source: trunk/essentials/dev-lang/python/Doc/lib/libstringio.tex@ 3368

\section{\module{StringIO} ---
         Read and write strings as files}

\declaremodule{standard}{StringIO}
\modulesynopsis{Read and write strings as if they were files.}


This module implements a file-like class, \class{StringIO},
that reads and writes a string buffer (also known as \emph{memory
files}).  See the description of file objects for operations (section
\ref{bltin-file-objects}).

\begin{classdesc}{StringIO}{\optional{buffer}}
When a \class{StringIO} object is created, it can be initialized
to an existing string by passing the string to the constructor.
If no string is given, the \class{StringIO} will start empty.
In both cases, the initial file position starts at zero.

The \class{StringIO} object can accept either Unicode or 8-bit
strings, but mixing the two may take some care.  If both are used,
8-bit strings that cannot be interpreted as 7-bit \ASCII{} (that
use the 8th bit) will cause a \exception{UnicodeError} to be raised
when \method{getvalue()} is called.
\end{classdesc}

The following methods of \class{StringIO} objects require special
mention:

\begin{methoddesc}{getvalue}{}
Retrieve the entire contents of the ``file'' at any time before the
\class{StringIO} object's \method{close()} method is called.  See the
note above for information about mixing Unicode and 8-bit strings;
such mixing can cause this method to raise \exception{UnicodeError}.
\end{methoddesc}

\begin{methoddesc}{close}{}
Free the memory buffer.
\end{methoddesc}

Example usage:

\begin{verbatim}
import StringIO

output = StringIO.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()
\end{verbatim}


\section{\module{cStringIO} ---
         Faster version of \module{StringIO}}

\declaremodule{builtin}{cStringIO}
\modulesynopsis{Faster version of \module{StringIO}, but not
                subclassable.}
\moduleauthor{Jim Fulton}{[email protected]}
\sectionauthor{Fred L. Drake, Jr.}{[email protected]}

The module \module{cStringIO} provides an interface similar to that of
the \refmodule{StringIO} module.  Heavy use of \class{StringIO.StringIO}
objects can be made more efficient by using the function
\function{StringIO()} from this module instead.

Since this module provides a factory function which returns objects of
built-in types, there's no way to build your own version using
subclassing.  Use the original \refmodule{StringIO} module in that case.

Unlike the memory files implemented by the \refmodule{StringIO}
module, those provided by this module are not able to accept Unicode
strings that cannot be encoded as plain \ASCII{} strings.

Another difference from the \refmodule{StringIO} module is that calling
\function{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:


\begin{datadesc}{InputType}
  The type object of the objects created by calling
  \function{StringIO} with a string parameter.
\end{datadesc}

\begin{datadesc}{OutputType}
  The type object of the objects returned by calling
  \function{StringIO} with no parameters.
\end{datadesc}


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

Example usage:

\begin{verbatim}
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()
\end{verbatim}