Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libregsub.tex @ 21467:4e35fa5d5708 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.
author Fred Drake <fdrake@acm.org>
date Tue, 18 Dec 2001 16:31:08 +0000
parents 45ec5df9a62d
children
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{regsub} ---
10703
e4e800a78d8d Make internal module references hyperlinks wherever it makes sense.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
2 String operations using regular expressions}
e4e800a78d8d Make internal module references hyperlinks wherever it makes sense.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
3
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7921
diff changeset
4 \declaremodule{standard}{regsub}
10703
e4e800a78d8d Make internal module references hyperlinks wherever it makes sense.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
5 \modulesynopsis{Substitution and splitting operations that use
14846
45ec5df9a62d Add obsolescence note to the module descriptions that get added to the
Fred Drake <fdrake@acm.org>
parents: 10703
diff changeset
6 regular expressions. \strong{Obsolete!}}
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7921
diff changeset
7
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
8
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
9 This module defines a number of functions useful for working with
10703
e4e800a78d8d Make internal module references hyperlinks wherever it makes sense.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
10 regular expressions (see built-in module \refmodule{regex}).
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
11
3713
adc86707fa96 Added thread unsafety warning. Added optional retain arg to split.
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
12 Warning: these functions are not thread-safe.
adc86707fa96 Added thread unsafety warning. Added optional retain arg to split.
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
13
6997
fa19430fec4e Add obsolescence note.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
14 \strong{Obsolescence note:}
fa19430fec4e Add obsolescence note.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
15 This module is obsolete as of Python version 1.5; it is still being
fa19430fec4e Add obsolescence note.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
16 maintained because much existing code still uses it. All new code in
10703
e4e800a78d8d Make internal module references hyperlinks wherever it makes sense.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
17 need of regular expressions should use the new \refmodule{re} module, which
6997
fa19430fec4e Add obsolescence note.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
18 supports the more powerful and regular Perl-style regular expressions.
fa19430fec4e Add obsolescence note.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
19 Existing code should be converted. The standard library module
10703
e4e800a78d8d Make internal module references hyperlinks wherever it makes sense.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
20 \module{reconvert} helps in converting \refmodule{regex} style regular
e4e800a78d8d Make internal module references hyperlinks wherever it makes sense.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
21 expressions to \refmodule{re} style regular expressions. (For more
7921
0bdcedcd1549 Updated URL to AMK's regex-to-re HOWTO.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
22 conversion help, see Andrew Kuchling's\index{Kuchling, Andrew}
0bdcedcd1549 Updated URL to AMK's regex-to-re HOWTO.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
23 ``regex-to-re HOWTO'' at
0bdcedcd1549 Updated URL to AMK's regex-to-re HOWTO.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
24 \url{http://www.python.org/doc/howto/regex-to-re/}.)
6997
fa19430fec4e Add obsolescence note.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
25
3995
ca0e05ec85b9 Added capwords, splitx, and optional 3rd argument to split/splitx.
Guido van Rossum <guido@python.org>
parents: 3713
diff changeset
26
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7570
diff changeset
27 \begin{funcdesc}{sub}{pat, repl, str}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
28 Replace the first occurrence of pattern \var{pat} in string
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
29 \var{str} by replacement \var{repl}. If the pattern isn't found,
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
30 the string is returned unchanged. The pattern may be a string or an
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
31 already compiled pattern. The replacement may contain references
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
32 \samp{\e \var{digit}} to subpatterns and escaped backslashes.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
33 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
34
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7570
diff changeset
35 \begin{funcdesc}{gsub}{pat, repl, str}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
36 Replace all (non-overlapping) occurrences of pattern \var{pat} in
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
37 string \var{str} by replacement \var{repl}. The same rules as for
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
38 \code{sub()} apply. Empty matches for the pattern are replaced only
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
39 when not adjacent to a previous match, so e.g.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
40 \code{gsub('', '-', 'abc')} returns \code{'-a-b-c-'}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
41 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
42
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7570
diff changeset
43 \begin{funcdesc}{split}{str, pat\optional{, maxsplit}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
44 Split the string \var{str} in fields separated by delimiters matching
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
45 the pattern \var{pat}, and return a list containing the fields. Only
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
46 non-empty matches for the pattern are considered, so e.g.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
47 \code{split('a:b', ':*')} returns \code{['a', 'b']} and
3995
ca0e05ec85b9 Added capwords, splitx, and optional 3rd argument to split/splitx.
Guido van Rossum <guido@python.org>
parents: 3713
diff changeset
48 \code{split('abc', '')} returns \code{['abc']}. The \var{maxsplit}
ca0e05ec85b9 Added capwords, splitx, and optional 3rd argument to split/splitx.
Guido van Rossum <guido@python.org>
parents: 3713
diff changeset
49 defaults to 0. If it is nonzero, only \var{maxsplit} number of splits
ca0e05ec85b9 Added capwords, splitx, and optional 3rd argument to split/splitx.
Guido van Rossum <guido@python.org>
parents: 3713
diff changeset
50 occur, and the remainder of the string is returned as the final
ca0e05ec85b9 Added capwords, splitx, and optional 3rd argument to split/splitx.
Guido van Rossum <guido@python.org>
parents: 3713
diff changeset
51 element of the list.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
52 \end{funcdesc}
3995
ca0e05ec85b9 Added capwords, splitx, and optional 3rd argument to split/splitx.
Guido van Rossum <guido@python.org>
parents: 3713
diff changeset
53
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7570
diff changeset
54 \begin{funcdesc}{splitx}{str, pat\optional{, maxsplit}}
3995
ca0e05ec85b9 Added capwords, splitx, and optional 3rd argument to split/splitx.
Guido van Rossum <guido@python.org>
parents: 3713
diff changeset
55 Split the string \var{str} in fields separated by delimiters matching
ca0e05ec85b9 Added capwords, splitx, and optional 3rd argument to split/splitx.
Guido van Rossum <guido@python.org>
parents: 3713
diff changeset
56 the pattern \var{pat}, and return a list containing the fields as well
ca0e05ec85b9 Added capwords, splitx, and optional 3rd argument to split/splitx.
Guido van Rossum <guido@python.org>
parents: 3713
diff changeset
57 as the separators. For example, \code{splitx('a:::b', ':*')} returns
ca0e05ec85b9 Added capwords, splitx, and optional 3rd argument to split/splitx.
Guido van Rossum <guido@python.org>
parents: 3713
diff changeset
58 \code{['a', ':::', 'b']}. Otherwise, this function behaves the same
ca0e05ec85b9 Added capwords, splitx, and optional 3rd argument to split/splitx.
Guido van Rossum <guido@python.org>
parents: 3713
diff changeset
59 as \code{split}.
ca0e05ec85b9 Added capwords, splitx, and optional 3rd argument to split/splitx.
Guido van Rossum <guido@python.org>
parents: 3713
diff changeset
60 \end{funcdesc}
ca0e05ec85b9 Added capwords, splitx, and optional 3rd argument to split/splitx.
Guido van Rossum <guido@python.org>
parents: 3713
diff changeset
61
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7570
diff changeset
62 \begin{funcdesc}{capwords}{s\optional{, pat}}
3995
ca0e05ec85b9 Added capwords, splitx, and optional 3rd argument to split/splitx.
Guido van Rossum <guido@python.org>
parents: 3713
diff changeset
63 Capitalize words separated by optional pattern \var{pat}. The default
ca0e05ec85b9 Added capwords, splitx, and optional 3rd argument to split/splitx.
Guido van Rossum <guido@python.org>
parents: 3713
diff changeset
64 pattern uses any characters except letters, digits and underscores as
ca0e05ec85b9 Added capwords, splitx, and optional 3rd argument to split/splitx.
Guido van Rossum <guido@python.org>
parents: 3713
diff changeset
65 word delimiters. Capitalization is done by changing the first
ca0e05ec85b9 Added capwords, splitx, and optional 3rd argument to split/splitx.
Guido van Rossum <guido@python.org>
parents: 3713
diff changeset
66 character of each word to upper case.
ca0e05ec85b9 Added capwords, splitx, and optional 3rd argument to split/splitx.
Guido van Rossum <guido@python.org>
parents: 3713
diff changeset
67 \end{funcdesc}
5132
0fc1dacdafd7 Added a paragraph to describe clear_cache(), and why it's necessary.
Barry Warsaw <barry@python.org>
parents: 3995
diff changeset
68
0fc1dacdafd7 Added a paragraph to describe clear_cache(), and why it's necessary.
Barry Warsaw <barry@python.org>
parents: 3995
diff changeset
69 \begin{funcdesc}{clear_cache}{}
0fc1dacdafd7 Added a paragraph to describe clear_cache(), and why it's necessary.
Barry Warsaw <barry@python.org>
parents: 3995
diff changeset
70 The regsub module maintains a cache of compiled regular expressions,
0fc1dacdafd7 Added a paragraph to describe clear_cache(), and why it's necessary.
Barry Warsaw <barry@python.org>
parents: 3995
diff changeset
71 keyed on the regular expression string and the syntax of the regex
0fc1dacdafd7 Added a paragraph to describe clear_cache(), and why it's necessary.
Barry Warsaw <barry@python.org>
parents: 3995
diff changeset
72 module at the time the expression was compiled. This function clears
0fc1dacdafd7 Added a paragraph to describe clear_cache(), and why it's necessary.
Barry Warsaw <barry@python.org>
parents: 3995
diff changeset
73 that cache.
0fc1dacdafd7 Added a paragraph to describe clear_cache(), and why it's necessary.
Barry Warsaw <barry@python.org>
parents: 3995
diff changeset
74 \end{funcdesc}