Doc/lib/libstringio.tex

   1 \section{\module{StringIO} ---
   2          Read and write strings as files}
   3
   4 \declaremodule{standard}{StringIO}
   5 \modulesynopsis{Read and write strings as if they were files.}
   6
   7
   8 This module implements a file-like class, \class{StringIO},
   9 that reads and writes a string buffer (also known as \emph{memory
  10 files}).  See the description of file objects for operations (section
  11 \ref{bltin-file-objects}).
  12
  13 \begin{classdesc}{StringIO}{\optional{buffer}}
  14 When a \class{StringIO} object is created, it can be initialized
  15 to an existing string by passing the string to the constructor.
  16 If no string is given, the \class{StringIO} will start empty.
  17 In both cases, the initial file position starts at zero.
  18
  19 The \class{StringIO} object can accept either Unicode or 8-bit
  20 strings, but mixing the two may take some care.  If both are used,
  21 8-bit strings that cannot be interpreted as 7-bit \ASCII{} (that
  22 use the 8th bit) will cause a \exception{UnicodeError} to be raised
  23 when \method{getvalue()} is called.
  24 \end{classdesc}
  25
  26 The following methods of \class{StringIO} objects require special
  27 mention:
  28
  29 \begin{methoddesc}{getvalue}{}
  30 Retrieve the entire contents of the ``file'' at any time before the
  31 \class{StringIO} object's \method{close()} method is called.  See the
  32 note above for information about mixing Unicode and 8-bit strings;
  33 such mixing can cause this method to raise \exception{UnicodeError}.
  34 \end{methoddesc}
  35
  36 \begin{methoddesc}{close}{}
  37 Free the memory buffer.
  38 \end{methoddesc}
  39
  40 Example usage:
  41
  42 \begin{verbatim}
  43 import StringIO
  44
  45 output = StringIO.StringIO()
  46 output.write('First line.\n')
  47 print >>output, 'Second line.'
  48
  49 # Retrieve file contents -- this will be
  50 # 'First line.\nSecond line.\n'
  51 contents = output.getvalue()
  52
  53 # Close object and discard memory buffer --
  54 # .getvalue() will now raise an exception.
  55 output.close()
  56 \end{verbatim}
  57
  58
  59 \section{\module{cStringIO} ---
  60          Faster version of \module{StringIO}}
  61
  62 \declaremodule{builtin}{cStringIO}
  63 \modulesynopsis{Faster version of \module{StringIO}, but not
  64                 subclassable.}
  65 \moduleauthor{Jim Fulton}{jim@zope.com}
  66 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
  67
  68 The module \module{cStringIO} provides an interface similar to that of
  69 the \refmodule{StringIO} module.  Heavy use of \class{StringIO.StringIO}
  70 objects can be made more efficient by using the function
  71 \function{StringIO()} from this module instead.
  72
  73 Since this module provides a factory function which returns objects of
  74 built-in types, there's no way to build your own version using
  75 subclassing.  Use the original \refmodule{StringIO} module in that case.
  76
  77 Unlike the memory files implemented by the \refmodule{StringIO}
  78 module, those provided by this module are not able to accept Unicode
  79 strings that cannot be encoded as plain \ASCII{} strings.
  80
  81 Another difference from the \refmodule{StringIO} module is that calling
  82 \function{StringIO()} with a string parameter creates a read-only object.
  83 Unlike an object created without a string parameter, it does not have
  84 write methods.  These objects are not generally visible.  They turn up in
  85 tracebacks as \class{StringI} and \class{StringO}.
  86
  87 The following data objects are provided as well:
  88
  89
  90 \begin{datadesc}{InputType}
  91   The type object of the objects created by calling
  92   \function{StringIO} with a string parameter.
  93 \end{datadesc}
  94
  95 \begin{datadesc}{OutputType}
  96   The type object of the objects returned by calling
  97   \function{StringIO} with no parameters.
  98 \end{datadesc}
  99
 100
 101 There is a C API to the module as well; refer to the module source for
 102 more information.
 103
 104 Example usage:
 105
 106 \begin{verbatim}
 107 import cStringIO
 108
 109 output = cStringIO.StringIO()
 110 output.write('First line.\n')
 111 print >>output, 'Second line.'
 112
 113 # Retrieve file contents -- this will be
 114 # 'First line.\nSecond line.\n'
 115 contents = output.getvalue()
 116
 117 # Close object and discard memory buffer --
 118 # .getvalue() will now raise an exception.
 119 output.close()
 120 \end{verbatim}
 121