Doc/lib/libregsub.tex

   1 \section{\module{regsub} ---
   2          Substitution and splitting operations that use regular expressions.}
   3 \declaremodule{standard}{regsub}
   4
   5 \modulesynopsis{Substitution and splitting operations that use regular expressions.}
   6
   7
   8 This module defines a number of functions useful for working with
   9 regular expressions (see built-in module \code{regex}).
  10
  11 Warning: these functions are not thread-safe.
  12
  13 \strong{Obsolescence note:}
  14 This module is obsolete as of Python version 1.5; it is still being
  15 maintained because much existing code still uses it.  All new code in
  16 need of regular expressions should use the new \module{re} module, which
  17 supports the more powerful and regular Perl-style regular expressions.
  18 Existing code should be converted.  The standard library module
  19 \module{reconvert} helps in converting \code{regex} style regular
  20 expressions to \module{re} style regular expressions.  (For more
  21 conversion help, see Andrew Kuchling's\index{Kuchling, Andrew}
  22 ``regex-to-re HOWTO'' at
  23 \url{http://www.python.org/doc/howto/regex-to-re/}.)
  24
  25
  26 \begin{funcdesc}{sub}{pat, repl, str}
  27 Replace the first occurrence of pattern \var{pat} in string
  28 \var{str} by replacement \var{repl}.  If the pattern isn't found,
  29 the string is returned unchanged.  The pattern may be a string or an
  30 already compiled pattern.  The replacement may contain references
  31 \samp{\e \var{digit}} to subpatterns and escaped backslashes.
  32 \end{funcdesc}
  33
  34 \begin{funcdesc}{gsub}{pat, repl, str}
  35 Replace all (non-overlapping) occurrences of pattern \var{pat} in
  36 string \var{str} by replacement \var{repl}.  The same rules as for
  37 \code{sub()} apply.  Empty matches for the pattern are replaced only
  38 when not adjacent to a previous match, so e.g.
  39 \code{gsub('', '-', 'abc')} returns \code{'-a-b-c-'}.
  40 \end{funcdesc}
  41
  42 \begin{funcdesc}{split}{str, pat\optional{, maxsplit}}
  43 Split the string \var{str} in fields separated by delimiters matching
  44 the pattern \var{pat}, and return a list containing the fields.  Only
  45 non-empty matches for the pattern are considered, so e.g.
  46 \code{split('a:b', ':*')} returns \code{['a', 'b']} and
  47 \code{split('abc', '')} returns \code{['abc']}.  The \var{maxsplit}
  48 defaults to 0. If it is nonzero, only \var{maxsplit} number of splits
  49 occur, and the remainder of the string is returned as the final
  50 element of the list.
  51 \end{funcdesc}
  52
  53 \begin{funcdesc}{splitx}{str, pat\optional{, maxsplit}}
  54 Split the string \var{str} in fields separated by delimiters matching
  55 the pattern \var{pat}, and return a list containing the fields as well
  56 as the separators.  For example, \code{splitx('a:::b', ':*')} returns
  57 \code{['a', ':::', 'b']}.  Otherwise, this function behaves the same
  58 as \code{split}.
  59 \end{funcdesc}
  60
  61 \begin{funcdesc}{capwords}{s\optional{, pat}}
  62 Capitalize words separated by optional pattern \var{pat}.  The default
  63 pattern uses any characters except letters, digits and underscores as
  64 word delimiters.  Capitalization is done by changing the first
  65 character of each word to upper case.
  66 \end{funcdesc}
  67
  68 \begin{funcdesc}{clear_cache}{}
  69 The regsub module maintains a cache of compiled regular expressions,
  70 keyed on the regular expression string and the syntax of the regex
  71 module at the time the expression was compiled.  This function clears
  72 that cache.
  73 \end{funcdesc}