mirror of https://github.com/python/cpython
415 lines
14 KiB
TeX
415 lines
14 KiB
TeX
\section{\module{operator} ---
|
|
Standard operators as functions.}
|
|
\declaremodule{builtin}{operator}
|
|
\sectionauthor{Skip Montanaro}{skip@automatrix.com}
|
|
|
|
\modulesynopsis{All Python's standard operators as built-in functions.}
|
|
|
|
|
|
The \module{operator} module exports a set of functions implemented in C
|
|
corresponding to the intrinsic operators of Python. For example,
|
|
\code{operator.add(x, y)} is equivalent to the expression \code{x+y}. The
|
|
function names are those used for special class methods; variants without
|
|
leading and trailing \samp{__} are also provided for convenience.
|
|
|
|
The functions fall into categories that perform object comparisons,
|
|
logical operations, mathematical operations, sequence operations, and
|
|
abstract type tests.
|
|
|
|
The object comparison functions are useful for all objects, and are
|
|
named after the rich comparison operators they support:
|
|
|
|
\begin{funcdesc}{lt}{a, b}
|
|
\funcline{le}{a, b}
|
|
\funcline{eq}{a, b}
|
|
\funcline{ne}{a, b}
|
|
\funcline{ge}{a, b}
|
|
\funcline{gt}{a, b}
|
|
\funcline{__lt__}{a, b}
|
|
\funcline{__le__}{a, b}
|
|
\funcline{__eq__}{a, b}
|
|
\funcline{__ne__}{a, b}
|
|
\funcline{__ge__}{a, b}
|
|
\funcline{__gt__}{a, b}
|
|
Perform ``rich comparisons'' between \var{a} and \var{b}. Specifically,
|
|
\code{lt(\var{a}, \var{b})} is equivalent to \code{\var{a} < \var{b}},
|
|
\code{le(\var{a}, \var{b})} is equivalent to \code{\var{a} <= \var{b}},
|
|
\code{eq(\var{a}, \var{b})} is equivalent to \code{\var{a} == \var{b}},
|
|
\code{ne(\var{a}, \var{b})} is equivalent to \code{\var{a} != \var{b}},
|
|
\code{gt(\var{a}, \var{b})} is equivalent to \code{\var{a} > \var{b}}
|
|
and
|
|
\code{ge(\var{a}, \var{b})} is equivalent to \code{\var{a} >= \var{b}}.
|
|
Note that unlike the built-in \function{cmp()}, these functions can
|
|
return any value, which may or may not be interpretable as a Boolean
|
|
value. See the \citetitle[../ref/ref.html]{Python Reference Manual}
|
|
for more informations about rich comparisons.
|
|
\versionadded{2.2}
|
|
\end{funcdesc}
|
|
|
|
|
|
The logical operations are also generally applicable to all objects,
|
|
and support truth tests, identity tests, and boolean operations:
|
|
|
|
\begin{funcdesc}{not_}{o}
|
|
\funcline{__not__}{o}
|
|
Return the outcome of \keyword{not} \var{o}. (Note that there is no
|
|
\method{__not__()} method for object instances; only the interpreter
|
|
core defines this operation. The result is affected by the
|
|
\method{__nonzero__()} and \method{__len__()} methods.)
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{truth}{o}
|
|
Return \constant{True} if \var{o} is true, and \constant{False}
|
|
otherwise. This is equivalent to using the \class{bool}
|
|
constructor.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{is_}{a, b}
|
|
Return \code{\var{a} is \var{b}}. Tests object identity.
|
|
\versionadded{2.3}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{is_not}{a, b}
|
|
Return \code{\var{a} is not \var{b}}. Tests object identity.
|
|
\versionadded{2.3}
|
|
\end{funcdesc}
|
|
|
|
|
|
The mathematical and bitwise operations are the most numerous:
|
|
|
|
\begin{funcdesc}{abs}{o}
|
|
\funcline{__abs__}{o}
|
|
Return the absolute value of \var{o}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{add}{a, b}
|
|
\funcline{__add__}{a, b}
|
|
Return \var{a} \code{+} \var{b}, for \var{a} and \var{b} numbers.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{and_}{a, b}
|
|
\funcline{__and__}{a, b}
|
|
Return the bitwise and of \var{a} and \var{b}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{div}{a, b}
|
|
\funcline{__div__}{a, b}
|
|
Return \var{a} \code{/} \var{b} when \code{__future__.division} is not
|
|
in effect. This is also known as ``classic'' division.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{floordiv}{a, b}
|
|
\funcline{__floordiv__}{a, b}
|
|
Return \var{a} \code{//} \var{b}.
|
|
\versionadded{2.2}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{inv}{o}
|
|
\funcline{invert}{o}
|
|
\funcline{__inv__}{o}
|
|
\funcline{__invert__}{o}
|
|
Return the bitwise inverse of the number \var{o}. This is equivalent
|
|
to \code{\textasciitilde}\var{o}. The names \function{invert()} and
|
|
\function{__invert__()} were added in Python 2.0.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{lshift}{a, b}
|
|
\funcline{__lshift__}{a, b}
|
|
Return \var{a} shifted left by \var{b}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{mod}{a, b}
|
|
\funcline{__mod__}{a, b}
|
|
Return \var{a} \code{\%} \var{b}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{mul}{a, b}
|
|
\funcline{__mul__}{a, b}
|
|
Return \var{a} \code{*} \var{b}, for \var{a} and \var{b} numbers.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{neg}{o}
|
|
\funcline{__neg__}{o}
|
|
Return \var{o} negated.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{or_}{a, b}
|
|
\funcline{__or__}{a, b}
|
|
Return the bitwise or of \var{a} and \var{b}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{pos}{o}
|
|
\funcline{__pos__}{o}
|
|
Return \var{o} positive.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{pow}{a, b}
|
|
\funcline{__pow__}{a, b}
|
|
Return \var{a} \code{**} \var{b}, for \var{a} and \var{b} numbers.
|
|
\versionadded{2.3}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{rshift}{a, b}
|
|
\funcline{__rshift__}{a, b}
|
|
Return \var{a} shifted right by \var{b}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{sub}{a, b}
|
|
\funcline{__sub__}{a, b}
|
|
Return \var{a} \code{-} \var{b}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{truediv}{a, b}
|
|
\funcline{__truediv__}{a, b}
|
|
Return \var{a} \code{/} \var{b} when \code{__future__.division} is in
|
|
effect. This is also known as division.
|
|
\versionadded{2.2}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{xor}{a, b}
|
|
\funcline{__xor__}{a, b}
|
|
Return the bitwise exclusive or of \var{a} and \var{b}.
|
|
\end{funcdesc}
|
|
|
|
|
|
Operations which work with sequences include:
|
|
|
|
\begin{funcdesc}{concat}{a, b}
|
|
\funcline{__concat__}{a, b}
|
|
Return \var{a} \code{+} \var{b} for \var{a} and \var{b} sequences.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{contains}{a, b}
|
|
\funcline{__contains__}{a, b}
|
|
Return the outcome of the test \var{b} \code{in} \var{a}.
|
|
Note the reversed operands. The name \function{__contains__()} was
|
|
added in Python 2.0.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{countOf}{a, b}
|
|
Return the number of occurrences of \var{b} in \var{a}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{delitem}{a, b}
|
|
\funcline{__delitem__}{a, b}
|
|
Remove the value of \var{a} at index \var{b}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{delslice}{a, b, c}
|
|
\funcline{__delslice__}{a, b, c}
|
|
Delete the slice of \var{a} from index \var{b} to index \var{c}\code{-1}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getitem}{a, b}
|
|
\funcline{__getitem__}{a, b}
|
|
Return the value of \var{a} at index \var{b}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getslice}{a, b, c}
|
|
\funcline{__getslice__}{a, b, c}
|
|
Return the slice of \var{a} from index \var{b} to index \var{c}\code{-1}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{indexOf}{a, b}
|
|
Return the index of the first of occurrence of \var{b} in \var{a}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{repeat}{a, b}
|
|
\funcline{__repeat__}{a, b}
|
|
Return \var{a} \code{*} \var{b} where \var{a} is a sequence and
|
|
\var{b} is an integer.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{sequenceIncludes}{\unspecified}
|
|
\deprecated{2.0}{Use \function{contains()} instead.}
|
|
Alias for \function{contains()}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{setitem}{a, b, c}
|
|
\funcline{__setitem__}{a, b, c}
|
|
Set the value of \var{a} at index \var{b} to \var{c}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{setslice}{a, b, c, v}
|
|
\funcline{__setslice__}{a, b, c, v}
|
|
Set the slice of \var{a} from index \var{b} to index \var{c}\code{-1} to the
|
|
sequence \var{v}.
|
|
\end{funcdesc}
|
|
|
|
|
|
The \module{operator} module also defines a few predicates to test the
|
|
type of objects. \note{Be careful not to misinterpret the
|
|
results of these functions; only \function{isCallable()} has any
|
|
measure of reliability with instance objects. For example:}
|
|
|
|
\begin{verbatim}
|
|
>>> class C:
|
|
... pass
|
|
...
|
|
>>> import operator
|
|
>>> o = C()
|
|
>>> operator.isMappingType(o)
|
|
True
|
|
\end{verbatim}
|
|
|
|
\begin{funcdesc}{isCallable}{o}
|
|
\deprecated{2.0}{Use the \function{callable()} built-in function instead.}
|
|
Returns true if the object \var{o} can be called like a function,
|
|
otherwise it returns false. True is returned for functions, bound and
|
|
unbound methods, class objects, and instance objects which support the
|
|
\method{__call__()} method.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{isMappingType}{o}
|
|
Returns true if the object \var{o} supports the mapping interface.
|
|
This is true for dictionaries and all instance objects.
|
|
\warning{There is no reliable way to test if an instance
|
|
supports the complete mapping protocol since the interface itself is
|
|
ill-defined. This makes this test less useful than it otherwise might
|
|
be.}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{isNumberType}{o}
|
|
Returns true if the object \var{o} represents a number. This is true
|
|
for all numeric types implemented in C, and for all instance objects.
|
|
\warning{There is no reliable way to test if an instance
|
|
supports the complete numeric interface since the interface itself is
|
|
ill-defined. This makes this test less useful than it otherwise might
|
|
be.}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{isSequenceType}{o}
|
|
Returns true if the object \var{o} supports the sequence protocol.
|
|
This returns true for all objects which define sequence methods in C,
|
|
and for all instance objects. \warning{There is no reliable
|
|
way to test if an instance supports the complete sequence interface
|
|
since the interface itself is ill-defined. This makes this test less
|
|
useful than it otherwise might be.}
|
|
\end{funcdesc}
|
|
|
|
|
|
Example: Build a dictionary that maps the ordinals from \code{0} to
|
|
\code{256} to their character equivalents.
|
|
|
|
\begin{verbatim}
|
|
>>> import operator
|
|
>>> d = {}
|
|
>>> keys = range(256)
|
|
>>> vals = map(chr, keys)
|
|
>>> map(operator.setitem, [d]*len(keys), keys, vals)
|
|
\end{verbatim}
|
|
|
|
|
|
The \module{operator} module also defines tools for generalized attribute
|
|
and item lookups. These are useful for making fast field extractors
|
|
as arguments for \function{map()}, \method{list.sort()},
|
|
\method{itertools.groupby()}, or other functions that expect a
|
|
function argument.
|
|
|
|
\begin{funcdesc}{attrgetter}{attr}
|
|
Return a callable object that fetches \var{attr} from its operand.
|
|
After, \samp{f=attrgetter('name')}, the call \samp{f(b)} returns
|
|
\samp{b.name}.
|
|
\versionadded{2.4}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{itemgetter}{item}
|
|
Return a callable object that fetches \var{item} from its operand.
|
|
After, \samp{f=itemgetter(2)}, the call \samp{f(b)} returns
|
|
\samp{b[2]}.
|
|
\versionadded{2.4}
|
|
\end{funcdesc}
|
|
|
|
Examples:
|
|
|
|
\begin{verbatim}
|
|
>>> from operator import *
|
|
>>> inventory = [('apple', 3), ('banana', 2), ('pear', 5), ('orange', 1)]
|
|
>>> getcount = itemgetter(1)
|
|
>>> map(getcount, inventory)
|
|
[3, 2, 5, 1]
|
|
>>> list.sorted(inventory, key=getcount)
|
|
[('orange', 1), ('banana', 2), ('apple', 3), ('pear', 5)]
|
|
\end{verbatim}
|
|
|
|
|
|
\subsection{Mapping Operators to Functions \label{operator-map}}
|
|
|
|
This table shows how abstract operations correspond to operator
|
|
symbols in the Python syntax and the functions in the
|
|
\refmodule{operator} module.
|
|
|
|
|
|
\begin{tableiii}{l|c|l}{textrm}{Operation}{Syntax}{Function}
|
|
\lineiii{Addition}{\code{\var{a} + \var{b}}}
|
|
{\code{add(\var{a}, \var{b})}}
|
|
\lineiii{Concatenation}{\code{\var{seq1} + \var{seq2}}}
|
|
{\code{concat(\var{seq1}, \var{seq2})}}
|
|
\lineiii{Containment Test}{\code{\var{o} in \var{seq}}}
|
|
{\code{contains(\var{seq}, \var{o})}}
|
|
\lineiii{Division}{\code{\var{a} / \var{b}}}
|
|
{\code{div(\var{a}, \var{b}) \#} without \code{__future__.division}}
|
|
\lineiii{Division}{\code{\var{a} / \var{b}}}
|
|
{\code{truediv(\var{a}, \var{b}) \#} with \code{__future__.division}}
|
|
\lineiii{Division}{\code{\var{a} // \var{b}}}
|
|
{\code{floordiv(\var{a}, \var{b})}}
|
|
\lineiii{Bitwise And}{\code{\var{a} \&\ \var{b}}}
|
|
{\code{and_(\var{a}, \var{b})}}
|
|
\lineiii{Bitwise Exclusive Or}{\code{\var{a} \^\ \var{b}}}
|
|
{\code{xor(\var{a}, \var{b})}}
|
|
\lineiii{Bitwise Inversion}{\code{\~{} \var{a}}}
|
|
{\code{invert(\var{a})}}
|
|
\lineiii{Bitwise Or}{\code{\var{a} | \var{b}}}
|
|
{\code{or_(\var{a}, \var{b})}}
|
|
\lineiii{Exponentiation}{\code{\var{a} ** \var{b}}}
|
|
{\code{pow(\var{a}, \var{b})}}
|
|
\lineiii{Identity}{\code{\var{a} is \var{b}}}
|
|
{\code{is_(\var{a}, \var{b})}}
|
|
\lineiii{Identity}{\code{\var{a} is not \var{b}}}
|
|
{\code{is_not(\var{a}, \var{b})}}
|
|
\lineiii{Indexed Assignment}{\code{\var{o}[\var{k}] = \var{v}}}
|
|
{\code{setitem(\var{o}, \var{k}, \var{v})}}
|
|
\lineiii{Indexed Deletion}{\code{del \var{o}[\var{k}]}}
|
|
{\code{delitem(\var{o}, \var{k})}}
|
|
\lineiii{Indexing}{\code{\var{o}[\var{k}]}}
|
|
{\code{getitem(\var{o}, \var{k})}}
|
|
\lineiii{Left Shift}{\code{\var{a} <\code{<} \var{b}}}
|
|
{\code{lshift(\var{a}, \var{b})}}
|
|
\lineiii{Modulo}{\code{\var{a} \%\ \var{b}}}
|
|
{\code{mod(\var{a}, \var{b})}}
|
|
\lineiii{Multiplication}{\code{\var{a} * \var{b}}}
|
|
{\code{mul(\var{a}, \var{b})}}
|
|
\lineiii{Negation (Arithmetic)}{\code{- \var{a}}}
|
|
{\code{neg(\var{a})}}
|
|
\lineiii{Negation (Logical)}{\code{not \var{a}}}
|
|
{\code{not_(\var{a})}}
|
|
\lineiii{Right Shift}{\code{\var{a} >\code{>} \var{b}}}
|
|
{\code{rshift(\var{a}, \var{b})}}
|
|
\lineiii{Sequence Repitition}{\code{\var{seq} * \var{i}}}
|
|
{\code{repeat(\var{seq}, \var{i})}}
|
|
\lineiii{Slice Assignment}{\code{\var{seq}[\var{i}:\var{j}]} = \var{values}}
|
|
{\code{setslice(\var{seq}, \var{i}, \var{j}, \var{values})}}
|
|
\lineiii{Slice Deletion}{\code{del \var{seq}[\var{i}:\var{j}]}}
|
|
{\code{delslice(\var{seq}, \var{i}, \var{j})}}
|
|
\lineiii{Slicing}{\code{\var{seq}[\var{i}:\var{j}]}}
|
|
{\code{getslice(\var{seq}, \var{i}, \var{j})}}
|
|
\lineiii{String Formatting}{\code{\var{s} \%\ \var{o}}}
|
|
{\code{mod(\var{s}, \var{o})}}
|
|
\lineiii{Subtraction}{\code{\var{a} - \var{b}}}
|
|
{\code{sub(\var{a}, \var{b})}}
|
|
\lineiii{Truth Test}{\code{\var{o}}}
|
|
{\code{truth(\var{o})}}
|
|
\lineiii{Ordering}{\code{\var{a} < \var{b}}}
|
|
{\code{lt(\var{a}, \var{b})}}
|
|
\lineiii{Ordering}{\code{\var{a} <= \var{b}}}
|
|
{\code{le(\var{a}, \var{b})}}
|
|
\lineiii{Equality}{\code{\var{a} == \var{b}}}
|
|
{\code{eq(\var{a}, \var{b})}}
|
|
\lineiii{Difference}{\code{\var{a} != \var{b}}}
|
|
{\code{ne(\var{a}, \var{b})}}
|
|
\lineiii{Ordering}{\code{\var{a} >= \var{b}}}
|
|
{\code{ge(\var{a}, \var{b})}}
|
|
\lineiii{Ordering}{\code{\var{a} > \var{b}}}
|
|
{\code{gt(\var{a}, \var{b})}}
|
|
\end{tableiii}
|