rest25/library/stringio.rst => rest262/library/stringio.rst
3===================================================
4
5.. module:: StringIO
6   :synopsis: Read and write strings as if they were files.
7
8
9This module implements a file-like class, :class:`StringIO`, that reads and
10writes a string buffer (also known as *memory files*).  See the description of
n11-file objects for operations (section :ref:`bltin-file-objects`).
n11+file objects for operations (section :ref:`bltin-file-objects`). (For
12+standard strings, see :class:`str` and :class:`unicode`.)
12
13
14.. class:: StringIO([buffer])
15
16   When a :class:`StringIO` object is created, it can be initialized to an existing
17   string by passing the string to the constructor. If no string is given, the
18   :class:`StringIO` will start empty. In both cases, the initial file position
19   starts at zero.
31   Retrieve the entire contents of the "file" at any time before the
32   :class:`StringIO` object's :meth:`close` method is called.  See the note above
33   for information about mixing Unicode and 8-bit strings; such mixing can cause
34   this method to raise :exc:`UnicodeError`.
35
36
37.. method:: StringIO.close()
38
n39-   Free the memory buffer.
n40+   Free the memory buffer.  Attempting to do further operations with a closed
41+   :class:`StringIO` object will raise a :exc:`ValueError`.
40
41Example usage::
42
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
n53-   # Close object and discard memory buffer -- 
n55+   # Close object and discard memory buffer --
54   # .getvalue() will now raise an exception.
55   output.close()
56
57
58:mod:`cStringIO` --- Faster version of :mod:`StringIO`
59======================================================
60
61.. module:: cStringIO
71
72Since this module provides a factory function which returns objects of built-in
73types, there's no way to build your own version using subclassing.  Use the
74original :mod:`StringIO` module in that case.
75
76Unlike the memory files implemented by the :mod:`StringIO` module, those
77provided by this module are not able to accept Unicode strings that cannot be
78encoded as plain ASCII strings.
n81+ 
82+Calling :func:`StringIO` with a Unicode string parameter populates
83+the object with the buffer representation of the Unicode string, instead of
84+encoding the string.
79
80Another difference from the :mod:`StringIO` module is that calling
81:func:`StringIO` with a string parameter creates a read-only object. Unlike an
82object created without a string parameter, it does not have write methods.
83These objects are not generally visible.  They turn up in tracebacks as
84:class:`StringI` and :class:`StringO`.
85
86The following data objects are provided as well:
107   output = cStringIO.StringIO()
108   output.write('First line.\n')
109   print >>output, 'Second line.'
110
111   # Retrieve file contents -- this will be
112   # 'First line.\nSecond line.\n'
113   contents = output.getvalue()
114
t115-   # Close object and discard memory buffer -- 
t121+   # Close object and discard memory buffer --
116   # .getvalue() will now raise an exception.
117   output.close()
118
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op