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 |
| 6 | classes, some exceptions, and some useful string functions. |
| 7 | The constants are: |
| 8 | |
| 9 | \renewcommand{\indexsubitem}{(data in module string)} |
| 10 | \begin{datadesc}{digits} |
| 11 | The string \code{'0123456789'}. |
| 12 | \end{datadesc} |
| 13 | |
| 14 | \begin{datadesc}{hexdigits} |
| 15 | The string \code{'0123456789abcdefABCDEF'}. |
| 16 | \end{datadesc} |
| 17 | |
| 18 | \begin{datadesc}{letters} |
| 19 | The concatenation of the strings \code{lowercase} and |
| 20 | \code{uppercase} described below. |
| 21 | \end{datadesc} |
| 22 | |
| 23 | \begin{datadesc}{lowercase} |
| 24 | A string containing all the characters that are considered lowercase |
| 25 | letters. On most systems this is the string |
| 26 | \code{'abcdefghijklmnopqrstuvwxyz'}. Do not change its definition -- |
| 27 | the effect on the routines \code{upper} and \code{swapcase} is |
| 28 | undefined. |
| 29 | \end{datadesc} |
| 30 | |
| 31 | \begin{datadesc}{octdigits} |
| 32 | The string \code{'01234567'}. |
| 33 | \end{datadesc} |
| 34 | |
| 35 | \begin{datadesc}{uppercase} |
| 36 | A string containing all the characters that are considered uppercase |
| 37 | letters. On most systems this is the string |
| 38 | \code{'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}. Do not change its definition -- |
| 39 | the effect on the routines \code{lower} and \code{swapcase} is |
| 40 | undefined. |
| 41 | \end{datadesc} |
| 42 | |
| 43 | \begin{datadesc}{whitespace} |
| 44 | A string containing all characters that are considered whitespace. |
| 45 | On most systems this includes the characters space, tab, linefeed, |
| 46 | return, formfeed, and vertical tab. Do not change its definition -- |
| 47 | the effect on the routines \code{strip} and \code{split} is |
| 48 | undefined. |
| 49 | \end{datadesc} |
| 50 | |
| 51 | The exceptions are: |
| 52 | |
| 53 | \renewcommand{\indexsubitem}{(exception in module string)} |
| 54 | |
| 55 | \begin{excdesc}{atof_error} |
| 56 | Exception raised by |
| 57 | \code{atof} |
| 58 | when a non-float string argument is detected. |
| 59 | The exception argument is the offending string. |
| 60 | \end{excdesc} |
| 61 | |
| 62 | \begin{excdesc}{atoi_error} |
| 63 | Exception raised by |
| 64 | \code{atoi} |
| 65 | when a non-integer string argument is detected. |
| 66 | The exception argument is the offending string. |
| 67 | \end{excdesc} |
| 68 | |
| 69 | \begin{excdesc}{atol_error} |
| 70 | Exception raised by |
| 71 | \code{atol} |
| 72 | when a non-integer string argument is detected. |
| 73 | The exception argument is the offending string. |
| 74 | \end{excdesc} |
| 75 | |
| 76 | \begin{excdesc}{index_error} |
| 77 | Exception raised by \code{index} when \var{sub} is not found. |
| 78 | The exception argument is undefined (it may be a tuple containing the |
| 79 | offending arguments to \code{index} or it may be the constant string |
| 80 | \code{'substring not found'}). |
| 81 | \end{excdesc} |
| 82 | |
| 83 | The functions are: |
| 84 | |
| 85 | \renewcommand{\indexsubitem}{(in module string)} |
| 86 | |
| 87 | \begin{funcdesc}{atof}{s} |
| 88 | Convert a string to a floating point number. The string must have |
| 89 | the standard syntax for a floating point literal in Python, optionally |
| 90 | preceded by a sign (\samp{+} or \samp{-}). |
| 91 | \end{funcdesc} |
| 92 | |
| 93 | \begin{funcdesc}{atoi}{s} |
| 94 | Convert a string to an integer. The string must consist of one or more |
| 95 | digits, optionally preceded by a sign (\samp{+} or \samp{-}). |
| 96 | \end{funcdesc} |
| 97 | |
| 98 | \begin{funcdesc}{atol}{s} |
| 99 | Convert a string to a long integer. The string must consist of one |
| 100 | or more digits, optionally preceded by a sign (\samp{+} or \samp{-}). |
| 101 | \end{funcdesc} |
| 102 | |
| 103 | \begin{funcdesc}{expandtabs}{s\, tabsize} |
| 104 | Expand tabs in a string, i.e. replace them by one or more spaces, |
| 105 | depending on the current column and the given tab size. The column |
| 106 | number is reset to zero after each newline occurring in the string. |
| 107 | This doesn't understand other non-printing characters or escape |
| 108 | sequences. |
| 109 | \end{funcdesc} |
| 110 | |
| 111 | \begin{funcdesc}{find}{s\, sub\, i} |
| 112 | Return the lowest index in \var{s} not smaller than \var{i} where the |
| 113 | substring \var{sub} is found. Return \code{-1} when \var{sub} |
| 114 | does not occur as a substring of \var{s} with index at least \var{i}. |
| 115 | If \var{i} is omitted, it defaults to \code{0}. If \var{i} is |
| 116 | negative, \code{len(\var{s})} is added. |
| 117 | \end{funcdesc} |
| 118 | |
| 119 | \begin{funcdesc}{rfind}{s\, sub\, i} |
| 120 | Like \code{find} but finds the highest index. |
| 121 | \end{funcdesc} |
| 122 | |
| 123 | \begin{funcdesc}{index}{s\, sub\, i} |
| 124 | Like \code{find} but raise \code{index_error} when the substring is |
| 125 | not found. |
| 126 | \end{funcdesc} |
| 127 | |
| 128 | \begin{funcdesc}{rindex}{s\, sub\, i} |
| 129 | Like \code{rfind} but raise \code{index_error} when the substring is |
| 130 | not found. |
| 131 | \end{funcdesc} |
| 132 | |
| 133 | \begin{funcdesc}{lower}{s} |
| 134 | Convert letters to lower case. |
| 135 | \end{funcdesc} |
| 136 | |
| 137 | \begin{funcdesc}{split}{s} |
| 138 | Returns a list of the whitespace-delimited words of the string |
| 139 | \var{s}. |
| 140 | \end{funcdesc} |
| 141 | |
| 142 | \begin{funcdesc}{splitfields}{s\, sep} |
| 143 | Returns a list containing the fields of the string \var{s}, using |
| 144 | the string \var{sep} as a separator. The list will have one more |
| 145 | items than the number of non-overlapping occurrences of the |
| 146 | separator in the string. Thus, \code{string.splitfields(\var{s}, ' |
| 147 | ')} is not the same as \code{string.split(\var{s})}, as the latter |
| 148 | only returns non-empty words. As a special case, |
| 149 | \code{splitfields(\var{s}, '')} returns \code{[\var{s}]}, for any string |
| 150 | \var{s}. (See also \code{regsub.split()}.) |
| 151 | \end{funcdesc} |
| 152 | |
| 153 | \begin{funcdesc}{join}{words} |
| 154 | Concatenate a list or tuple of words with intervening spaces. |
| 155 | \end{funcdesc} |
| 156 | |
| 157 | \begin{funcdesc}{joinfields}{words\, sep} |
| 158 | Concatenate a list or tuple of words with intervening separators. |
| 159 | It is always true that |
| 160 | \code{string.joinfields(string.splitfields(\var{t}, \var{sep}), \var{sep})} |
| 161 | equals \var{t}. |
| 162 | \end{funcdesc} |
| 163 | |
| 164 | \begin{funcdesc}{strip}{s} |
| 165 | Removes leading and trailing whitespace from the string |
| 166 | \var{s}. |
| 167 | \end{funcdesc} |
| 168 | |
| 169 | \begin{funcdesc}{swapcase}{s} |
| 170 | Converts lower case letters to upper case and vice versa. |
| 171 | \end{funcdesc} |
| 172 | |
| 173 | \begin{funcdesc}{upper}{s} |
| 174 | Convert letters to upper case. |
| 175 | \end{funcdesc} |
| 176 | |
| 177 | \begin{funcdesc}{ljust}{s\, width} |
| 178 | \funcline{rjust}{s\, width} |
| 179 | \funcline{center}{s\, width} |
| 180 | These functions respectively left-justify, right-justify and center a |
| 181 | string in a field of given width. |
| 182 | They return a string that is at least |
| 183 | \var{width} |
| 184 | characters wide, created by padding the string |
| 185 | \var{s} |
| 186 | with spaces until the given width on the right, left or both sides. |
| 187 | The string is never truncated. |
| 188 | \end{funcdesc} |
| 189 | |
| 190 | \begin{funcdesc}{zfill}{s\, width} |
| 191 | Pad a numeric string on the left with zero digits until the given |
| 192 | width is reached. Strings starting with a sign are handled correctly. |
| 193 | \end{funcdesc} |