Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libstring.tex @ 8918:acfffe14628e legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
New section header style. Fix up a few synopses.
author Fred Drake <fdrake@acm.org>
date Mon, 10 Aug 1998 19:42:37 +0000
parents 760dcf197048
children b78049fefceb
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}
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
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
63 identical to the built-in function
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
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}}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
68 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
69 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
70 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
71 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
72 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
73 \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
74 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
75 invoked without \var{base} or with \var{base} set to 10, this behaves
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
76 identical to the built-in function \function{int()} when passed a string.
5245
c5fd327057c6 Add cross-refs for int() to atoi() etc.
Guido van Rossum <guido@python.org>
parents: 5212
diff changeset
77 (Also note: for a more flexible interpretation of numeric literals,
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
78 use the built-in function \function{eval()}\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
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
81 \begin{funcdesc}{atol}{s\optional{, base}}
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
82 Convert string \var{s} to a long integer in the given \var{base}. The
2576
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
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
85 meaning as for \function{atoi()}. A trailing \samp{l} or \samp{L} is
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
86 not allowed, except if the base is 0. Note that when invoked without
5245
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
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
88 built-in function \function{long()}\bifuncindex{long} when passed a
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
89 string.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
90 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
91
3996
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
92 \begin{funcdesc}{capitalize}{word}
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
93 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
94 \end{funcdesc}
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
95
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
96 \begin{funcdesc}{capwords}{s}
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
97 Split the argument into words using \function{split()}, capitalize
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
98 each word using \function{capitalize()}, and join the capitalized
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
99 words using \function{join()}. Note that this replaces runs of
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
100 whitespace characters by a single space, and removes leading and
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
101 trailing whitespace.
3996
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
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
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
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
112 \begin{funcdesc}{find}{s, sub\optional{, start\optional{,end}}}
6493
bb8c3004d758 count() now has a 4th parameter too. Also rephrased the docs for find
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
113 Return the lowest index in \var{s} where the substring \var{sub} is
bb8c3004d758 count() now has a 4th parameter too. Also rephrased the docs for find
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
114 found such that \var{sub} is wholly contained in
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
115 \code{\var{s}[\var{start}:\var{end}]}. Return \code{-1} on failure.
6493
bb8c3004d758 count() now has a 4th parameter too. Also rephrased the docs for find
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
116 Defaults for \var{start} and \var{end} and interpretation of negative
bb8c3004d758 count() now has a 4th parameter too. Also rephrased the docs for find
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
117 values is the same as for slices.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
118 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
119
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
120 \begin{funcdesc}{rfind}{s, sub\optional{, start\optional{, end}}}
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
121 Like \function{find()} but find the highest index.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
122 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
123
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
124 \begin{funcdesc}{index}{s, sub\optional{, start\optional{, end}}}
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
125 Like \function{find()} but raise \exception{ValueError} when the
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
126 substring is not found.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
127 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
128
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
129 \begin{funcdesc}{rindex}{s, sub\optional{, start\optional{, end}}}
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
130 Like \function{rfind()} but raise \exception{ValueError} when the
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
131 substring is not found.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
132 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
133
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
134 \begin{funcdesc}{count}{s, sub\optional{, start\optional{, end}}}
1750
0b645726957e libsocket.tex: send[to] returns nbytes.
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
135 Return the number of (non-overlapping) occurrences of substring
6493
bb8c3004d758 count() now has a 4th parameter too. Also rephrased the docs for find
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
136 \var{sub} in string \code{\var{s}[\var{start}:\var{end}]}.
bb8c3004d758 count() now has a 4th parameter too. Also rephrased the docs for find
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
137 Defaults for \var{start} and \var{end} and interpretation of negative
bb8c3004d758 count() now has a 4th parameter too. Also rephrased the docs for find
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
138 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
139 \end{funcdesc}
0b645726957e libsocket.tex: send[to] returns nbytes.
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
140
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
141 \begin{funcdesc}{lower}{s}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
142 Convert letters to lower case.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
143 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
144
3858
8b71ea5dacc8 Added maketrans() and optional 3rd arg to translate() (chars to delete).
Guido van Rossum <guido@python.org>
parents: 3379
diff changeset
145 \begin{funcdesc}{maketrans}{from, to}
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
146 Return a translation table suitable for passing to
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
147 \function{translate()} or \function{regex.compile()}, that will map
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
148 each character in \var{from} into the character at the same position
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
149 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
150
3604131f942d Add warning about use of lowercase/uppercase with maketrans().
Guido van Rossum <guido@python.org>
parents: 7904
diff changeset
151 \strong{Warning:} don't use strings derived from \code{lowercase} and
3604131f942d Add warning about use of lowercase/uppercase with maketrans().
Guido van Rossum <guido@python.org>
parents: 7904
diff changeset
152 \code{uppercase} as arguments; in some locales, these don't have the
3604131f942d Add warning about use of lowercase/uppercase with maketrans().
Guido van Rossum <guido@python.org>
parents: 7904
diff changeset
153 same length. For case conversions, always use \function{lower()} and
3604131f942d Add warning about use of lowercase/uppercase with maketrans().
Guido van Rossum <guido@python.org>
parents: 7904
diff changeset
154 \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
155 \end{funcdesc}
8b71ea5dacc8 Added maketrans() and optional 3rd arg to translate() (chars to delete).
Guido van Rossum <guido@python.org>
parents: 3379
diff changeset
156
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
157 \begin{funcdesc}{split}{s\optional{, sep\optional{, maxsplit}}}
3996
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
158 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
159 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
160 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
161 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
162 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
163 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
164 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
165 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
166 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
167 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
168 (thus, the list will have at most \code{\var{maxsplit}+1} elements).
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
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
171 \begin{funcdesc}{splitfields}{s\optional{, sep\optional{, maxsplit}}}
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
172 This function behaves identically to \function{split()}. (In the
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
173 past, \function{split()} was only used with one argument, while
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
174 \function{splitfields()} 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
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
177 \begin{funcdesc}{join}{words\optional{, sep}}
3996
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
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
179 \var{sep}. The default value for \var{sep} is a single space
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
180 character. It is always true that
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
181 \samp{string.join(string.split(\var{s}, \var{sep}), \var{sep})}
3996
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
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
185 \begin{funcdesc}{joinfields}{words\optional{, sep}}
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
186 This function behaves identical to \function{join()}. (In the past,
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
187 \function{join()} was only used with one argument, while
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
188 \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
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}}
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
208 Delete all characters from \var{s} that are in \var{deletechars} (if
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
209 present), and then translate the characters using \var{table}, which
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
210 must be a 256-character string giving the translation for each
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
211 character 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
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
218 \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
219 \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
220 \funcline{center}{s, width}
1471
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
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
231 \begin{funcdesc}{zfill}{s, width}
1471
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
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
244 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
245 \module{strop}\refbimodindex{strop}. However, you
2463
e764b78a704f add warning about strop
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
246 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
247 \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
248 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
249 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
250 \module{string} instead of \module{strop}.