diff options
Diffstat (limited to 'Doc/lib/libstring.tex')
| -rw-r--r-- | Doc/lib/libstring.tex | 210 |
1 files changed, 107 insertions, 103 deletions
diff --git a/Doc/lib/libstring.tex b/Doc/lib/libstring.tex index f7189fd..4bf2903 100644 --- a/Doc/lib/libstring.tex +++ b/Doc/lib/libstring.tex @@ -57,187 +57,191 @@ The functions defined in this module are: \begin{funcdesc}{atof}{s} -Convert a string to a floating point number. The string must have -the standard syntax for a floating point literal in Python, optionally -preceded by a sign (\samp{+} or \samp{-}). Note that this behaves -identical to the built-in function -\function{float()}\bifuncindex{float} when passed a string. + Convert a string to a floating point number. The string must have + the standard syntax for a floating point literal in Python, + optionally preceded by a sign (\samp{+} or \samp{-}). Note that + this behaves identical to the built-in function + \function{float()}\bifuncindex{float} when passed a string. \end{funcdesc} \begin{funcdesc}{atoi}{s\optional{, base}} -Convert string \var{s} to an integer in the given \var{base}. The -string must consist of one or more digits, optionally preceded by a -sign (\samp{+} or \samp{-}). The \var{base} defaults to 10. If it is -0, a default base is chosen depending on the leading characters of the -string (after stripping the sign): \samp{0x} or \samp{0X} means 16, -\samp{0} means 8, anything else means 10. If \var{base} is 16, a -leading \samp{0x} or \samp{0X} is always accepted. Note that when -invoked without \var{base} or with \var{base} set to 10, this behaves -identical to the built-in function \function{int()} when passed a string. -(Also note: for a more flexible interpretation of numeric literals, -use the built-in function \function{eval()}\bifuncindex{eval}.) + Convert string \var{s} to an integer in the given \var{base}. The + string must consist of one or more digits, optionally preceded by a + sign (\samp{+} or \samp{-}). The \var{base} defaults to 10. If it + is 0, a default base is chosen depending on the leading characters + of the string (after stripping the sign): \samp{0x} or \samp{0X} + means 16, \samp{0} means 8, anything else means 10. If \var{base} + is 16, a leading \samp{0x} or \samp{0X} is always accepted. Note + that when invoked without \var{base} or with \var{base} set to 10, + this behaves identical to the built-in function \function{int()} + when passed a string. (Also note: for a more flexible + interpretation of numeric literals, use the built-in function + \function{eval()}\bifuncindex{eval}.) \end{funcdesc} \begin{funcdesc}{atol}{s\optional{, base}} -Convert string \var{s} to a long integer in the given \var{base}. The -string must consist of one or more digits, optionally preceded by a -sign (\samp{+} or \samp{-}). The \var{base} argument has the same -meaning as for \function{atoi()}. A trailing \samp{l} or \samp{L} is -not allowed, except if the base is 0. Note that when invoked without -\var{base} or with \var{base} set to 10, this behaves identical to the -built-in function \function{long()}\bifuncindex{long} when passed a -string. + Convert string \var{s} to a long integer in the given \var{base}. + The string must consist of one or more digits, optionally preceded + by a sign (\samp{+} or \samp{-}). The \var{base} argument has the + same meaning as for \function{atoi()}. A trailing \samp{l} or + \samp{L} is not allowed, except if the base is 0. Note that when + invoked without \var{base} or with \var{base} set to 10, this + behaves identical to the built-in function + \function{long()}\bifuncindex{long} when passed a string. \end{funcdesc} \begin{funcdesc}{capitalize}{word} -Capitalize the first character of the argument. + Capitalize the first character of the argument. \end{funcdesc} \begin{funcdesc}{capwords}{s} -Split the argument into words using \function{split()}, capitalize -each word using \function{capitalize()}, and join the capitalized -words using \function{join()}. Note that this replaces runs of -whitespace characters by a single space, and removes leading and -trailing whitespace. + Split the argument into words using \function{split()}, capitalize + each word using \function{capitalize()}, and join the capitalized + words using \function{join()}. Note that this replaces runs of + whitespace characters by a single space, and removes leading and + trailing whitespace. \end{funcdesc} \begin{funcdesc}{expandtabs}{s, tabsize} -Expand tabs in a string, i.e.\ replace them by one or more spaces, -depending on the current column and the given tab size. The column -number is reset to zero after each newline occurring in the string. -This doesn't understand other non-printing characters or escape -sequences. + Expand tabs in a string, i.e.\ replace them by one or more spaces, + depending on the current column and the given tab size. The column + number is reset to zero after each newline occurring in the string. + This doesn't understand other non-printing characters or escape + sequences. \end{funcdesc} \begin{funcdesc}{find}{s, sub\optional{, start\optional{,end}}} -Return the lowest index in \var{s} where the substring \var{sub} is -found such that \var{sub} is wholly contained in -\code{\var{s}[\var{start}:\var{end}]}. Return \code{-1} on failure. -Defaults for \var{start} and \var{end} and interpretation of negative -values is the same as for slices. + Return the lowest index in \var{s} where the substring \var{sub} is + found such that \var{sub} is wholly contained in + \code{\var{s}[\var{start}:\var{end}]}. Return \code{-1} on failure. + Defaults for \var{start} and \var{end} and interpretation of + negative values is the same as for slices. \end{funcdesc} \begin{funcdesc}{rfind}{s, sub\optional{, start\optional{, end}}} -Like \function{find()} but find the highest index. + Like \function{find()} but find the highest index. \end{funcdesc} \begin{funcdesc}{index}{s, sub\optional{, start\optional{, end}}} -Like \function{find()} but raise \exception{ValueError} when the -substring is not found. + Like \function{find()} but raise \exception{ValueError} when the + substring is not found. \end{funcdesc} \begin{funcdesc}{rindex}{s, sub\optional{, start\optional{, end}}} -Like \function{rfind()} but raise \exception{ValueError} when the -substring is not found. + Like \function{rfind()} but raise \exception{ValueError} when the + substring is not found. \end{funcdesc} \begin{funcdesc}{count}{s, sub\optional{, start\optional{, end}}} -Return the number of (non-overlapping) occurrences of substring -\var{sub} in string \code{\var{s}[\var{start}:\var{end}]}. -Defaults for \var{start} and \var{end} and interpretation of negative -values is the same as for slices. + Return the number of (non-overlapping) occurrences of substring + \var{sub} in string \code{\var{s}[\var{start}:\var{end}]}. + Defaults for \var{start} and \var{end} and interpretation of + negative values is the same as for slices. \end{funcdesc} \begin{funcdesc}{lower}{s} -Convert letters to lower case. + Return a copy of \var{s}, but with upper case letters converted to + lower case. \end{funcdesc} \begin{funcdesc}{maketrans}{from, to} -Return a translation table suitable for passing to -\function{translate()} or \function{regex.compile()}, that will map -each character in \var{from} into the character at the same position -in \var{to}; \var{from} and \var{to} must have the same length. + Return a translation table suitable for passing to + \function{translate()} or \function{regex.compile()}, that will map + each character in \var{from} into the character at the same position + in \var{to}; \var{from} and \var{to} must have the same length. -\strong{Warning:} don't use strings derived from \code{lowercase} and -\code{uppercase} as arguments; in some locales, these don't have the -same length. For case conversions, always use \function{lower()} and -\function{upper()}. + \strong{Warning:} don't use strings derived from \code{lowercase} + and \code{uppercase} as arguments; in some locales, these don't have + the same length. For case conversions, always use + \function{lower()} and \function{upper()}. \end{funcdesc} \begin{funcdesc}{split}{s\optional{, sep\optional{, maxsplit}}} -Return a list of the words of the string \var{s}. If the optional -second argument \var{sep} is absent or \code{None}, the words are -separated by arbitrary strings of whitespace characters (space, tab, -newline, return, formfeed). If the second argument \var{sep} is -present and not \code{None}, it specifies a string to be used as the -word separator. The returned list will then have one more items than -the number of non-overlapping occurrences of the separator in the -string. The optional third argument \var{maxsplit} defaults to 0. If -it is nonzero, at most \var{maxsplit} number of splits occur, and the -remainder of the string is returned as the final element of the list -(thus, the list will have at most \code{\var{maxsplit}+1} elements). + Return a list of the words of the string \var{s}. If the optional + second argument \var{sep} is absent or \code{None}, the words are + separated by arbitrary strings of whitespace characters (space, tab, + newline, return, formfeed). If the second argument \var{sep} is + present and not \code{None}, it specifies a string to be used as the + word separator. The returned list will then have one more items + than the number of non-overlapping occurrences of the separator in + the string. The optional third argument \var{maxsplit} defaults to + 0. If it is nonzero, at most \var{maxsplit} number of splits occur, + and the remainder of the string is returned as the final element of + the list (thus, the list will have at most \code{\var{maxsplit}+1} + elements). \end{funcdesc} \begin{funcdesc}{splitfields}{s\optional{, sep\optional{, maxsplit}}} -This function behaves identically to \function{split()}. (In the -past, \function{split()} was only used with one argument, while -\function{splitfields()} was only used with two arguments.) + This function behaves identically to \function{split()}. (In the + past, \function{split()} was only used with one argument, while + \function{splitfields()} was only used with two arguments.) \end{funcdesc} \begin{funcdesc}{join}{words\optional{, sep}} -Concatenate a list or tuple of words with intervening occurrences of -\var{sep}. The default value for \var{sep} is a single space -character. It is always true that -\samp{string.join(string.split(\var{s}, \var{sep}), \var{sep})} -equals \var{s}. + Concatenate a list or tuple of words with intervening occurrences of + \var{sep}. The default value for \var{sep} is a single space + character. It is always true that + \samp{string.join(string.split(\var{s}, \var{sep}), \var{sep})} + equals \var{s}. \end{funcdesc} \begin{funcdesc}{joinfields}{words\optional{, sep}} -This function behaves identical to \function{join()}. (In the past, -\function{join()} was only used with one argument, while -\function{joinfields()} was only used with two arguments.) + This function behaves identical to \function{join()}. (In the past, + \function{join()} was only used with one argument, while + \function{joinfields()} was only used with two arguments.) \end{funcdesc} \begin{funcdesc}{lstrip}{s} -Remove leading whitespace from the string \var{s}. + Return a copy of \var{s} but without leading whitespace characters. \end{funcdesc} \begin{funcdesc}{rstrip}{s} -Remove trailing whitespace from the string \var{s}. + Return a copy of \var{s} but without trailing whitespace + characters. \end{funcdesc} \begin{funcdesc}{strip}{s} -Remove leading and trailing whitespace from the string \var{s}. + Return a copy of \var{s} without leading or trailing whitespace. \end{funcdesc} \begin{funcdesc}{swapcase}{s} -Convert lower case letters to upper case and vice versa. + Return a copy of \var{s}, but with lower case letters + converted to upper case and vice versa. \end{funcdesc} \begin{funcdesc}{translate}{s, table\optional{, deletechars}} -Delete all characters from \var{s} that are in \var{deletechars} (if -present), and then translate the characters using \var{table}, which -must be a 256-character string giving the translation for each -character value, indexed by its ordinal. + Delete all characters from \var{s} that are in \var{deletechars} (if + present), and then translate the characters using \var{table}, which + must be a 256-character string giving the translation for each + character value, indexed by its ordinal. \end{funcdesc} \begin{funcdesc}{upper}{s} -Convert letters to upper case. + Return a copy of \var{s}, but with lower case letters converted to + upper case. \end{funcdesc} \begin{funcdesc}{ljust}{s, width} \funcline{rjust}{s, width} \funcline{center}{s, width} -These functions respectively left-justify, right-justify and center a -string in a field of given width. -They return a string that is at least -\var{width} -characters wide, created by padding the string -\var{s} -with spaces until the given width on the right, left or both sides. -The string is never truncated. + These functions respectively left-justify, right-justify and center + a string in a field of given width. They return a string that is at + least \var{width} characters wide, created by padding the string + \var{s} with spaces until the given width on the right, left or both + sides. The string is never truncated. \end{funcdesc} \begin{funcdesc}{zfill}{s, width} -Pad a numeric string on the left with zero digits until the given -width is reached. Strings starting with a sign are handled correctly. + Pad a numeric string on the left with zero digits until the given + width is reached. Strings starting with a sign are handled + correctly. \end{funcdesc} \begin{funcdesc}{replace}{str, old, new\optional{, maxsplit}} -Return a copy of string \var{str} with all occurrences of substring -\var{old} replaced by \var{new}. If the optional argument -\var{maxsplit} is given, the first \var{maxsplit} occurrences are -replaced. + Return a copy of string \var{str} with all occurrences of substring + \var{old} replaced by \var{new}. If the optional argument + \var{maxsplit} is given, the first \var{maxsplit} occurrences are + replaced. \end{funcdesc} This module is implemented in Python. Much of its functionality has |