mirror of
https://github.com/python/cpython.git
synced 2025-11-04 07:31:38 +00:00
82 lines
3 KiB
TeX
82 lines
3 KiB
TeX
\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.
|
|
|
|
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}
|
|
|
|
|
|
\section{\module{cStringIO} ---
|
|
Faster version of \module{StringIO}}
|
|
|
|
\declaremodule{builtin}{cStringIO}
|
|
\modulesynopsis{Faster version of \module{StringIO}, but not
|
|
subclassable.}
|
|
\moduleauthor{Jim Fulton}{jfulton@digicool.com}
|
|
\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
|
|
|
|
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.
|
|
|
|
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.
|