Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libstring.tex @ 10123:bc287c6cfa23 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Restructured a bit.
author Guido van Rossum <guido@python.org>
date Mon, 08 Feb 1999 22:27:18 +0000
parents e5d0df824bf3
children b30077c57348
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: 8716
diff changeset
1 \section{\module{string} ---
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
2 Common string operations.}
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8488
diff changeset
3 \declaremodule{standard}{string}
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8488
diff changeset
4
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8488
diff changeset
5 \modulesynopsis{Common string operations.}
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8488
diff changeset
6
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
7
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
8 This module defines some constants useful for checking character
6872
2d97fb1d06ca Fixed index module reference.
Fred Drake <fdrake@acm.org>
parents: 6493
diff changeset
9 classes and some useful string functions. See the module
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
10 \module{re}\refstmodindex{re} for string functions based on regular
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
11 expressions.
2463
e764b78a704f add warning about strop
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
12
e764b78a704f add warning about strop
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
13 The constants defined in this module are are:
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
14
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
15 \begin{datadesc}{digits}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
16 The string \code{'0123456789'}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
17 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
18
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
19 \begin{datadesc}{hexdigits}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
20 The string \code{'0123456789abcdefABCDEF'}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
21 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
22
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
23 \begin{datadesc}{letters}
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
24 The concatenation of the strings \function{lowercase()} and
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
25 \function{uppercase()} described below.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
26 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
27
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
28 \begin{datadesc}{lowercase}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
29 A string containing all the characters that are considered lowercase
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
30 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
31 \code{'abcdefghijklmnopqrstuvwxyz'}. Do not change its definition ---
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
32 the effect on the routines \function{upper()} and
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
33 \function{swapcase()} is undefined.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
34 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
35
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
36 \begin{datadesc}{octdigits}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
37 The string \code{'01234567'}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
38 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
39
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
40 \begin{datadesc}{uppercase}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
41 A string containing all the characters that are considered uppercase
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
42 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
43 \code{'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}. Do not change its definition ---
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
44 the effect on the routines \function{lower()} and
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
45 \function{swapcase()} is undefined.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
46 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
47
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
48 \begin{datadesc}{whitespace}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
49 A string containing all characters that are considered whitespace.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
50 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
51 return, formfeed, and vertical tab. Do not change its definition ---
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
52 the effect on the routines \function{strip()} and \function{split()}
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
53 is undefined.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
54 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
55
2463
e764b78a704f add warning about strop
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
56 The functions defined in this module are:
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
57
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}
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
60 Convert a string to a floating point number. The string must have
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
61 the standard syntax for a floating point literal in Python,
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
62 optionally preceded by a sign (\samp{+} or \samp{-}). Note that
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
63 this behaves identical to the built-in function
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
64 \function{float()}\bifuncindex{float} when passed a string.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
65 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
66
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
67 \begin{funcdesc}{atoi}{s\optional{, base}}
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
68 Convert string \var{s} to an integer in the given \var{base}. The
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
69 string must consist of one or more digits, optionally preceded by a
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
70 sign (\samp{+} or \samp{-}). The \var{base} defaults to 10. If it
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
71 is 0, a default base is chosen depending on the leading characters
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
72 of the string (after stripping the sign): \samp{0x} or \samp{0X}
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
73 means 16, \samp{0} means 8, anything else means 10. If \var{base}
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
74 is 16, a leading \samp{0x} or \samp{0X} is always accepted. Note
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
75 that when invoked without \var{base} or with \var{base} set to 10,
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
76 this behaves identical to the built-in function \function{int()}
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
77 when passed a string. (Also note: for a more flexible
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
78 interpretation of numeric literals, use the built-in function
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
79 \function{eval()}\bifuncindex{eval}.)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
80 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
81
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
82 \begin{funcdesc}{atol}{s\optional{, base}}
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
83 Convert string \var{s} to a long integer in the given \var{base}.
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
84 The string must consist of one or more digits, optionally preceded
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
85 by a sign (\samp{+} or \samp{-}). The \var{base} argument has the
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
86 same meaning as for \function{atoi()}. A trailing \samp{l} or
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
87 \samp{L} is not allowed, except if the base is 0. Note that when
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
88 invoked without \var{base} or with \var{base} set to 10, this
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
89 behaves identical to the built-in function
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
90 \function{long()}\bifuncindex{long} when passed a string.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
91 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
92
3996
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
93 \begin{funcdesc}{capitalize}{word}
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
94 Capitalize the first character of the argument.
3996
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
95 \end{funcdesc}
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
96
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
97 \begin{funcdesc}{capwords}{s}
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
98 Split the argument into words using \function{split()}, capitalize
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
99 each word using \function{capitalize()}, and join the capitalized
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
100 words using \function{join()}. Note that this replaces runs of
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
101 whitespace characters by a single space, and removes leading and
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
102 trailing whitespace.
3996
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
103 \end{funcdesc}
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
104
9952
e5d0df824bf3 Document the default for tabsize in expandtabs().
Guido van Rossum <guido@python.org>
parents: 9675
diff changeset
105 \begin{funcdesc}{expandtabs}{s, \optional{tabsize}}
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
106 Expand tabs in a string, i.e.\ replace them by one or more spaces,
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
107 depending on the current column and the given tab size. The column
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
108 number is reset to zero after each newline occurring in the string.
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
109 This doesn't understand other non-printing characters or escape
9952
e5d0df824bf3 Document the default for tabsize in expandtabs().
Guido van Rossum <guido@python.org>
parents: 9675
diff changeset
110 sequences. The tab size defaults to 8.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
111 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
112
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
113 \begin{funcdesc}{find}{s, sub\optional{, start\optional{,end}}}
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
114 Return the lowest index in \var{s} where the substring \var{sub} is
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
115 found such that \var{sub} is wholly contained in
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
116 \code{\var{s}[\var{start}:\var{end}]}. Return \code{-1} on failure.
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
117 Defaults for \var{start} and \var{end} and interpretation of
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
118 negative values is the same as for slices.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
119 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
120
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
121 \begin{funcdesc}{rfind}{s, sub\optional{, start\optional{, end}}}
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
122 Like \function{find()} but find the highest index.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
123 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
124
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
125 \begin{funcdesc}{index}{s, sub\optional{, start\optional{, end}}}
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
126 Like \function{find()} but raise \exception{ValueError} when the
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
127 substring is not found.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
128 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
129
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
130 \begin{funcdesc}{rindex}{s, sub\optional{, start\optional{, end}}}
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
131 Like \function{rfind()} but raise \exception{ValueError} when the
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
132 substring is not found.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
133 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
134
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
135 \begin{funcdesc}{count}{s, sub\optional{, start\optional{, end}}}
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
136 Return the number of (non-overlapping) occurrences of substring
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
137 \var{sub} in string \code{\var{s}[\var{start}:\var{end}]}.
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
138 Defaults for \var{start} and \var{end} and interpretation of
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
139 negative values is the same as for slices.
1750
0b645726957e libsocket.tex: send[to] returns nbytes.
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
140 \end{funcdesc}
0b645726957e libsocket.tex: send[to] returns nbytes.
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
141
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
142 \begin{funcdesc}{lower}{s}
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
143 Return a copy of \var{s}, but with upper case letters converted to
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
144 lower case.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
145 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
146
3858
8b71ea5dacc8 Added maketrans() and optional 3rd arg to translate() (chars to delete).
Guido van Rossum <guido@python.org>
parents: 3379
diff changeset
147 \begin{funcdesc}{maketrans}{from, to}
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
148 Return a translation table suitable for passing to
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
149 \function{translate()} or \function{regex.compile()}, that will map
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
150 each character in \var{from} into the character at the same position
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
151 in \var{to}; \var{from} and \var{to} must have the same length.
8488
3604131f942d Add warning about use of lowercase/uppercase with maketrans().
Guido van Rossum <guido@python.org>
parents: 7904
diff changeset
152
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
153 \strong{Warning:} don't use strings derived from \code{lowercase}
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
154 and \code{uppercase} as arguments; in some locales, these don't have
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
155 the same length. For case conversions, always use
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
156 \function{lower()} and \function{upper()}.
3858
8b71ea5dacc8 Added maketrans() and optional 3rd arg to translate() (chars to delete).
Guido van Rossum <guido@python.org>
parents: 3379
diff changeset
157 \end{funcdesc}
8b71ea5dacc8 Added maketrans() and optional 3rd arg to translate() (chars to delete).
Guido van Rossum <guido@python.org>
parents: 3379
diff changeset
158
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
159 \begin{funcdesc}{split}{s\optional{, sep\optional{, maxsplit}}}
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
160 Return a list of the words of the string \var{s}. If the optional
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
161 second argument \var{sep} is absent or \code{None}, the words are
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
162 separated by arbitrary strings of whitespace characters (space, tab,
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
163 newline, return, formfeed). If the second argument \var{sep} is
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
164 present and not \code{None}, it specifies a string to be used as the
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
165 word separator. The returned list will then have one more items
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
166 than the number of non-overlapping occurrences of the separator in
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
167 the string. The optional third argument \var{maxsplit} defaults to
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
168 0. If it is nonzero, at most \var{maxsplit} number of splits occur,
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
169 and the remainder of the string is returned as the final element of
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
170 the list (thus, the list will have at most \code{\var{maxsplit}+1}
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
171 elements).
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
172 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
173
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
174 \begin{funcdesc}{splitfields}{s\optional{, sep\optional{, maxsplit}}}
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
175 This function behaves identically to \function{split()}. (In the
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
176 past, \function{split()} was only used with one argument, while
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
177 \function{splitfields()} was only used with two arguments.)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
178 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
179
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
180 \begin{funcdesc}{join}{words\optional{, sep}}
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
181 Concatenate a list or tuple of words with intervening occurrences of
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
182 \var{sep}. The default value for \var{sep} is a single space
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
183 character. It is always true that
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
184 \samp{string.join(string.split(\var{s}, \var{sep}), \var{sep})}
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
185 equals \var{s}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
186 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
187
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
188 \begin{funcdesc}{joinfields}{words\optional{, sep}}
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
189 This function behaves identical to \function{join()}. (In the past,
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
190 \function{join()} was only used with one argument, while
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
191 \function{joinfields()} was only used with two arguments.)
3996
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
192 \end{funcdesc}
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
193
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
194 \begin{funcdesc}{lstrip}{s}
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
195 Return a copy of \var{s} but without leading whitespace characters.
3996
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
196 \end{funcdesc}
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
197
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
198 \begin{funcdesc}{rstrip}{s}
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
199 Return a copy of \var{s} but without trailing whitespace
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
200 characters.
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}{strip}{s}
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
204 Return a copy of \var{s} without leading or trailing whitespace.
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
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
207 \begin{funcdesc}{swapcase}{s}
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
208 Return a copy of \var{s}, but with lower case letters
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
209 converted to upper case and vice versa.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
210 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
211
3858
8b71ea5dacc8 Added maketrans() and optional 3rd arg to translate() (chars to delete).
Guido van Rossum <guido@python.org>
parents: 3379
diff changeset
212 \begin{funcdesc}{translate}{s, table\optional{, deletechars}}
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
213 Delete all characters from \var{s} that are in \var{deletechars} (if
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
214 present), and then translate the characters using \var{table}, which
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
215 must be a 256-character string giving the translation for each
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
216 character value, indexed by its ordinal.
3084
91c1bb75e945 added string.translate(s, table)
Guido van Rossum <guido@python.org>
parents: 2647
diff changeset
217 \end{funcdesc}
91c1bb75e945 added string.translate(s, table)
Guido van Rossum <guido@python.org>
parents: 2647
diff changeset
218
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
219 \begin{funcdesc}{upper}{s}
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
220 Return a copy of \var{s}, but with lower case letters converted to
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
221 upper case.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
222 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
223
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
224 \begin{funcdesc}{ljust}{s, width}
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
225 \funcline{rjust}{s, width}
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
226 \funcline{center}{s, width}
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
227 These functions respectively left-justify, right-justify and center
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
228 a string in a field of given width. They return a string that is at
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
229 least \var{width} characters wide, created by padding the string
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
230 \var{s} with spaces until the given width on the right, left or both
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
231 sides. The string is never truncated.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
232 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
233
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
234 \begin{funcdesc}{zfill}{s, width}
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
235 Pad a numeric string on the left with zero digits until the given
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
236 width is reached. Strings starting with a sign are handled
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
237 correctly.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
238 \end{funcdesc}
2463
e764b78a704f add warning about strop
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
239
5245
c5fd327057c6 Add cross-refs for int() to atoi() etc.
Guido van Rossum <guido@python.org>
parents: 5212
diff changeset
240 \begin{funcdesc}{replace}{str, old, new\optional{, maxsplit}}
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
241 Return a copy of string \var{str} with all occurrences of substring
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
242 \var{old} replaced by \var{new}. If the optional argument
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
243 \var{maxsplit} is given, the first \var{maxsplit} occurrences are
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
244 replaced.
5212
1f38d5fb3d23 Added docs for replace() and replace1().
Guido van Rossum <guido@python.org>
parents: 5188
diff changeset
245 \end{funcdesc}
1f38d5fb3d23 Added docs for replace() and replace1().
Guido van Rossum <guido@python.org>
parents: 5188
diff changeset
246
2463
e764b78a704f add warning about strop
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
247 This module is implemented in Python. Much of its functionality has
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
248 been reimplemented in the built-in module
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
249 \module{strop}\refbimodindex{strop}. However, you
2463
e764b78a704f add warning about strop
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
250 should \emph{never} import the latter module directly. When
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
251 \module{string} discovers that \module{strop} exists, it transparently
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
252 replaces parts of itself with the implementation from \module{strop}.
2463
e764b78a704f add warning about strop
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
253 After initialization, there is \emph{no} overhead in using
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
254 \module{string} instead of \module{strop}.