Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libstringio.tex @ 39587:bbef2ecdee33 2.4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Patch #1540329: _hotshot.c fix backports.
author Georg Brandl <georg@python.org>
date Sat, 19 Aug 2006 07:48:06 +0000
parents dad2b6204974
children 61c0fe48376a
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8918
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8730
diff changeset
1 \section{\module{StringIO} ---
10661
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
2 Read and write strings as files}
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
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
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
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
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
40
8918
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8730
diff changeset
41 \section{\module{cStringIO} ---
10661
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
42 Faster version of \module{StringIO}}
10240
359244fa6b52 Use current approach to record documentation author.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
43
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
44 \declaremodule{builtin}{cStringIO}
10661
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
45 \modulesynopsis{Faster version of \module{StringIO}, but not
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
46 subclassable.}
31363
f7a05ab50d3b Fix some digicool addresses I noticed
Andrew M. Kuchling <amk@amk.ca>
parents: 30127
diff changeset
47 \moduleauthor{Jim Fulton}{jim@zope.com}
10240
359244fa6b52 Use current approach to record documentation author.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
48 \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
49
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
50 The module \module{cStringIO} provides an interface similar to that of
10661
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
51 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
52 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
53 \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
54
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
55 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
56 built-in types, there's no way to build your own version using
10661
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
57 subclassing. Use the original \refmodule{StringIO} module in that case.
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
58
15443
68de9185b41e Added information on the use of Unicode with the StringIO and cStringIO
Fred Drake <fdrake@acm.org>
parents: 10661
diff changeset
59 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
60 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
61 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
62
27546
bd63f28ce7a8 SF bug #671447: StringIO doc doesn't say it's sometimes read-only.
Raymond Hettinger <python@rcn.com>
parents: 18416
diff changeset
63 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
64 \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
65 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
66 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
67 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
68
10661
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
69 The following data objects are provided as well:
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
70
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
71
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
72 \begin{datadesc}{InputType}
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
73 The type object of the objects created by calling
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
74 \function{StringIO} with a string parameter.
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
75 \end{datadesc}
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
76
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
77 \begin{datadesc}{OutputType}
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
78 The type object of the objects returned by calling
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
79 \function{StringIO} with no parameters.
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
80 \end{datadesc}
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
81
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
82
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
83 There is a C API to the module as well; refer to the module source for
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
84 more information.