Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libstringio.tex @ 17581:c1937faabb23 2.1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added support for optional explanation parameter to the \versionadded macro. Refactored do_cmd_versionadded() and do_cmd_versionchanged() to do most of the work in a helper function, with the do_cmd_*() wrappers just supplying a portion of the replacement text.
author Fred Drake <fdrake@acm.org>
date Wed, 18 Apr 2001 17:29:14 +0000
parents 68de9185b41e
children 33b4357aebb8
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.
15443
68de9185b41e Added information on the use of Unicode with the StringIO and cStringIO
Fred Drake <fdrake@acm.org>
parents: 10661
diff changeset
17
68de9185b41e Added information on the use of Unicode with the StringIO and cStringIO
Fred Drake <fdrake@acm.org>
parents: 10661
diff changeset
18 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
19 strings, but mixing the two may take some care. If both are used,
68de9185b41e Added information on the use of Unicode with the StringIO and cStringIO
Fred Drake <fdrake@acm.org>
parents: 10661
diff changeset
20 8-bit strings that cannot be interpreted as 7-bit \ASCII{} (i.e., that
68de9185b41e Added information on the use of Unicode with the StringIO and cStringIO
Fred Drake <fdrake@acm.org>
parents: 10661
diff changeset
21 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
22 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
23 \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
24
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
25 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
26 mention:
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
27
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
28 \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
29 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
30 \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
31 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
32 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
33 \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
34
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
35 \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
36 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
37 \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
38
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
39
8918
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8730
diff changeset
40 \section{\module{cStringIO} ---
10661
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
41 Faster version of \module{StringIO}}
10240
359244fa6b52 Use current approach to record documentation author.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
42
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
43 \declaremodule{builtin}{cStringIO}
10661
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
44 \modulesynopsis{Faster version of \module{StringIO}, but not
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
45 subclassable.}
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
46 \moduleauthor{Jim Fulton}{jfulton@digicool.com}
10240
359244fa6b52 Use current approach to record documentation author.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
47 \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
48
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
49 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
50 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
51 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
52 \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
53
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
54 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
55 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
56 subclassing. Use the original \refmodule{StringIO} module in that case.
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
57
15443
68de9185b41e Added information on the use of Unicode with the StringIO and cStringIO
Fred Drake <fdrake@acm.org>
parents: 10661
diff changeset
58 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
59 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
60 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
61
10661
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
62 The following data objects are provided as well:
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
63
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
64
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
65 \begin{datadesc}{InputType}
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
66 The type object of the objects created by calling
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
67 \function{StringIO} with a string parameter.
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
68 \end{datadesc}
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
69
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
70 \begin{datadesc}{OutputType}
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
71 The type object of the objects returned by calling
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
72 \function{StringIO} with no parameters.
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
73 \end{datadesc}
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
74
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
75
a71c636b85d1 Small nits, more hyperlinks.
Fred Drake <fdrake@acm.org>
parents: 10240
diff changeset
76 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
77 more information.