Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libstring.tex @ 5818:3468ea8645ca legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
AMK's megapatch: * \bcode, \ecode added everywhere * \label{module-foo} added everywhere * A few \seealso sections added. * Indentation fixed inside verbatim in lib*tex files
author Guido van Rossum <guido@python.org>
date Thu, 17 Jul 1997 16:34:52 +0000
parents cd1ae62ed2cf
children bb8c3004d758
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
1 \section{Standard Module \sectcode{string}}
5818
3468ea8645ca AMK's megapatch:
Guido van Rossum <guido@python.org>
parents: 5683
diff changeset
2 \label{module-string}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
3
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
4 \stmodindex{string}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
5
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
6 This module defines some constants useful for checking character
2463
e764b78a704f add warning about strop
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
7 classes and some useful string functions. See the modules
e764b78a704f add warning about strop
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
8 \code{regex} and \code{regsub} for string functions based on regular
e764b78a704f add warning about strop
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
9 expressions.
e764b78a704f add warning about strop
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
10
e764b78a704f add warning about strop
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
11 The constants defined in this module are are:
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
12
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
13 \renewcommand{\indexsubitem}{(data in module string)}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
14 \begin{datadesc}{digits}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
15 The string \code{'0123456789'}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
16 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
17
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
18 \begin{datadesc}{hexdigits}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
19 The string \code{'0123456789abcdefABCDEF'}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
20 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
21
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
22 \begin{datadesc}{letters}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
23 The concatenation of the strings \code{lowercase} and
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
24 \code{uppercase} described below.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
25 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
26
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
27 \begin{datadesc}{lowercase}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
28 A string containing all the characters that are considered lowercase
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
29 letters. On most systems this is the string
2453
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 1789
diff changeset
30 \code{'abcdefghijklmnopqrstuvwxyz'}. Do not change its definition ---
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
31 the effect on the routines \code{upper} and \code{swapcase} is
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
32 undefined.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
33 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
34
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
35 \begin{datadesc}{octdigits}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
36 The string \code{'01234567'}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
37 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
38
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
39 \begin{datadesc}{uppercase}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
40 A string containing all the characters that are considered uppercase
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
41 letters. On most systems this is the string
2453
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 1789
diff changeset
42 \code{'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}. Do not change its definition ---
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
43 the effect on the routines \code{lower} and \code{swapcase} is
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
44 undefined.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
45 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
46
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
47 \begin{datadesc}{whitespace}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
48 A string containing all characters that are considered whitespace.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
49 On most systems this includes the characters space, tab, linefeed,
2453
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 1789
diff changeset
50 return, formfeed, and vertical tab. Do not change its definition ---
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
51 the effect on the routines \code{strip} and \code{split} is
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
52 undefined.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
53 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
54
2463
e764b78a704f add warning about strop
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
55 The functions defined in this module are:
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
56
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
57 \renewcommand{\indexsubitem}{(in module string)}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
58
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
59 \begin{funcdesc}{atof}{s}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
60 Convert a string to a floating point number. The string must have
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
61 the standard syntax for a floating point literal in Python, optionally
5245
c5fd327057c6 Add cross-refs for int() to atoi() etc.
Guido van Rossum <guido@python.org>
parents: 5212
diff changeset
62 preceded by a sign (\samp{+} or \samp{-}). Note that this behaves
c5fd327057c6 Add cross-refs for int() to atoi() etc.
Guido van Rossum <guido@python.org>
parents: 5212
diff changeset
63 identical to the built-in function \code{float()} when passed a string.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
64 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
65
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
66 \begin{funcdesc}{atoi}{s\optional{\, base}}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
67 Convert string \var{s} to an integer in the given \var{base}. The
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
68 string must consist of one or more digits, optionally preceded by a
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
69 sign (\samp{+} or \samp{-}). The \var{base} defaults to 10. If it is
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
70 0, a default base is chosen depending on the leading characters of the
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
71 string (after stripping the sign): \samp{0x} or \samp{0X} means 16,
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
72 \samp{0} means 8, anything else means 10. If \var{base} is 16, a
5245
c5fd327057c6 Add cross-refs for int() to atoi() etc.
Guido van Rossum <guido@python.org>
parents: 5212
diff changeset
73 leading \samp{0x} or \samp{0X} is always accepted. Note that when
c5fd327057c6 Add cross-refs for int() to atoi() etc.
Guido van Rossum <guido@python.org>
parents: 5212
diff changeset
74 invoked without \var{base} or with \var{base} set to 10, this behaves
c5fd327057c6 Add cross-refs for int() to atoi() etc.
Guido van Rossum <guido@python.org>
parents: 5212
diff changeset
75 identical to the built-in function \code{int()} when passed a string.
c5fd327057c6 Add cross-refs for int() to atoi() etc.
Guido van Rossum <guido@python.org>
parents: 5212
diff changeset
76 (Also note: for a more flexible interpretation of numeric literals,
c5fd327057c6 Add cross-refs for int() to atoi() etc.
Guido van Rossum <guido@python.org>
parents: 5212
diff changeset
77 use the built-in function \code{eval()}.)
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
78 \bifuncindex{eval}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
79 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
80
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
81 \begin{funcdesc}{atol}{s\optional{\, base}}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
82 Convert string \var{s} to a long integer in the given \var{base}. The
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
83 string must consist of one or more digits, optionally preceded by a
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
84 sign (\samp{+} or \samp{-}). The \var{base} argument has the same
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
85 meaning as for \code{atoi()}. A trailing \samp{l} or \samp{L} is not
5245
c5fd327057c6 Add cross-refs for int() to atoi() etc.
Guido van Rossum <guido@python.org>
parents: 5212
diff changeset
86 allowed, except if the base is 0. Note that when invoked without
c5fd327057c6 Add cross-refs for int() to atoi() etc.
Guido van Rossum <guido@python.org>
parents: 5212
diff changeset
87 \var{base} or with \var{base} set to 10, this behaves identical to the
c5fd327057c6 Add cross-refs for int() to atoi() etc.
Guido van Rossum <guido@python.org>
parents: 5212
diff changeset
88 built-in function \code{long()} when passed a string.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
89 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
90
3996
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
91 \begin{funcdesc}{capitalize}{word}
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
92 Capitalize the first character of the argument.
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
93 \end{funcdesc}
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
94
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
95 \begin{funcdesc}{capwords}{s}
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
96 Split the argument into words using \code{split}, capitalize each word
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
97 using \code{capitalize}, and join the capitalized words using
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
98 \code{join}. Note that this replaces runs of whitespace characters by
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
99 a single space. (See also \code{regsub.capwords()} for a version
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
100 that doesn't change the delimiters, and lets you specify a word
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
101 separator.)
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
102 \end{funcdesc}
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
103
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
104 \begin{funcdesc}{expandtabs}{s\, tabsize}
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2463
diff changeset
105 Expand tabs in a string, i.e.\ replace them by one or more spaces,
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
106 depending on the current column and the given tab size. The column
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
107 number is reset to zero after each newline occurring in the string.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
108 This doesn't understand other non-printing characters or escape
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
109 sequences.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
110 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
111
5188
3ec3d8807f9e Add optional 4th argument to [r]find and [r]index (end of slice).
Guido van Rossum <guido@python.org>
parents: 3996
diff changeset
112 \begin{funcdesc}{find}{s\, sub\optional{\, start\optional{\,end}}}
3ec3d8807f9e Add optional 4th argument to [r]find and [r]index (end of slice).
Guido van Rossum <guido@python.org>
parents: 3996
diff changeset
113 Return the lowest index in \var{s} not smaller than \var{start} and not
3ec3d8807f9e Add optional 4th argument to [r]find and [r]index (end of slice).
Guido van Rossum <guido@python.org>
parents: 3996
diff changeset
114 greater than \var{end} where the substring \var{sub} is found. Return
3ec3d8807f9e Add optional 4th argument to [r]find and [r]index (end of slice).
Guido van Rossum <guido@python.org>
parents: 3996
diff changeset
115 \code{-1} when \var{sub} does not occur as a substring of \var{s} with
3ec3d8807f9e Add optional 4th argument to [r]find and [r]index (end of slice).
Guido van Rossum <guido@python.org>
parents: 3996
diff changeset
116 index at least \var{start} and less than \var{end}.
1767
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1750
diff changeset
117 If \var{start} is omitted, it defaults to \code{0}. If \var{start} is
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
118 negative, \code{len(\var{s})} is added.
5188
3ec3d8807f9e Add optional 4th argument to [r]find and [r]index (end of slice).
Guido van Rossum <guido@python.org>
parents: 3996
diff changeset
119 If \var{end} is omitted, it defaults to \code{len(\var{s})}. If
3ec3d8807f9e Add optional 4th argument to [r]find and [r]index (end of slice).
Guido van Rossum <guido@python.org>
parents: 3996
diff changeset
120 \var{end} is negative, \code{len(\var{s})} is added.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
121 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
122
5188
3ec3d8807f9e Add optional 4th argument to [r]find and [r]index (end of slice).
Guido van Rossum <guido@python.org>
parents: 3996
diff changeset
123 \begin{funcdesc}{rfind}{s\, sub\optional{\, start\optional{\,end}}}
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2463
diff changeset
124 Like \code{find} but find the highest index.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
125 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
126
5188
3ec3d8807f9e Add optional 4th argument to [r]find and [r]index (end of slice).
Guido van Rossum <guido@python.org>
parents: 3996
diff changeset
127 \begin{funcdesc}{index}{s\, sub\optional{\, start\optional{\,end}}}
1789
43ae7fcd7835 * Doc/libstring.tex (section{Standard Module \sectcode{string}}):
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
128 Like \code{find} but raise \code{ValueError} when the substring is
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
129 not found.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
130 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
131
5188
3ec3d8807f9e Add optional 4th argument to [r]find and [r]index (end of slice).
Guido van Rossum <guido@python.org>
parents: 3996
diff changeset
132 \begin{funcdesc}{rindex}{s\, sub\optional{\, start\optional{\,end}}}
1789
43ae7fcd7835 * Doc/libstring.tex (section{Standard Module \sectcode{string}}):
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
133 Like \code{rfind} but raise \code{ValueError} when the substring is
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
134 not found.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
135 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
136
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
137 \begin{funcdesc}{count}{s\, sub\optional{\, start}}
1750
0b645726957e libsocket.tex: send[to] returns nbytes.
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
138 Return the number of (non-overlapping) occurrences of substring
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
139 \var{sub} in string \var{s} with index at least \var{start}.
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
140 If \var{start} is omitted, it defaults to \code{0}. If \var{start} is
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
141 negative, \code{len(\var{s})} is added.
1750
0b645726957e libsocket.tex: send[to] returns nbytes.
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
142 \end{funcdesc}
0b645726957e libsocket.tex: send[to] returns nbytes.
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
143
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
144 \begin{funcdesc}{lower}{s}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
145 Convert letters to lower case.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
146 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
147
3858
8b71ea5dacc8 Added maketrans() and optional 3rd arg to translate() (chars to delete).
Guido van Rossum <guido@python.org>
parents: 3379
diff changeset
148 \begin{funcdesc}{maketrans}{from, to}
8b71ea5dacc8 Added maketrans() and optional 3rd arg to translate() (chars to delete).
Guido van Rossum <guido@python.org>
parents: 3379
diff changeset
149 Return a translation table suitable for passing to \code{string.translate}
8b71ea5dacc8 Added maketrans() and optional 3rd arg to translate() (chars to delete).
Guido van Rossum <guido@python.org>
parents: 3379
diff changeset
150 or \code{regex.compile}, that will map each character in \var{from}
8b71ea5dacc8 Added maketrans() and optional 3rd arg to translate() (chars to delete).
Guido van Rossum <guido@python.org>
parents: 3379
diff changeset
151 into the character at the same position in \var{to}; \var{from} and
8b71ea5dacc8 Added maketrans() and optional 3rd arg to translate() (chars to delete).
Guido van Rossum <guido@python.org>
parents: 3379
diff changeset
152 \var{to} must have the same length.
8b71ea5dacc8 Added maketrans() and optional 3rd arg to translate() (chars to delete).
Guido van Rossum <guido@python.org>
parents: 3379
diff changeset
153 \end{funcdesc}
8b71ea5dacc8 Added maketrans() and optional 3rd arg to translate() (chars to delete).
Guido van Rossum <guido@python.org>
parents: 3379
diff changeset
154
3996
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
155 \begin{funcdesc}{split}{s\optional{\, sep\optional{\, maxsplit}}}
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
156 Return a list of the words of the string \var{s}. If the optional
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
157 second argument \var{sep} is absent or \code{None}, the words are
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
158 separated by arbitrary strings of whitespace characters (space, tab,
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
159 newline, return, formfeed). If the second argument \var{sep} is
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
160 present and not \code{None}, it specifies a string to be used as the
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
161 word separator. The returned list will then have one more items than
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
162 the number of non-overlapping occurrences of the separator in the
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
163 string. The optional third argument \var{maxsplit} defaults to 0. If
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
164 it is nonzero, at most \var{maxsplit} number of splits occur, and the
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
165 remainder of the string is returned as the final element of the list
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
166 (thus, the list will have at most \code{\var{maxsplit}+1} elements).
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
167 (See also \code{regsub.split()} for a version that allows specifying a
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
168 regular expression as the separator.)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
169 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
170
3996
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
171 \begin{funcdesc}{splitfields}{s\optional{\, sep\optional{\, maxsplit}}}
5683
cd1ae62ed2cf Grammar (AMK).
Guido van Rossum <guido@python.org>
parents: 5245
diff changeset
172 This function behaves identically to \code{split}. (In the past,
3996
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
173 \code{split} was only used with one argument, while \code{splitfields}
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
174 was only used with two arguments.)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
175 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
176
3996
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
177 \begin{funcdesc}{join}{words\optional{\, sep}}
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
178 Concatenate a list or tuple of words with intervening occurrences of
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
179 \var{sep}. The default value for \var{sep} is a single space character.
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
180 It is always true that
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
181 \code{string.join(string.split(\var{s}, \var{sep}), \var{sep})}
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
182 equals \var{s}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
183 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
184
3996
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
185 \begin{funcdesc}{joinfields}{words\optional{\, sep}}
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
186 This function behaves identical to \code{join}. (In the past,
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
187 \code{join} was only used with one argument, while \code{joinfields}
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
188 was only used with two arguments.)
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
189 \end{funcdesc}
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
190
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
191 \begin{funcdesc}{lstrip}{s}
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
192 Remove leading whitespace from the string \var{s}.
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
193 \end{funcdesc}
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
194
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
195 \begin{funcdesc}{rstrip}{s}
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
196 Remove trailing whitespace from the string \var{s}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
197 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
198
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
199 \begin{funcdesc}{strip}{s}
3996
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
200 Remove leading and trailing whitespace from the string \var{s}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
201 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
202
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
203 \begin{funcdesc}{swapcase}{s}
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2463
diff changeset
204 Convert lower case letters to upper case and vice versa.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
205 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
206
3858
8b71ea5dacc8 Added maketrans() and optional 3rd arg to translate() (chars to delete).
Guido van Rossum <guido@python.org>
parents: 3379
diff changeset
207 \begin{funcdesc}{translate}{s, table\optional{, deletechars}}
8b71ea5dacc8 Added maketrans() and optional 3rd arg to translate() (chars to delete).
Guido van Rossum <guido@python.org>
parents: 3379
diff changeset
208 Delete all characters from \var{s} that are in \var{deletechars} (if present), and
8b71ea5dacc8 Added maketrans() and optional 3rd arg to translate() (chars to delete).
Guido van Rossum <guido@python.org>
parents: 3379
diff changeset
209 then translate the characters using \var{table}, which must be
3084
91c1bb75e945 added string.translate(s, table)
Guido van Rossum <guido@python.org>
parents: 2647
diff changeset
210 a 256-character string giving the translation for each character
3858
8b71ea5dacc8 Added maketrans() and optional 3rd arg to translate() (chars to delete).
Guido van Rossum <guido@python.org>
parents: 3379
diff changeset
211 value, indexed by its ordinal.
3084
91c1bb75e945 added string.translate(s, table)
Guido van Rossum <guido@python.org>
parents: 2647
diff changeset
212 \end{funcdesc}
91c1bb75e945 added string.translate(s, table)
Guido van Rossum <guido@python.org>
parents: 2647
diff changeset
213
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
214 \begin{funcdesc}{upper}{s}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
215 Convert letters to upper case.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
216 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
217
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
218 \begin{funcdesc}{ljust}{s\, width}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
219 \funcline{rjust}{s\, width}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
220 \funcline{center}{s\, width}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
221 These functions respectively left-justify, right-justify and center a
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
222 string in a field of given width.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
223 They return a string that is at least
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
224 \var{width}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
225 characters wide, created by padding the string
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
226 \var{s}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
227 with spaces until the given width on the right, left or both sides.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
228 The string is never truncated.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
229 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
230
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
231 \begin{funcdesc}{zfill}{s\, width}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
232 Pad a numeric string on the left with zero digits until the given
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
233 width is reached. Strings starting with a sign are handled correctly.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
234 \end{funcdesc}
2463
e764b78a704f add warning about strop
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
235
5245
c5fd327057c6 Add cross-refs for int() to atoi() etc.
Guido van Rossum <guido@python.org>
parents: 5212
diff changeset
236 \begin{funcdesc}{replace}{str, old, new\optional{, maxsplit}}
5212
1f38d5fb3d23 Added docs for replace() and replace1().
Guido van Rossum <guido@python.org>
parents: 5188
diff changeset
237 Return a copy of string \var{str} with all occurrences of substring
5245
c5fd327057c6 Add cross-refs for int() to atoi() etc.
Guido van Rossum <guido@python.org>
parents: 5212
diff changeset
238 \var{old} replaced by \var{new}. If the optional argument
c5fd327057c6 Add cross-refs for int() to atoi() etc.
Guido van Rossum <guido@python.org>
parents: 5212
diff changeset
239 \var{maxsplit} is given, the first \var{maxsplit} occurrences are
c5fd327057c6 Add cross-refs for int() to atoi() etc.
Guido van Rossum <guido@python.org>
parents: 5212
diff changeset
240 replaced.
5212
1f38d5fb3d23 Added docs for replace() and replace1().
Guido van Rossum <guido@python.org>
parents: 5188
diff changeset
241 \end{funcdesc}
1f38d5fb3d23 Added docs for replace() and replace1().
Guido van Rossum <guido@python.org>
parents: 5188
diff changeset
242
2463
e764b78a704f add warning about strop
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
243 This module is implemented in Python. Much of its functionality has
e764b78a704f add warning about strop
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
244 been reimplemented in the built-in module \code{strop}. However, you
e764b78a704f add warning about strop
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
245 should \emph{never} import the latter module directly. When
e764b78a704f add warning about strop
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
246 \code{string} discovers that \code{strop} exists, it transparently
e764b78a704f add warning about strop
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
247 replaces parts of itself with the implementation from \code{strop}.
e764b78a704f add warning about strop
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
248 After initialization, there is \emph{no} overhead in using
e764b78a704f add warning about strop
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
249 \code{string} instead of \code{strop}.
e764b78a704f add warning about strop
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
250 \bimodindex{strop}