Doc/libstring.tex

   1 \section{Standard Module \sectcode{string}}
   2
   3 \stmodindex{string}
   4
   5 This module defines some constants useful for checking character
   6 classes and some useful string functions.  See the modules
   7 \code{regex} and \code{regsub} for string functions based on regular
   8 expressions.
   9
  10 The constants defined in this module are are:
  11
  12 \renewcommand{\indexsubitem}{(data in module string)}
  13 \begin{datadesc}{digits}
  14   The string \code{'0123456789'}.
  15 \end{datadesc}
  16
  17 \begin{datadesc}{hexdigits}
  18   The string \code{'0123456789abcdefABCDEF'}.
  19 \end{datadesc}
  20
  21 \begin{datadesc}{letters}
  22   The concatenation of the strings \code{lowercase} and
  23   \code{uppercase} described below.
  24 \end{datadesc}
  25
  26 \begin{datadesc}{lowercase}
  27   A string containing all the characters that are considered lowercase
  28   letters.  On most systems this is the string
  29   \code{'abcdefghijklmnopqrstuvwxyz'}.  Do not change its definition ---
  30   the effect on the routines \code{upper} and \code{swapcase} is
  31   undefined.
  32 \end{datadesc}
  33
  34 \begin{datadesc}{octdigits}
  35   The string \code{'01234567'}.
  36 \end{datadesc}
  37
  38 \begin{datadesc}{uppercase}
  39   A string containing all the characters that are considered uppercase
  40   letters.  On most systems this is the string
  41   \code{'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}.  Do not change its definition ---
  42   the effect on the routines \code{lower} and \code{swapcase} is
  43   undefined.
  44 \end{datadesc}
  45
  46 \begin{datadesc}{whitespace}
  47   A string containing all characters that are considered whitespace.
  48   On most systems this includes the characters space, tab, linefeed,
  49   return, formfeed, and vertical tab.  Do not change its definition ---
  50   the effect on the routines \code{strip} and \code{split} is
  51   undefined.
  52 \end{datadesc}
  53
  54 The functions defined in this module are:
  55
  56 \renewcommand{\indexsubitem}{(in module string)}
  57
  58 \begin{funcdesc}{atof}{s}
  59 Convert a string to a floating point number.  The string must have
  60 the standard syntax for a floating point literal in Python, optionally
  61 preceded by a sign (\samp{+} or \samp{-}).
  62 \end{funcdesc}
  63
  64 \begin{funcdesc}{atoi}{s\optional{\, base}}
  65 Convert string \var{s} to an integer in the given \var{base}.  The
  66 string must consist of one or more digits, optionally preceded by a
  67 sign (\samp{+} or \samp{-}).  The \var{base} defaults to 10.  If it is
  68 0, a default base is chosen depending on the leading characters of the
  69 string (after stripping the sign): \samp{0x} or \samp{0X} means 16,
  70 \samp{0} means 8, anything else means 10.  If \var{base} is 16, a
  71 leading \samp{0x} or \samp{0X} is always accepted.  (Note: for a more
  72 flexible interpretation of numeric literals, use the built-in function
  73 \code{eval()}.)
  74 \bifuncindex{eval}
  75 \end{funcdesc}
  76
  77 \begin{funcdesc}{atol}{s\optional{\, base}}
  78 Convert string \var{s} to a long integer in the given \var{base}.  The
  79 string must consist of one or more digits, optionally preceded by a
  80 sign (\samp{+} or \samp{-}).  The \var{base} argument has the same
  81 meaning as for \code{atoi()}.  A trailing \samp{l} or \samp{L} is not
  82 allowed, except if the base is 0.
  83 \end{funcdesc}
  84
  85 \begin{funcdesc}{expandtabs}{s\, tabsize}
  86 Expand tabs in a string, i.e.\ replace them by one or more spaces,
  87 depending on the current column and the given tab size.  The column
  88 number is reset to zero after each newline occurring in the string.
  89 This doesn't understand other non-printing characters or escape
  90 sequences.
  91 \end{funcdesc}
  92
  93 \begin{funcdesc}{find}{s\, sub\optional{\, start}}
  94 Return the lowest index in \var{s} not smaller than \var{start} where the
  95 substring \var{sub} is found.  Return \code{-1} when \var{sub}
  96 does not occur as a substring of \var{s} with index at least \var{start}.
  97 If \var{start} is omitted, it defaults to \code{0}.  If \var{start} is
  98 negative, \code{len(\var{s})} is added.
  99 \end{funcdesc}
 100
 101 \begin{funcdesc}{rfind}{s\, sub\optional{\, start}}
 102 Like \code{find} but find the highest index.
 103 \end{funcdesc}
 104
 105 \begin{funcdesc}{index}{s\, sub\optional{\, start}}
 106 Like \code{find} but raise \code{ValueError} when the substring is
 107 not found.
 108 \end{funcdesc}
 109
 110 \begin{funcdesc}{rindex}{s\, sub\optional{\, start}}
 111 Like \code{rfind} but raise \code{ValueError} when the substring is
 112 not found.
 113 \end{funcdesc}
 114
 115 \begin{funcdesc}{count}{s\, sub\optional{\, start}}
 116 Return the number of (non-overlapping) occurrences of substring
 117 \var{sub} in string \var{s} with index at least \var{start}.
 118 If \var{start} is omitted, it defaults to \code{0}.  If \var{start} is
 119 negative, \code{len(\var{s})} is added.
 120 \end{funcdesc}
 121
 122 \begin{funcdesc}{lower}{s}
 123 Convert letters to lower case.
 124 \end{funcdesc}
 125
 126 \begin{funcdesc}{split}{s}
 127 Return a list of the whitespace-delimited words of the string
 128 \var{s}.
 129 \end{funcdesc}
 130
 131 \begin{funcdesc}{splitfields}{s\, sep}
 132   Return a list containing the fields of the string \var{s}, using
 133   the string \var{sep} as a separator.  The list will have one more
 134   items than the number of non-overlapping occurrences of the
 135   separator in the string.  Thus, \code{string.splitfields(\var{s}, '
 136   ')} is not the same as \code{string.split(\var{s})}, as the latter
 137   only returns non-empty words.  As a special case,
 138   \code{splitfields(\var{s}, '')} returns \code{[\var{s}]}, for any string
 139   \var{s}.  (See also \code{regsub.split()}.)
 140 \end{funcdesc}
 141
 142 \begin{funcdesc}{join}{words}
 143 Concatenate a list or tuple of words with intervening spaces.
 144 \end{funcdesc}
 145
 146 \begin{funcdesc}{joinfields}{words\, sep}
 147 Concatenate a list or tuple of words with intervening separators.
 148 It is always true that
 149 \code{string.joinfields(string.splitfields(\var{t}, \var{sep}), \var{sep})}
 150 equals \var{t}.
 151 \end{funcdesc}
 152
 153 \begin{funcdesc}{strip}{s}
 154 Remove leading and trailing whitespace from the string
 155 \var{s}.
 156 \end{funcdesc}
 157
 158 \begin{funcdesc}{swapcase}{s}
 159 Convert lower case letters to upper case and vice versa.
 160 \end{funcdesc}
 161
 162 \begin{funcdesc}{translate}{s, table}
 163 Translate the characters from \var{s} using \var{table}, which must be
 164 a 256-character string giving the translation for each character
 165 value, indexed by its ordinal.
 166 \end{funcdesc}
 167
 168 \begin{funcdesc}{upper}{s}
 169 Convert letters to upper case.
 170 \end{funcdesc}
 171
 172 \begin{funcdesc}{ljust}{s\, width}
 173 \funcline{rjust}{s\, width}
 174 \funcline{center}{s\, width}
 175 These functions respectively left-justify, right-justify and center a
 176 string in a field of given width.
 177 They return a string that is at least
 178 \var{width}
 179 characters wide, created by padding the string
 180 \var{s}
 181 with spaces until the given width on the right, left or both sides.
 182 The string is never truncated.
 183 \end{funcdesc}
 184
 185 \begin{funcdesc}{zfill}{s\, width}
 186 Pad a numeric string on the left with zero digits until the given
 187 width is reached.  Strings starting with a sign are handled correctly.
 188 \end{funcdesc}
 189
 190 This module is implemented in Python.  Much of its functionality has
 191 been reimplemented in the built-in module \code{strop}.  However, you
 192 should \emph{never} import the latter module directly.  When
 193 \code{string} discovers that \code{strop} exists, it transparently
 194 replaces parts of itself with the implementation from \code{strop}.
 195 After initialization, there is \emph{no} overhead in using
 196 \code{string} instead of \code{strop}.
 197 \bimodindex{strop}