← Back to branch summary

~malept/ubuntu/lucid/python2.6/dev-dependency-fix

« back to all changes in this revision

Viewing changes to Doc/library/stringio.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-02-13 12:51:00 UTC
  • Revision ID: james.westby@ubuntu.com-20090213125100-uufgcb9yeqzujpqw
Tags: upstream-2.6.1
Import upstream version 2.6.1

Show diffs side-by-side

added added

removed removed

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