Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libstring.tex @ 33871:5afa5277fcd9 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
SF patch #1056967, changes the semantics of Template.safe_substitute() to not raise a ValueError for dangling delimiters (the delimiter itself is returned).
author Barry Warsaw <barry@python.org>
date Mon, 01 Nov 2004 03:52:43 +0000
parents 301265b80c41
children d55769712f73
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} ---
10703
e4e800a78d8d Make internal module references hyperlinks wherever it makes sense.
Fred Drake <fdrake@acm.org>
parents: 10229
diff changeset
2 Common string operations}
e4e800a78d8d Make internal module references hyperlinks wherever it makes sense.
Fred Drake <fdrake@acm.org>
parents: 10229
diff changeset
3
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8488
diff changeset
4 \declaremodule{standard}{string}
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
33258
993fd8acc90f Ah whoops, we didn't turn string into a package (thanks Neal!)
Barry Warsaw <barry@python.org>
parents: 33257
diff changeset
7 The \module{string} module contains a number of useful constants and classes,
33257
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
8 as well as some deprecated legacy functions that are also available as methods
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
9 on strings. See the module \refmodule{re}\refstmodindex{re} for string
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
10 functions based on regular expressions.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
11
33257
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
12 \subsection{String constants}
2463
e764b78a704f add warning about strop
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
13
15665
1690755c5986 Fix doubled word
Andrew M. Kuchling <amk@amk.ca>
parents: 15009
diff changeset
14 The constants defined in this module are:
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
15
18776
22b2f4b436af Added the constants ascii_letters, ascii_lowercase, and ascii_uppercase
Fred Drake <fdrake@acm.org>
parents: 17759
diff changeset
16 \begin{datadesc}{ascii_letters}
22b2f4b436af Added the constants ascii_letters, ascii_lowercase, and ascii_uppercase
Fred Drake <fdrake@acm.org>
parents: 17759
diff changeset
17 The concatenation of the \constant{ascii_lowercase} and
22b2f4b436af Added the constants ascii_letters, ascii_lowercase, and ascii_uppercase
Fred Drake <fdrake@acm.org>
parents: 17759
diff changeset
18 \constant{ascii_uppercase} constants described below. This value is
22b2f4b436af Added the constants ascii_letters, ascii_lowercase, and ascii_uppercase
Fred Drake <fdrake@acm.org>
parents: 17759
diff changeset
19 not locale-dependent.
22b2f4b436af Added the constants ascii_letters, ascii_lowercase, and ascii_uppercase
Fred Drake <fdrake@acm.org>
parents: 17759
diff changeset
20 \end{datadesc}
22b2f4b436af Added the constants ascii_letters, ascii_lowercase, and ascii_uppercase
Fred Drake <fdrake@acm.org>
parents: 17759
diff changeset
21
22b2f4b436af Added the constants ascii_letters, ascii_lowercase, and ascii_uppercase
Fred Drake <fdrake@acm.org>
parents: 17759
diff changeset
22 \begin{datadesc}{ascii_lowercase}
22b2f4b436af Added the constants ascii_letters, ascii_lowercase, and ascii_uppercase
Fred Drake <fdrake@acm.org>
parents: 17759
diff changeset
23 The lowercase letters \code{'abcdefghijklmnopqrstuvwxyz'}. This
22b2f4b436af Added the constants ascii_letters, ascii_lowercase, and ascii_uppercase
Fred Drake <fdrake@acm.org>
parents: 17759
diff changeset
24 value is not locale-dependent and will not change.
22b2f4b436af Added the constants ascii_letters, ascii_lowercase, and ascii_uppercase
Fred Drake <fdrake@acm.org>
parents: 17759
diff changeset
25 \end{datadesc}
22b2f4b436af Added the constants ascii_letters, ascii_lowercase, and ascii_uppercase
Fred Drake <fdrake@acm.org>
parents: 17759
diff changeset
26
22b2f4b436af Added the constants ascii_letters, ascii_lowercase, and ascii_uppercase
Fred Drake <fdrake@acm.org>
parents: 17759
diff changeset
27 \begin{datadesc}{ascii_uppercase}
22b2f4b436af Added the constants ascii_letters, ascii_lowercase, and ascii_uppercase
Fred Drake <fdrake@acm.org>
parents: 17759
diff changeset
28 The uppercase letters \code{'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}. This
22b2f4b436af Added the constants ascii_letters, ascii_lowercase, and ascii_uppercase
Fred Drake <fdrake@acm.org>
parents: 17759
diff changeset
29 value is not locale-dependent and will not change.
22b2f4b436af Added the constants ascii_letters, ascii_lowercase, and ascii_uppercase
Fred Drake <fdrake@acm.org>
parents: 17759
diff changeset
30 \end{datadesc}
22b2f4b436af Added the constants ascii_letters, ascii_lowercase, and ascii_uppercase
Fred Drake <fdrake@acm.org>
parents: 17759
diff changeset
31
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
32 \begin{datadesc}{digits}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
33 The string \code{'0123456789'}.
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}{hexdigits}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
37 The string \code{'0123456789abcdefABCDEF'}.
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}{letters}
12352
179a6e2850ac letters:
Fred Drake <fdrake@acm.org>
parents: 10882
diff changeset
41 The concatenation of the strings \constant{lowercase} and
18776
22b2f4b436af Added the constants ascii_letters, ascii_lowercase, and ascii_uppercase
Fred Drake <fdrake@acm.org>
parents: 17759
diff changeset
42 \constant{uppercase} described below. The specific value is
22b2f4b436af Added the constants ascii_letters, ascii_lowercase, and ascii_uppercase
Fred Drake <fdrake@acm.org>
parents: 17759
diff changeset
43 locale-dependent, and will be updated when
22b2f4b436af Added the constants ascii_letters, ascii_lowercase, and ascii_uppercase
Fred Drake <fdrake@acm.org>
parents: 17759
diff changeset
44 \function{locale.setlocale()} is called.
1471
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}{lowercase}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
48 A string containing all the characters that are considered lowercase
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
49 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
50 \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
51 the effect on the routines \function{upper()} and
18776
22b2f4b436af Added the constants ascii_letters, ascii_lowercase, and ascii_uppercase
Fred Drake <fdrake@acm.org>
parents: 17759
diff changeset
52 \function{swapcase()} is undefined. The specific value is
22b2f4b436af Added the constants ascii_letters, ascii_lowercase, and ascii_uppercase
Fred Drake <fdrake@acm.org>
parents: 17759
diff changeset
53 locale-dependent, and will be updated when
22b2f4b436af Added the constants ascii_letters, ascii_lowercase, and ascii_uppercase
Fred Drake <fdrake@acm.org>
parents: 17759
diff changeset
54 \function{locale.setlocale()} is called.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
55 \end{datadesc}
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 \begin{datadesc}{octdigits}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
58 The string \code{'01234567'}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
59 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
60
14666
1570854911ce Document the "printable" and "punctuation" constants added to the string
Fred Drake <fdrake@acm.org>
parents: 14488
diff changeset
61 \begin{datadesc}{punctuation}
1570854911ce Document the "printable" and "punctuation" constants added to the string
Fred Drake <fdrake@acm.org>
parents: 14488
diff changeset
62 String of \ASCII{} characters which are considered punctuation
1570854911ce Document the "printable" and "punctuation" constants added to the string
Fred Drake <fdrake@acm.org>
parents: 14488
diff changeset
63 characters in the \samp{C} locale.
1570854911ce Document the "printable" and "punctuation" constants added to the string
Fred Drake <fdrake@acm.org>
parents: 14488
diff changeset
64 \end{datadesc}
1570854911ce Document the "printable" and "punctuation" constants added to the string
Fred Drake <fdrake@acm.org>
parents: 14488
diff changeset
65
1570854911ce Document the "printable" and "punctuation" constants added to the string
Fred Drake <fdrake@acm.org>
parents: 14488
diff changeset
66 \begin{datadesc}{printable}
1570854911ce Document the "printable" and "punctuation" constants added to the string
Fred Drake <fdrake@acm.org>
parents: 14488
diff changeset
67 String of characters which are considered printable. This is a
1570854911ce Document the "printable" and "punctuation" constants added to the string
Fred Drake <fdrake@acm.org>
parents: 14488
diff changeset
68 combination of \constant{digits}, \constant{letters},
1570854911ce Document the "printable" and "punctuation" constants added to the string
Fred Drake <fdrake@acm.org>
parents: 14488
diff changeset
69 \constant{punctuation}, and \constant{whitespace}.
1570854911ce Document the "printable" and "punctuation" constants added to the string
Fred Drake <fdrake@acm.org>
parents: 14488
diff changeset
70 \end{datadesc}
1570854911ce Document the "printable" and "punctuation" constants added to the string
Fred Drake <fdrake@acm.org>
parents: 14488
diff changeset
71
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
72 \begin{datadesc}{uppercase}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
73 A string containing all the characters that are considered uppercase
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
74 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
75 \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
76 the effect on the routines \function{lower()} and
18776
22b2f4b436af Added the constants ascii_letters, ascii_lowercase, and ascii_uppercase
Fred Drake <fdrake@acm.org>
parents: 17759
diff changeset
77 \function{swapcase()} is undefined. The specific value is
22b2f4b436af Added the constants ascii_letters, ascii_lowercase, and ascii_uppercase
Fred Drake <fdrake@acm.org>
parents: 17759
diff changeset
78 locale-dependent, and will be updated when
22b2f4b436af Added the constants ascii_letters, ascii_lowercase, and ascii_uppercase
Fred Drake <fdrake@acm.org>
parents: 17759
diff changeset
79 \function{locale.setlocale()} is called.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
80 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
81
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
82 \begin{datadesc}{whitespace}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
83 A string containing all characters that are considered whitespace.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
84 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
85 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
86 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
87 is undefined.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
88 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
89
33257
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
90 \subsection{Template strings}
14488
aba7eb9d8d61 Add a reference to the material on string methods.
Fred Drake <fdrake@acm.org>
parents: 12976
diff changeset
91
33517
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
92 Templates provide simpler string substitutions as described in \pep{292}.
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
93 Instead of the normal \samp{\%}-based substitutions, Templates support
33257
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
94 \samp{\$}-based substitutions, using the following rules:
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
95
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
96 \begin{itemize}
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
97 \item \samp{\$\$} is an escape; it is replaced with a single \samp{\$}.
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
98
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
99 \item \samp{\$identifier} names a substitution placeholder matching a mapping
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
100 key of "identifier". By default, "identifier" must spell a Python
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
101 identifier. The first non-identifier character after the \samp{\$}
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
102 character terminates this placeholder specification.
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
103
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
104 \item \samp{\$\{identifier\}} is equivalent to \samp{\$identifier}. It is
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
105 required when valid identifier characters follow the placeholder but are
33413
e1ab2c12cd5e Markup nits.
Raymond Hettinger <python@rcn.com>
parents: 33258
diff changeset
106 not part of the placeholder, such as "\$\{noun\}ification".
33257
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
107 \end{itemize}
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
108
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
109 Any other appearance of \samp{\$} in the string will result in a
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
110 \exception{ValueError} being raised.
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
111
33413
e1ab2c12cd5e Markup nits.
Raymond Hettinger <python@rcn.com>
parents: 33258
diff changeset
112 \versionadded{2.4}
e1ab2c12cd5e Markup nits.
Raymond Hettinger <python@rcn.com>
parents: 33258
diff changeset
113
33517
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
114 The \module{string} module provides a \class{Template} class that implements
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
115 these rules. The methods of \class{Template} are:
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
116
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
117 \begin{classdesc}{Template}{template}
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
118 The constructor takes a single argument which is the template string.
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
119 \end{classdesc}
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
120
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
121 \begin{methoddesc}[Template]{substitute}{mapping\optional{, **kws}}
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
122 Performs the template substitution, returning a new string. \var{mapping} is
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
123 any dictionary-like object with keys that match the placeholders in the
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
124 template. Alternatively, you can provide keyword arguments, where the
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
125 keywords are the placeholders. When both \var{mapping} and \var{kws} are
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
126 given and there are duplicates, the placeholders from \var{kws} take
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
127 precedence.
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
128 \end{methoddesc}
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
129
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
130 \begin{methoddesc}[Template]{safe_substitute}{mapping\optional{, **kws}}
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
131 Like \method{substitute()}, except that if placeholders are missing from
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
132 \var{mapping} and \var{kws}, instead of raising a \exception{KeyError}
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
133 exception, the original placeholder will appear in the resulting string
33871
5afa5277fcd9 SF patch #1056967, changes the semantics of Template.safe_substitute() to not
Barry Warsaw <barry@python.org>
parents: 33517
diff changeset
134 intact. Also, unlike with \method{substitute()}, any other appearances of the
5afa5277fcd9 SF patch #1056967, changes the semantics of Template.safe_substitute() to not
Barry Warsaw <barry@python.org>
parents: 33517
diff changeset
135 \samp{\$} will simply return \samp{\$} instead of raising
5afa5277fcd9 SF patch #1056967, changes the semantics of Template.safe_substitute() to not
Barry Warsaw <barry@python.org>
parents: 33517
diff changeset
136 \exception{ValueError}.
5afa5277fcd9 SF patch #1056967, changes the semantics of Template.safe_substitute() to not
Barry Warsaw <barry@python.org>
parents: 33517
diff changeset
137
5afa5277fcd9 SF patch #1056967, changes the semantics of Template.safe_substitute() to not
Barry Warsaw <barry@python.org>
parents: 33517
diff changeset
138 While other exceptions may still occur, this method is called ``safe'' because
5afa5277fcd9 SF patch #1056967, changes the semantics of Template.safe_substitute() to not
Barry Warsaw <barry@python.org>
parents: 33517
diff changeset
139 substitutions always tries to return a usable string instead of raising an
5afa5277fcd9 SF patch #1056967, changes the semantics of Template.safe_substitute() to not
Barry Warsaw <barry@python.org>
parents: 33517
diff changeset
140 exception. In another sense, \method{safe_substitute()} may be anything other
5afa5277fcd9 SF patch #1056967, changes the semantics of Template.safe_substitute() to not
Barry Warsaw <barry@python.org>
parents: 33517
diff changeset
141 than safe, since it will silently ignore malformed templates containing
5afa5277fcd9 SF patch #1056967, changes the semantics of Template.safe_substitute() to not
Barry Warsaw <barry@python.org>
parents: 33517
diff changeset
142 dangling delimiters, unmatched braces, or placeholders that are not valid
5afa5277fcd9 SF patch #1056967, changes the semantics of Template.safe_substitute() to not
Barry Warsaw <barry@python.org>
parents: 33517
diff changeset
143 Python identifiers.
33517
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
144 \end{methoddesc}
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
145
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
146 \class{Template} instances also provide one public data attribute:
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
147
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
148 \begin{memberdesc}[string]{template}
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
149 This is the object passed to the constructor's \var{template} argument. In
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
150 general, you shouldn't change it, but read-only access is not enforced.
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
151 \end{memberdesc}
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
152
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
153 Here is an example of how to use a Template:
33257
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
154
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
155 \begin{verbatim}
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
156 >>> from string import Template
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
157 >>> s = Template('$who likes $what')
33517
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
158 >>> s.substitute(who='tim', what='kung pao')
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
159 'tim likes kung pao'
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
160 >>> d = dict(who='tim')
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
161 >>> Template('Give $who $100').substitute(d)
33257
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
162 Traceback (most recent call last):
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
163 [...]
33517
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
164 ValueError: Invalid placeholder in string: line 1, col 10
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
165 >>> Template('$who likes $what').substitute(d)
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
166 Traceback (most recent call last):
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
167 [...]
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
168 KeyError: 'what'
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
169 >>> Template('$who likes $what').safe_substitute(d)
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
170 'tim likes $what'
33257
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
171 \end{verbatim}
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
172
33517
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
173 Advanced usage: you can derive subclasses of \class{Template} to customize the
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
174 placeholder syntax, delimiter character, or the entire regular expression used
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
175 to parse template strings. To do this, you can override these class
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
176 attributes:
33257
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
177
33517
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
178 \begin{itemize}
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
179 \item \var{delimiter} -- This is the literal string describing a placeholder
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
180 introducing delimiter. The default value \samp{\$}. Note that this
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
181 should \emph{not} be a regular expression, as the implementation will
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
182 call \method{re.escape()} on this string as needed.
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
183 \item \var{idpattern} -- This is the regular expression describing the pattern
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
184 for non-braced placeholders (the braces will be added automatically as
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
185 appropriate). The default value is the regular expression
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
186 \samp{[_a-z][_a-z0-9]*}.
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
187 \end{itemize}
33257
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
188
33517
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
189 Alternatively, you can provide the entire regular expression pattern by
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
190 overriding the class attribute \var{pattern}. If you do this, the value must
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
191 be a regular expression object with four named capturing groups. The
33257
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
192 capturing groups correspond to the rules given above, along with the invalid
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
193 placeholder rule:
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
194
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
195 \begin{itemize}
33517
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
196 \item \var{escaped} -- This group matches the escape sequence,
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
197 e.g. \samp{\$\$}, in the default pattern.
33257
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
198 \item \var{named} -- This group matches the unbraced placeholder name; it
33517
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
199 should not include the delimiter in capturing group.
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
200 \item \var{braced} -- This group matches the brace enclosed placeholder name;
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
201 it should not include either the delimiter or braces in the capturing
33257
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
202 group.
33517
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
203 \item \var{invalid} -- This group matches any other delimiter pattern (usually
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
204 a single delimiter), and it should appear last in the regular
301265b80c41 Update Template/PEP 292 documentation to current implementation.
Barry Warsaw <barry@python.org>
parents: 33413
diff changeset
205 expression.
33257
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
206 \end{itemize}
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
207
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
208 \subsection{String functions}
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
209
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
210 The following functions are available to operate on string and Unicode
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
211 objects. They are not available as string methods.
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
212
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
213 \begin{funcdesc}{capwords}{s}
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
214 Split the argument into words using \function{split()}, capitalize
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
215 each word using \function{capitalize()}, and join the capitalized
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
216 words using \function{join()}. Note that this replaces runs of
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
217 whitespace characters by a single space, and removes leading and
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
218 trailing whitespace.
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
219 \end{funcdesc}
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
220
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
221 \begin{funcdesc}{maketrans}{from, to}
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
222 Return a translation table suitable for passing to
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
223 \function{translate()} or \function{regex.compile()}, that will map
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
224 each character in \var{from} into the character at the same position
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
225 in \var{to}; \var{from} and \var{to} must have the same length.
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
226
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
227 \warning{Don't use strings derived from \constant{lowercase}
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
228 and \constant{uppercase} as arguments; in some locales, these don't have
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
229 the same length. For case conversions, always use
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
230 \function{lower()} and \function{upper()}.}
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
231 \end{funcdesc}
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
232
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
233 \subsection{Deprecated string functions}
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
234
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
235 The following list of functions are also defined as methods of string and
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
236 Unicode objects; see ``String Methods'' (section
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
237 \ref{string-methods}) for more information on those. You should consider
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
238 these functions as deprecated, although they will not be removed until Python
11a4fbc88a80 PEP 292 classes Template and SafeTemplate are added to the string module.
Barry Warsaw <barry@python.org>
parents: 32761
diff changeset
239 3.0. The functions defined in this module are:
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
240
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
241 \begin{funcdesc}{atof}{s}
15009
9847b486d15f Added deprecation notices to atof(), atoi(), and atol(), recommending
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
242 \deprecated{2.0}{Use the \function{float()} built-in function.}
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
243 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
244 the standard syntax for a floating point literal in Python,
10229
ce57eb30968a Add notes to __builtin__.float() and string.atof() that the NaN and Inf
Fred Drake <fdrake@acm.org>
parents: 10222
diff changeset
245 optionally preceded by a sign (\samp{+} or \samp{-}). Note that
ce57eb30968a Add notes to __builtin__.float() and string.atof() that the NaN and Inf
Fred Drake <fdrake@acm.org>
parents: 10222
diff changeset
246 this behaves identical to the built-in function
ce57eb30968a Add notes to __builtin__.float() and string.atof() that the NaN and Inf
Fred Drake <fdrake@acm.org>
parents: 10222
diff changeset
247 \function{float()}\bifuncindex{float} when passed a string.
ce57eb30968a Add notes to __builtin__.float() and string.atof() that the NaN and Inf
Fred Drake <fdrake@acm.org>
parents: 10222
diff changeset
248
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 18776
diff changeset
249 \note{When passing in a string, values for NaN\index{NaN}
10229
ce57eb30968a Add notes to __builtin__.float() and string.atof() that the NaN and Inf
Fred Drake <fdrake@acm.org>
parents: 10222
diff changeset
250 and Infinity\index{Infinity} may be returned, depending on the
ce57eb30968a Add notes to __builtin__.float() and string.atof() that the NaN and Inf
Fred Drake <fdrake@acm.org>
parents: 10222
diff changeset
251 underlying C library. The specific set of strings accepted which
ce57eb30968a Add notes to __builtin__.float() and string.atof() that the NaN and Inf
Fred Drake <fdrake@acm.org>
parents: 10222
diff changeset
252 cause these values to be returned depends entirely on the C library
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 18776
diff changeset
253 and is known to vary.}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
254 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
255
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
256 \begin{funcdesc}{atoi}{s\optional{, base}}
15009
9847b486d15f Added deprecation notices to atof(), atoi(), and atol(), recommending
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
257 \deprecated{2.0}{Use the \function{int()} built-in function.}
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
258 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
259 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
260 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
261 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
262 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
263 means 16, \samp{0} means 8, anything else means 10. If \var{base}
14710
ac6df0494c58 Fixed a number of small problems reported by Detlef Lannert
Fred Drake <fdrake@acm.org>
parents: 14666
diff changeset
264 is 16, a leading \samp{0x} or \samp{0X} is always accepted, though
ac6df0494c58 Fixed a number of small problems reported by Detlef Lannert
Fred Drake <fdrake@acm.org>
parents: 14666
diff changeset
265 not required. This behaves identically to the built-in function
ac6df0494c58 Fixed a number of small problems reported by Detlef Lannert
Fred Drake <fdrake@acm.org>
parents: 14666
diff changeset
266 \function{int()} when passed a string. (Also note: for a more
ac6df0494c58 Fixed a number of small problems reported by Detlef Lannert
Fred Drake <fdrake@acm.org>
parents: 14666
diff changeset
267 flexible interpretation of numeric literals, use the built-in
ac6df0494c58 Fixed a number of small problems reported by Detlef Lannert
Fred Drake <fdrake@acm.org>
parents: 14666
diff changeset
268 function \function{eval()}\bifuncindex{eval}.)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
269 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
270
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
271 \begin{funcdesc}{atol}{s\optional{, base}}
15009
9847b486d15f Added deprecation notices to atof(), atoi(), and atol(), recommending
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
272 \deprecated{2.0}{Use the \function{long()} built-in function.}
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
273 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
274 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
275 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
276 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
277 \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
278 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
279 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
280 \function{long()}\bifuncindex{long} when passed a string.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
281 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
282
3996
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
283 \begin{funcdesc}{capitalize}{word}
23942
6e2a3c5700ac Make the docs for string.capitalize() match those of str.capitalize()
Fred Drake <fdrake@acm.org>
parents: 23225
diff changeset
284 Return a copy of \var{word} with only its first character capitalized.
3996
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
285 \end{funcdesc}
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
286
15009
9847b486d15f Added deprecation notices to atof(), atoi(), and atol(), recommending
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
287 \begin{funcdesc}{expandtabs}{s\optional{, tabsize}}
33413
e1ab2c12cd5e Markup nits.
Raymond Hettinger <python@rcn.com>
parents: 33258
diff changeset
288 Expand tabs in a string replacing them by one or more spaces,
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
289 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
290 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
291 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
292 sequences. The tab size defaults to 8.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
293 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
294
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
295 \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
296 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
297 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
298 \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
299 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
300 negative values is the same as for slices.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
301 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
302
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
303 \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
304 Like \function{find()} but find the highest index.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
305 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
306
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
307 \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
308 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
309 substring is not found.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
310 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
311
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
312 \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
313 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
314 substring is not found.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
315 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
316
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
317 \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
318 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
319 \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
320 Defaults for \var{start} and \var{end} and interpretation of
12976
f793c47c510e Minor grammatical fix
Andrew M. Kuchling <amk@amk.ca>
parents: 12352
diff changeset
321 negative values are the same as for slices.
1750
0b645726957e libsocket.tex: send[to] returns nbytes.
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
322 \end{funcdesc}
0b645726957e libsocket.tex: send[to] returns nbytes.
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
323
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
324 \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
325 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
326 lower case.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
327 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
328
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
329 \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
330 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
331 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
332 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
333 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
334 present and not \code{None}, it specifies a string to be used as the
10882
06def8042d8e Typo reported by Gerry Wiener <wiener@rap.ucar.edu>:
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
335 word separator. The returned list will then have one more item
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
336 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
337 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
338 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
339 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
340 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
341 elements).
31735
ee0ba00b277c Modified string.split documentation to reflect behaviour of splitting emtpy string. Closes SF bug #811604
Nicholas Bastin <nick.bastin@gmail.com>
parents: 31289
diff changeset
342
ee0ba00b277c Modified string.split documentation to reflect behaviour of splitting emtpy string. Closes SF bug #811604
Nicholas Bastin <nick.bastin@gmail.com>
parents: 31289
diff changeset
343 The behavior of split on an empty string depends on the value of \var{sep}.
ee0ba00b277c Modified string.split documentation to reflect behaviour of splitting emtpy string. Closes SF bug #811604
Nicholas Bastin <nick.bastin@gmail.com>
parents: 31289
diff changeset
344 If \var{sep} is not specified, or specified as \code{None}, the result will
ee0ba00b277c Modified string.split documentation to reflect behaviour of splitting emtpy string. Closes SF bug #811604
Nicholas Bastin <nick.bastin@gmail.com>
parents: 31289
diff changeset
345 be an empty list. If \var{sep} is specified as any string, the result will
ee0ba00b277c Modified string.split documentation to reflect behaviour of splitting emtpy string. Closes SF bug #811604
Nicholas Bastin <nick.bastin@gmail.com>
parents: 31289
diff changeset
346 be a list containing one element which is an empty string.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
347 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
348
31199
504943c89193 Add rsplit method for str and unicode builtin types.
Hye-Shik Chang <hyeshik@gmail.com>
parents: 30937
diff changeset
349 \begin{funcdesc}{rsplit}{s\optional{, sep\optional{, maxsplit}}}
31206
3771ff99d5f2 Update documentations for str.rsplit() with Alex Martelli's rewrite.
Hye-Shik Chang <hyeshik@gmail.com>
parents: 31199
diff changeset
350 Return a list of the words of the string \var{s}, scanning \var{s}
3771ff99d5f2 Update documentations for str.rsplit() with Alex Martelli's rewrite.
Hye-Shik Chang <hyeshik@gmail.com>
parents: 31199
diff changeset
351 from the end. To all intents and purposes, the resulting list of
3771ff99d5f2 Update documentations for str.rsplit() with Alex Martelli's rewrite.
Hye-Shik Chang <hyeshik@gmail.com>
parents: 31199
diff changeset
352 words is the same as returned by \function{split()}, except when the
3771ff99d5f2 Update documentations for str.rsplit() with Alex Martelli's rewrite.
Hye-Shik Chang <hyeshik@gmail.com>
parents: 31199
diff changeset
353 optional third argument \var{maxsplit} is explicitly specified and
3771ff99d5f2 Update documentations for str.rsplit() with Alex Martelli's rewrite.
Hye-Shik Chang <hyeshik@gmail.com>
parents: 31199
diff changeset
354 nonzero. When \var{maxsplit} is nonzero, at most \var{maxsplit}
31289
2cd96629fe8d fix truly evil markup typo
Fred Drake <fdrake@acm.org>
parents: 31206
diff changeset
355 number of splits -- the \emph{rightmost} ones -- occur, and the remainder
31206
3771ff99d5f2 Update documentations for str.rsplit() with Alex Martelli's rewrite.
Hye-Shik Chang <hyeshik@gmail.com>
parents: 31199
diff changeset
356 of the string is returned as the first element of the list (thus, the
3771ff99d5f2 Update documentations for str.rsplit() with Alex Martelli's rewrite.
Hye-Shik Chang <hyeshik@gmail.com>
parents: 31199
diff changeset
357 list will have at most \code{\var{maxsplit}+1} elements).
31199
504943c89193 Add rsplit method for str and unicode builtin types.
Hye-Shik Chang <hyeshik@gmail.com>
parents: 30937
diff changeset
358 \versionadded{2.4}
504943c89193 Add rsplit method for str and unicode builtin types.
Hye-Shik Chang <hyeshik@gmail.com>
parents: 30937
diff changeset
359 \end{funcdesc}
504943c89193 Add rsplit method for str and unicode builtin types.
Hye-Shik Chang <hyeshik@gmail.com>
parents: 30937
diff changeset
360
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
361 \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
362 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
363 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
364 \function{splitfields()} was only used with two arguments.)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
365 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
366
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
367 \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
368 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
369 \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
370 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
371 \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
372 equals \var{s}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
373 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
374
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
375 \begin{funcdesc}{joinfields}{words\optional{, sep}}
25229
8775dee60d89 Fix typo reported by Paul Clifford.
Fred Drake <fdrake@acm.org>
parents: 23942
diff changeset
376 This function behaves identically to \function{join()}. (In the past,
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
377 \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
378 \function{joinfields()} was only used with two arguments.)
25229
8775dee60d89 Fix typo reported by Paul Clifford.
Fred Drake <fdrake@acm.org>
parents: 23942
diff changeset
379 Note that there is no \method{joinfields()} method on string
8775dee60d89 Fix typo reported by Paul Clifford.
Fred Drake <fdrake@acm.org>
parents: 23942
diff changeset
380 objects; use the \method{join()} method instead.
3996
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
381 \end{funcdesc}
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
382
23225
e639e34ef901 Apply patch diff.txt from SF feature request
Walter Dörwald <walter@livinglogic.de>
parents: 20580
diff changeset
383 \begin{funcdesc}{lstrip}{s\optional{, chars}}
e639e34ef901 Apply patch diff.txt from SF feature request
Walter Dörwald <walter@livinglogic.de>
parents: 20580
diff changeset
384 Return a copy of the string with leading characters removed. If
e639e34ef901 Apply patch diff.txt from SF feature request
Walter Dörwald <walter@livinglogic.de>
parents: 20580
diff changeset
385 \var{chars} is omitted or \code{None}, whitespace characters are
e639e34ef901 Apply patch diff.txt from SF feature request
Walter Dörwald <walter@livinglogic.de>
parents: 20580
diff changeset
386 removed. If given and not \code{None}, \var{chars} must be a string;
e639e34ef901 Apply patch diff.txt from SF feature request
Walter Dörwald <walter@livinglogic.de>
parents: 20580
diff changeset
387 the characters in the string will be stripped from the beginning of
e639e34ef901 Apply patch diff.txt from SF feature request
Walter Dörwald <walter@livinglogic.de>
parents: 20580
diff changeset
388 the string this method is called on.
28575
215f1f4851a4 Attempt to make all the various string *strip methods the same.
Neal Norwitz <nnorwitz@gmail.com>
parents: 25229
diff changeset
389 \versionchanged[The \var{chars} parameter was added. The \var{chars}
215f1f4851a4 Attempt to make all the various string *strip methods the same.
Neal Norwitz <nnorwitz@gmail.com>
parents: 25229
diff changeset
390 parameter cannot be passed in earlier 2.2 versions]{2.2.3}
3996
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
391 \end{funcdesc}
0ec2ce97b8e3 Added capitalize, capwords, lstrip, rstrip, and optional 3rd argument
Guido van Rossum <guido@python.org>
parents: 3858
diff changeset
392
23225
e639e34ef901 Apply patch diff.txt from SF feature request
Walter Dörwald <walter@livinglogic.de>
parents: 20580
diff changeset
393 \begin{funcdesc}{rstrip}{s\optional{, chars}}
e639e34ef901 Apply patch diff.txt from SF feature request
Walter Dörwald <walter@livinglogic.de>
parents: 20580
diff changeset
394 Return a copy of the string with trailing characters removed. If
e639e34ef901 Apply patch diff.txt from SF feature request
Walter Dörwald <walter@livinglogic.de>
parents: 20580
diff changeset
395 \var{chars} is omitted or \code{None}, whitespace characters are
e639e34ef901 Apply patch diff.txt from SF feature request
Walter Dörwald <walter@livinglogic.de>
parents: 20580
diff changeset
396 removed. If given and not \code{None}, \var{chars} must be a string;
e639e34ef901 Apply patch diff.txt from SF feature request
Walter Dörwald <walter@livinglogic.de>
parents: 20580
diff changeset
397 the characters in the string will be stripped from the end of the
e639e34ef901 Apply patch diff.txt from SF feature request
Walter Dörwald <walter@livinglogic.de>
parents: 20580
diff changeset
398 string this method is called on.
28575
215f1f4851a4 Attempt to make all the various string *strip methods the same.
Neal Norwitz <nnorwitz@gmail.com>
parents: 25229
diff changeset
399 \versionchanged[The \var{chars} parameter was added. The \var{chars}
32761
61be904a1d4e Patch #993187: Make rstrip doc similar to lstrip.
Martin v. Löwis <martin@v.loewis.de>
parents: 31735
diff changeset
400 parameter cannot be passed in earlier 2.2 versions]{2.2.3}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
401 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
402
23225
e639e34ef901 Apply patch diff.txt from SF feature request
Walter Dörwald <walter@livinglogic.de>
parents: 20580
diff changeset
403 \begin{funcdesc}{strip}{s\optional{, chars}}
e639e34ef901 Apply patch diff.txt from SF feature request
Walter Dörwald <walter@livinglogic.de>
parents: 20580
diff changeset
404 Return a copy of the string with leading and trailing characters
e639e34ef901 Apply patch diff.txt from SF feature request
Walter Dörwald <walter@livinglogic.de>
parents: 20580
diff changeset
405 removed. If \var{chars} is omitted or \code{None}, whitespace
e639e34ef901 Apply patch diff.txt from SF feature request
Walter Dörwald <walter@livinglogic.de>
parents: 20580
diff changeset
406 characters are removed. If given and not \code{None}, \var{chars}
e639e34ef901 Apply patch diff.txt from SF feature request
Walter Dörwald <walter@livinglogic.de>
parents: 20580
diff changeset
407 must be a string; the characters in the string will be stripped from
e639e34ef901 Apply patch diff.txt from SF feature request
Walter Dörwald <walter@livinglogic.de>
parents: 20580
diff changeset
408 the both ends of the string this method is called on.
28575
215f1f4851a4 Attempt to make all the various string *strip methods the same.
Neal Norwitz <nnorwitz@gmail.com>
parents: 25229
diff changeset
409 \versionchanged[The \var{chars} parameter was added. The \var{chars}
28665
239429dc029f Oops, missed updating doc to correct version for split
Neal Norwitz <nnorwitz@gmail.com>
parents: 28575
diff changeset
410 parameter cannot be passed in earlier 2.2 versions]{2.2.3}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
411 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
412
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
413 \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
414 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
415 converted to upper case and vice versa.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
416 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
417
3858
8b71ea5dacc8 Added maketrans() and optional 3rd arg to translate() (chars to delete).
Guido van Rossum <guido@python.org>
parents: 3379
diff changeset
418 \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
419 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
420 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
421 must be a 256-character string giving the translation for each
29833
d45d317fda35 SF bug #706546: u''.translate not documented
Raymond Hettinger <python@rcn.com>
parents: 28665
diff changeset
422 character value, indexed by its ordinal.
3084
91c1bb75e945 added string.translate(s, table)
Guido van Rossum <guido@python.org>
parents: 2647
diff changeset
423 \end{funcdesc}
91c1bb75e945 added string.translate(s, table)
Guido van Rossum <guido@python.org>
parents: 2647
diff changeset
424
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
425 \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
426 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
427 upper case.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
428 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
429
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
430 \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
431 \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
432 \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
433 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
434 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
435 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
436 \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
437 sides. The string is never truncated.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
438 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
439
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
440 \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
441 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
442 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
443 correctly.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
444 \end{funcdesc}
2463
e764b78a704f add warning about strop
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
445
30937
51ebf5474f3d Patch #843088: Fix typos. Backported to 2.3.
Martin v. Löwis <martin@v.loewis.de>
parents: 29893
diff changeset
446 \begin{funcdesc}{replace}{str, old, new\optional{, maxreplace}}
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
447 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
448 \var{old} replaced by \var{new}. If the optional argument
30937
51ebf5474f3d Patch #843088: Fix typos. Backported to 2.3.
Martin v. Löwis <martin@v.loewis.de>
parents: 29893
diff changeset
449 \var{maxreplace} is given, the first \var{maxreplace} occurrences are
9675
b78049fefceb Clarify descriptions of some operations; it's not always clear that
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
450 replaced.
5212
1f38d5fb3d23 Added docs for replace() and replace1().
Guido van Rossum <guido@python.org>
parents: 5188
diff changeset
451 \end{funcdesc}