Mercurial > cpython-lru_cache-weakref
annotate Doc/lib/libstringio.tex @ 39496:352ffe77b71d legacy-trunk
Patch #1535500: fix segfault in BZ2File.writelines and make sure it
raises the correct exceptions.
| author | Georg Brandl <georg@python.org> |
|---|---|
| date | Mon, 14 Aug 2006 21:42:55 +0000 |
| parents | 61c0fe48376a |
| children | 9918989b733b |
| rev | line source |
|---|---|
| 8918 | 1 \section{\module{StringIO} --- |
| 10661 | 2 Read and write strings as files} |
| 3 | |
|
8730
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
4 \declaremodule{standard}{StringIO} |
|
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
5 \modulesynopsis{Read and write strings as if they were files.} |
|
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
6 |
|
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
7 |
|
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
8 This module implements a file-like class, \class{StringIO}, |
|
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
9 that reads and writes a string buffer (also known as \emph{memory |
|
15443
68de9185b41e
Added information on the use of Unicode with the StringIO and cStringIO
Fred Drake <fdrake@acm.org>
parents:
10661
diff
changeset
|
10 files}). See the description of file objects for operations (section |
| 10661 | 11 \ref{bltin-file-objects}). |
|
8730
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
12 |
|
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
13 \begin{classdesc}{StringIO}{\optional{buffer}} |
|
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
14 When a \class{StringIO} object is created, it can be initialized |
|
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
15 to an existing string by passing the string to the constructor. |
|
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
16 If no string is given, the \class{StringIO} will start empty. |
|
34900
dad2b6204974
SF bug #1180392: StringIO's docs should mention overwriting of initial value
Raymond Hettinger <python@rcn.com>
parents:
31363
diff
changeset
|
17 In both cases, the initial file position starts at zero. |
|
15443
68de9185b41e
Added information on the use of Unicode with the StringIO and cStringIO
Fred Drake <fdrake@acm.org>
parents:
10661
diff
changeset
|
18 |
|
68de9185b41e
Added information on the use of Unicode with the StringIO and cStringIO
Fred Drake <fdrake@acm.org>
parents:
10661
diff
changeset
|
19 The \class{StringIO} object can accept either Unicode or 8-bit |
|
68de9185b41e
Added information on the use of Unicode with the StringIO and cStringIO
Fred Drake <fdrake@acm.org>
parents:
10661
diff
changeset
|
20 strings, but mixing the two may take some care. If both are used, |
|
18416
33b4357aebb8
Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents:
15443
diff
changeset
|
21 8-bit strings that cannot be interpreted as 7-bit \ASCII{} (that |
|
15443
68de9185b41e
Added information on the use of Unicode with the StringIO and cStringIO
Fred Drake <fdrake@acm.org>
parents:
10661
diff
changeset
|
22 use the 8th bit) will cause a \exception{UnicodeError} to be raised |
|
68de9185b41e
Added information on the use of Unicode with the StringIO and cStringIO
Fred Drake <fdrake@acm.org>
parents:
10661
diff
changeset
|
23 when \method{getvalue()} is called. |
|
8730
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
24 \end{classdesc} |
|
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
25 |
|
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
26 The following methods of \class{StringIO} objects require special |
|
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
27 mention: |
|
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
28 |
|
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
29 \begin{methoddesc}{getvalue}{} |
|
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
30 Retrieve the entire contents of the ``file'' at any time before the |
|
15443
68de9185b41e
Added information on the use of Unicode with the StringIO and cStringIO
Fred Drake <fdrake@acm.org>
parents:
10661
diff
changeset
|
31 \class{StringIO} object's \method{close()} method is called. See the |
|
68de9185b41e
Added information on the use of Unicode with the StringIO and cStringIO
Fred Drake <fdrake@acm.org>
parents:
10661
diff
changeset
|
32 note above for information about mixing Unicode and 8-bit strings; |
|
68de9185b41e
Added information on the use of Unicode with the StringIO and cStringIO
Fred Drake <fdrake@acm.org>
parents:
10661
diff
changeset
|
33 such mixing can cause this method to raise \exception{UnicodeError}. |
|
8730
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
34 \end{methoddesc} |
|
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
35 |
|
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
36 \begin{methoddesc}{close}{} |
|
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
37 Free the memory buffer. |
|
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
38 \end{methoddesc} |
|
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
39 |
| 39211 | 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 | |
|
8730
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
58 |
| 8918 | 59 \section{\module{cStringIO} --- |
| 10661 | 60 Faster version of \module{StringIO}} |
|
10240
359244fa6b52
Use current approach to record documentation author.
Fred Drake <fdrake@acm.org>
parents:
8918
diff
changeset
|
61 |
|
8730
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
62 \declaremodule{builtin}{cStringIO} |
| 10661 | 63 \modulesynopsis{Faster version of \module{StringIO}, but not |
| 64 subclassable.} | |
|
31363
f7a05ab50d3b
Fix some digicool addresses I noticed
Andrew M. Kuchling <amk@amk.ca>
parents:
30127
diff
changeset
|
65 \moduleauthor{Jim Fulton}{jim@zope.com} |
|
10240
359244fa6b52
Use current approach to record documentation author.
Fred Drake <fdrake@acm.org>
parents:
8918
diff
changeset
|
66 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} |
|
8730
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
67 |
|
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
68 The module \module{cStringIO} provides an interface similar to that of |
| 10661 | 69 the \refmodule{StringIO} module. Heavy use of \class{StringIO.StringIO} |
|
8730
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
70 objects can be made more efficient by using the function |
|
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
71 \function{StringIO()} from this module instead. |
|
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
72 |
|
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
73 Since this module provides a factory function which returns objects of |
|
8a306dfd9f33
Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff
changeset
|
74 built-in types, there's no way to build your own version using |
| 10661 | 75 subclassing. Use the original \refmodule{StringIO} module in that case. |
| 76 | |
|
15443
68de9185b41e
Added information on the use of Unicode with the StringIO and cStringIO
Fred Drake <fdrake@acm.org>
parents:
10661
diff
changeset
|
77 Unlike the memory files implemented by the \refmodule{StringIO} |
|
68de9185b41e
Added information on the use of Unicode with the StringIO and cStringIO
Fred Drake <fdrake@acm.org>
parents:
10661
diff
changeset
|
78 module, those provided by this module are not able to accept Unicode |
|
68de9185b41e
Added information on the use of Unicode with the StringIO and cStringIO
Fred Drake <fdrake@acm.org>
parents:
10661
diff
changeset
|
79 strings that cannot be encoded as plain \ASCII{} strings. |
|
68de9185b41e
Added information on the use of Unicode with the StringIO and cStringIO
Fred Drake <fdrake@acm.org>
parents:
10661
diff
changeset
|
80 |
|
27546
bd63f28ce7a8
SF bug #671447: StringIO doc doesn't say it's sometimes read-only.
Raymond Hettinger <python@rcn.com>
parents:
18416
diff
changeset
|
81 Another difference from the \refmodule{StringIO} module is that calling |
|
bd63f28ce7a8
SF bug #671447: StringIO doc doesn't say it's sometimes read-only.
Raymond Hettinger <python@rcn.com>
parents:
18416
diff
changeset
|
82 \function{StringIO()} with a string parameter creates a read-only object. |
|
bd63f28ce7a8
SF bug #671447: StringIO doc doesn't say it's sometimes read-only.
Raymond Hettinger <python@rcn.com>
parents:
18416
diff
changeset
|
83 Unlike an object created without a string parameter, it does not have |
|
30127
2c6f92cddbad
add a statement identifying StringI and StringO objects.
Skip Montanaro <skip@pobox.com>
parents:
27546
diff
changeset
|
84 write methods. These objects are not generally visible. They turn up in |
|
2c6f92cddbad
add a statement identifying StringI and StringO objects.
Skip Montanaro <skip@pobox.com>
parents:
27546
diff
changeset
|
85 tracebacks as \class{StringI} and \class{StringO}. |
|
27546
bd63f28ce7a8
SF bug #671447: StringIO doc doesn't say it's sometimes read-only.
Raymond Hettinger <python@rcn.com>
parents:
18416
diff
changeset
|
86 |
| 10661 | 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. | |
| 39211 | 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 |