:mod:`cStringIO` --- Faster version of :mod:`StringIO`
======================================================

.. module:: cStringIO
   :synopsis: Faster version of StringIO, but not subclassable.
.. moduleauthor:: Jim Fulton <jim@zope.com>
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>


The module :mod:`cStringIO` provides an interface similar to that of the
:mod:`StringIO` module.  Heavy use of :class:`StringIO.StringIO` objects can be
made more efficient by using the function :func:`StringIO` from this module
instead.


.. function:: StringIO([s])

   Return a StringIO-like stream for reading or writing.

   Since this is a factory function which returns objects of built-in types,
   there's no way to build your own version using subclassing.  It's not
   possible to set attributes on it.  Use the original :mod:`StringIO` module in
   those cases.

   Unlike the :mod:`StringIO` module, this module is not able to accept Unicode
   strings that cannot be encoded as plain ASCII strings.

   Another difference from the :mod:`StringIO` module is that calling
   :func:`StringIO` with a string parameter creates a read-only object. Unlike an
   object created without a string parameter, it does not have write methods.
   These objects are not generally visible.  They turn up in tracebacks as
   :class:`StringI` and :class:`StringO`.



The following data objects are provided as well:


.. data:: InputType

   The type object of the objects created by calling :func:`StringIO` with a string
   parameter.


.. data:: OutputType

   The type object of the objects returned by calling :func:`StringIO` with no
   parameters.

There is a C API to the module as well; refer to the module source for  more
information.

Example usage::

   import cStringIO

   output = cStringIO.StringIO()
   output.write('First line.\n')
   print >>output, 'Second line.'

   # Retrieve file contents -- this will be
   # 'First line.\nSecond line.\n'
   contents = output.getvalue()

   # Close object and discard memory buffer --
   # .getvalue() will now raise an exception.
   output.close()