diff options
Diffstat (limited to 'Doc/lib/libstringio.tex')
-rw-r--r-- | Doc/lib/libstringio.tex | 125 |
1 files changed, 0 insertions, 125 deletions
diff --git a/Doc/lib/libstringio.tex b/Doc/lib/libstringio.tex deleted file mode 100644 index 73ff0e4..0000000 --- a/Doc/lib/libstringio.tex +++ /dev/null @@ -1,125 +0,0 @@ -\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}{jim@zope.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. - -Calling \function{StringIO()} with a Unicode string parameter populates -the object with the buffer representation of the Unicode string, instead of -encoding the string. - -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} - |