mirror of https://github.com/python/cpython
244 lines
9.4 KiB
TeX
244 lines
9.4 KiB
TeX
\section{Standard Module \sectcode{string}}
|
|
\label{module-string}
|
|
\stmodindex{string}
|
|
|
|
This module defines some constants useful for checking character
|
|
classes and some useful string functions. See the module
|
|
\module{re}\refstmodindex{re} for string functions based on regular
|
|
expressions.
|
|
|
|
The constants defined in this module are are:
|
|
|
|
\setindexsubitem{(data in module string)}
|
|
\begin{datadesc}{digits}
|
|
The string \code{'0123456789'}.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{hexdigits}
|
|
The string \code{'0123456789abcdefABCDEF'}.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{letters}
|
|
The concatenation of the strings \function{lowercase()} and
|
|
\function{uppercase()} described below.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{lowercase}
|
|
A string containing all the characters that are considered lowercase
|
|
letters. On most systems this is the string
|
|
\code{'abcdefghijklmnopqrstuvwxyz'}. Do not change its definition ---
|
|
the effect on the routines \function{upper()} and
|
|
\function{swapcase()} is undefined.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{octdigits}
|
|
The string \code{'01234567'}.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{uppercase}
|
|
A string containing all the characters that are considered uppercase
|
|
letters. On most systems this is the string
|
|
\code{'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}. Do not change its definition ---
|
|
the effect on the routines \function{lower()} and
|
|
\function{swapcase()} is undefined.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{whitespace}
|
|
A string containing all characters that are considered whitespace.
|
|
On most systems this includes the characters space, tab, linefeed,
|
|
return, formfeed, and vertical tab. Do not change its definition ---
|
|
the effect on the routines \function{strip()} and \function{split()}
|
|
is undefined.
|
|
\end{datadesc}
|
|
|
|
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.
|
|
\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}.)
|
|
\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.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{capitalize}{word}
|
|
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.
|
|
\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.
|
|
\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.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{rfind}{s, sub\optional{, start\optional{, end}}}
|
|
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.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{rindex}{s, sub\optional{, start\optional{, end}}}
|
|
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.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{lower}{s}
|
|
Convert letters 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.
|
|
\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).
|
|
\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.)
|
|
\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}.
|
|
\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.)
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{lstrip}{s}
|
|
Remove leading whitespace from the string \var{s}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{rstrip}{s}
|
|
Remove trailing whitespace from the string \var{s}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{strip}{s}
|
|
Remove leading and trailing whitespace from the string \var{s}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{swapcase}{s}
|
|
Convert lower case letters 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.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{upper}{s}
|
|
Convert letters 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.
|
|
\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.
|
|
\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.
|
|
\end{funcdesc}
|
|
|
|
This module is implemented in Python. Much of its functionality has
|
|
been reimplemented in the built-in module
|
|
\module{strop}\refbimodindex{strop}. However, you
|
|
should \emph{never} import the latter module directly. When
|
|
\module{string} discovers that \module{strop} exists, it transparently
|
|
replaces parts of itself with the implementation from \module{strop}.
|
|
After initialization, there is \emph{no} overhead in using
|
|
\module{string} instead of \module{strop}.
|