Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 1 | \section{Standard Module \sectcode{string}} |
| 2 | |
| 3 | \stmodindex{string} |
| 4 | |
| 5 | This module defines some constants useful for checking character |
Guido van Rossum | 0bf4d89 | 1995-03-02 12:37:30 +0000 | [diff] [blame] | 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: |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 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 |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 29 | \code{'abcdefghijklmnopqrstuvwxyz'}. Do not change its definition --- |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 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 |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 41 | \code{'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}. Do not change its definition --- |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 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, |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 49 | return, formfeed, and vertical tab. Do not change its definition --- |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 50 | the effect on the routines \code{strip} and \code{split} is |
| 51 | undefined. |
| 52 | \end{datadesc} |
| 53 | |
Guido van Rossum | 0bf4d89 | 1995-03-02 12:37:30 +0000 | [diff] [blame] | 54 | The functions defined in this module are: |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 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 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 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 |
Guido van Rossum | 96628a9 | 1995-04-10 11:34:00 +0000 | [diff] [blame] | 73 | \code{eval()}.) |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 74 | \bifuncindex{eval} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 75 | \end{funcdesc} |
| 76 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 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 |
Guido van Rossum | 264302d | 1996-02-12 23:20:12 +0000 | [diff] [blame] | 82 | allowed, except if the base is 0. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 83 | \end{funcdesc} |
| 84 | |
Guido van Rossum | e5e55d7 | 1996-08-09 21:44:51 +0000 | [diff] [blame] | 85 | \begin{funcdesc}{capitalize}{word} |
| 86 | Capitalize the first character of the argument. |
| 87 | \end{funcdesc} |
| 88 | |
| 89 | \begin{funcdesc}{capwords}{s} |
| 90 | Split the argument into words using \code{split}, capitalize each word |
| 91 | using \code{capitalize}, and join the capitalized words using |
| 92 | \code{join}. Note that this replaces runs of whitespace characters by |
| 93 | a single space. (See also \code{regsub.capwords()} for a version |
| 94 | that doesn't change the delimiters, and lets you specify a word |
| 95 | separator.) |
| 96 | \end{funcdesc} |
| 97 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 98 | \begin{funcdesc}{expandtabs}{s\, tabsize} |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 99 | Expand tabs in a string, i.e.\ replace them by one or more spaces, |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 100 | depending on the current column and the given tab size. The column |
| 101 | number is reset to zero after each newline occurring in the string. |
| 102 | This doesn't understand other non-printing characters or escape |
| 103 | sequences. |
| 104 | \end{funcdesc} |
| 105 | |
Guido van Rossum | 7b7c578 | 1997-03-14 04:13:56 +0000 | [diff] [blame] | 106 | \begin{funcdesc}{find}{s\, sub\optional{\, start\optional{\,end}}} |
| 107 | Return the lowest index in \var{s} not smaller than \var{start} and not |
| 108 | greater than \var{end} where the substring \var{sub} is found. Return |
| 109 | \code{-1} when \var{sub} does not occur as a substring of \var{s} with |
| 110 | index at least \var{start} and less than \var{end}. |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +0000 | [diff] [blame] | 111 | If \var{start} is omitted, it defaults to \code{0}. If \var{start} is |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 112 | negative, \code{len(\var{s})} is added. |
Guido van Rossum | 7b7c578 | 1997-03-14 04:13:56 +0000 | [diff] [blame] | 113 | If \var{end} is omitted, it defaults to \code{len(\var{s})}. If |
| 114 | \var{end} is negative, \code{len(\var{s})} is added. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 115 | \end{funcdesc} |
| 116 | |
Guido van Rossum | 7b7c578 | 1997-03-14 04:13:56 +0000 | [diff] [blame] | 117 | \begin{funcdesc}{rfind}{s\, sub\optional{\, start\optional{\,end}}} |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 118 | Like \code{find} but find the highest index. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 119 | \end{funcdesc} |
| 120 | |
Guido van Rossum | 7b7c578 | 1997-03-14 04:13:56 +0000 | [diff] [blame] | 121 | \begin{funcdesc}{index}{s\, sub\optional{\, start\optional{\,end}}} |
Guido van Rossum | 2828e9d | 1994-08-17 13:16:34 +0000 | [diff] [blame] | 122 | Like \code{find} but raise \code{ValueError} when the substring is |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 123 | not found. |
| 124 | \end{funcdesc} |
| 125 | |
Guido van Rossum | 7b7c578 | 1997-03-14 04:13:56 +0000 | [diff] [blame] | 126 | \begin{funcdesc}{rindex}{s\, sub\optional{\, start\optional{\,end}}} |
Guido van Rossum | 2828e9d | 1994-08-17 13:16:34 +0000 | [diff] [blame] | 127 | Like \code{rfind} but raise \code{ValueError} when the substring is |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 128 | not found. |
| 129 | \end{funcdesc} |
| 130 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 131 | \begin{funcdesc}{count}{s\, sub\optional{\, start}} |
Guido van Rossum | ab3a250 | 1994-08-01 12:18:36 +0000 | [diff] [blame] | 132 | Return the number of (non-overlapping) occurrences of substring |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 133 | \var{sub} in string \var{s} with index at least \var{start}. |
| 134 | If \var{start} is omitted, it defaults to \code{0}. If \var{start} is |
| 135 | negative, \code{len(\var{s})} is added. |
Guido van Rossum | ab3a250 | 1994-08-01 12:18:36 +0000 | [diff] [blame] | 136 | \end{funcdesc} |
| 137 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 138 | \begin{funcdesc}{lower}{s} |
| 139 | Convert letters to lower case. |
| 140 | \end{funcdesc} |
| 141 | |
Guido van Rossum | f4d0d57 | 1996-07-30 18:23:05 +0000 | [diff] [blame] | 142 | \begin{funcdesc}{maketrans}{from, to} |
| 143 | Return a translation table suitable for passing to \code{string.translate} |
| 144 | or \code{regex.compile}, that will map each character in \var{from} |
| 145 | into the character at the same position in \var{to}; \var{from} and |
| 146 | \var{to} must have the same length. |
| 147 | \end{funcdesc} |
| 148 | |
Guido van Rossum | e5e55d7 | 1996-08-09 21:44:51 +0000 | [diff] [blame] | 149 | \begin{funcdesc}{split}{s\optional{\, sep\optional{\, maxsplit}}} |
| 150 | Return a list of the words of the string \var{s}. If the optional |
| 151 | second argument \var{sep} is absent or \code{None}, the words are |
| 152 | separated by arbitrary strings of whitespace characters (space, tab, |
| 153 | newline, return, formfeed). If the second argument \var{sep} is |
| 154 | present and not \code{None}, it specifies a string to be used as the |
| 155 | word separator. The returned list will then have one more items than |
| 156 | the number of non-overlapping occurrences of the separator in the |
| 157 | string. The optional third argument \var{maxsplit} defaults to 0. If |
| 158 | it is nonzero, at most \var{maxsplit} number of splits occur, and the |
| 159 | remainder of the string is returned as the final element of the list |
| 160 | (thus, the list will have at most \code{\var{maxsplit}+1} elements). |
| 161 | (See also \code{regsub.split()} for a version that allows specifying a |
| 162 | regular expression as the separator.) |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 163 | \end{funcdesc} |
| 164 | |
Guido van Rossum | e5e55d7 | 1996-08-09 21:44:51 +0000 | [diff] [blame] | 165 | \begin{funcdesc}{splitfields}{s\optional{\, sep\optional{\, maxsplit}}} |
| 166 | This function behaves identical to \code{split}. (In the past, |
| 167 | \code{split} was only used with one argument, while \code{splitfields} |
| 168 | was only used with two arguments.) |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 169 | \end{funcdesc} |
| 170 | |
Guido van Rossum | e5e55d7 | 1996-08-09 21:44:51 +0000 | [diff] [blame] | 171 | \begin{funcdesc}{join}{words\optional{\, sep}} |
| 172 | Concatenate a list or tuple of words with intervening occurrences of |
| 173 | \var{sep}. The default value for \var{sep} is a single space character. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 174 | It is always true that |
Guido van Rossum | e5e55d7 | 1996-08-09 21:44:51 +0000 | [diff] [blame] | 175 | \code{string.join(string.split(\var{s}, \var{sep}), \var{sep})} |
| 176 | equals \var{s}. |
| 177 | \end{funcdesc} |
| 178 | |
| 179 | \begin{funcdesc}{joinfields}{words\optional{\, sep}} |
| 180 | This function behaves identical to \code{join}. (In the past, |
| 181 | \code{join} was only used with one argument, while \code{joinfields} |
| 182 | was only used with two arguments.) |
| 183 | \end{funcdesc} |
| 184 | |
| 185 | \begin{funcdesc}{lstrip}{s} |
| 186 | Remove leading whitespace from the string \var{s}. |
| 187 | \end{funcdesc} |
| 188 | |
| 189 | \begin{funcdesc}{rstrip}{s} |
| 190 | Remove trailing whitespace from the string \var{s}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 191 | \end{funcdesc} |
| 192 | |
| 193 | \begin{funcdesc}{strip}{s} |
Guido van Rossum | e5e55d7 | 1996-08-09 21:44:51 +0000 | [diff] [blame] | 194 | Remove leading and trailing whitespace from the string \var{s}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 195 | \end{funcdesc} |
| 196 | |
| 197 | \begin{funcdesc}{swapcase}{s} |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 198 | Convert lower case letters to upper case and vice versa. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 199 | \end{funcdesc} |
| 200 | |
Guido van Rossum | f4d0d57 | 1996-07-30 18:23:05 +0000 | [diff] [blame] | 201 | \begin{funcdesc}{translate}{s, table\optional{, deletechars}} |
| 202 | Delete all characters from \var{s} that are in \var{deletechars} (if present), and |
| 203 | then translate the characters using \var{table}, which must be |
Guido van Rossum | f65f278 | 1995-09-13 17:37:21 +0000 | [diff] [blame] | 204 | a 256-character string giving the translation for each character |
Guido van Rossum | f4d0d57 | 1996-07-30 18:23:05 +0000 | [diff] [blame] | 205 | value, indexed by its ordinal. |
Guido van Rossum | f65f278 | 1995-09-13 17:37:21 +0000 | [diff] [blame] | 206 | \end{funcdesc} |
| 207 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 208 | \begin{funcdesc}{upper}{s} |
| 209 | Convert letters to upper case. |
| 210 | \end{funcdesc} |
| 211 | |
| 212 | \begin{funcdesc}{ljust}{s\, width} |
| 213 | \funcline{rjust}{s\, width} |
| 214 | \funcline{center}{s\, width} |
| 215 | These functions respectively left-justify, right-justify and center a |
| 216 | string in a field of given width. |
| 217 | They return a string that is at least |
| 218 | \var{width} |
| 219 | characters wide, created by padding the string |
| 220 | \var{s} |
| 221 | with spaces until the given width on the right, left or both sides. |
| 222 | The string is never truncated. |
| 223 | \end{funcdesc} |
| 224 | |
| 225 | \begin{funcdesc}{zfill}{s\, width} |
| 226 | Pad a numeric string on the left with zero digits until the given |
| 227 | width is reached. Strings starting with a sign are handled correctly. |
| 228 | \end{funcdesc} |
Guido van Rossum | 0bf4d89 | 1995-03-02 12:37:30 +0000 | [diff] [blame] | 229 | |
Guido van Rossum | c8a80cd | 1997-03-25 16:41:31 +0000 | [diff] [blame^] | 230 | \begin{funcdesc}{replace}{old, new, str} |
| 231 | Return a copy of string \var{str} with all occurrences of substring |
| 232 | \var{old} replaced by \var{new}. |
| 233 | \end{funcdesc} |
| 234 | |
| 235 | \begin{funcdesc}{replace1}{old, new, str\optional{, start\optional{, end}}} |
| 236 | Return a copy of string \var{str} with the first occurrence of |
| 237 | substring \var{old} replaced by \var{new}. If no occurrence is found, |
| 238 | \var{str} is returned unchanged. Optional arguments \var{start} and |
| 239 | \var{end} limit the search for \var{old} like for \code{find} (they |
| 240 | are not used to slice the result). |
| 241 | \end{funcdesc} |
| 242 | |
Guido van Rossum | 0bf4d89 | 1995-03-02 12:37:30 +0000 | [diff] [blame] | 243 | This module is implemented in Python. Much of its functionality has |
| 244 | been reimplemented in the built-in module \code{strop}. However, you |
| 245 | should \emph{never} import the latter module directly. When |
| 246 | \code{string} discovers that \code{strop} exists, it transparently |
| 247 | replaces parts of itself with the implementation from \code{strop}. |
| 248 | After initialization, there is \emph{no} overhead in using |
| 249 | \code{string} instead of \code{strop}. |
| 250 | \bimodindex{strop} |