Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

Added documentation for the new rich comparison support. 

This closes SF patch #428320.

Added documentation for the new floordiv() and truediv() functions.
This is part of SF bug #449093.

Re-organized the listing of functions to get better logical grouping.
This commit is contained in:
Fred Drake 2001-08-10 15:55:09 +00:00
parent fcfc8d5c0e
commit e89659c02d
1 changed files with 160 additions and 86 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

246
Doc/lib/liboperator.tex
View File

@ -12,65 +12,67 @@ corresponding to the intrinsic operators of Python. For example,
function names are those used for special class methods; variants without
leading and trailing \samp{__} are also provided for convenience.
The \module{operator} module defines the following functions:
The functions fall into categories that perform object comparisons,
logical operations, mathematical operations, sequence operations, and
abstract type tests.
\begin{funcdesc}{add}{a, b}
\funcline{__add__}{a, b}
Return \var{a} \code{+} \var{b}, for \var{a} and \var{b} numbers.
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}
\begin{funcdesc}{sub}{a, b}
\funcline{__sub__}{a, b}
Return \var{a} \code{-} \var{b}.
The logical operations are also generally applicable to all objects,
and support truth 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}{mul}{a, b}
\funcline{__mul__}{a, b}
Return \var{a} \code{*} \var{b}, for \var{a} and \var{b} numbers.
\begin{funcdesc}{truth}{o}
Return \code{1} if \var{o} is true, and 0 otherwise.
\end{funcdesc}
\begin{funcdesc}{div}{a, b}
\funcline{__div__}{a, b}
Return \var{a} \code{/} \var{b}.
\end{funcdesc}
\begin{funcdesc}{mod}{a, b}
\funcline{__mod__}{a, b}
Return \var{a} \code{\%} \var{b}.
\end{funcdesc}
\begin{funcdesc}{neg}{o}
\funcline{__neg__}{o}
Return \var{o} negated.
\end{funcdesc}
\begin{funcdesc}{pos}{o}
\funcline{__pos__}{o}
Return \var{o} positive.
\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}{inv}{o}
\funcline{invert}{o}
\funcline{__inv__}{o}
\funcline{__invert__}{o}
Return the bitwise inverse of the number \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}{rshift}{a, b}
\funcline{__rshift__}{a, b}
Return \var{a} shifted right by \var{b}.
\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}
@ -78,38 +80,87 @@ Return \var{a} shifted right by \var{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}{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}
\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.)
\end{funcdesc}
\begin{funcdesc}{truth}{o}
Return \code{1} if \var{o} is true, and 0 otherwise.
\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}{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}{contains}{a, b}
\funcline{__contains__}{a, b}
Return the outcome of the test \var{b} \code{in} \var{a}.
@ -117,52 +168,59 @@ Note the reversed operands. The name \function{__contains__()} was
added in Python 2.0.
\end{funcdesc}
\begin{funcdesc}{sequenceIncludes}{\unspecified}
\deprecated{2.0}{Use \function{contains()} instead.}
Alias for \function{contains()}.
\end{funcdesc}
\begin{funcdesc}{countOf}{a, b}
Return the number of occurrences of \var{b} in \var{a}.
\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}{getitem}{a, b}
\funcline{__getitem__}{a, b}
Return the value of \var{a} at index \var{b}.
\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}{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}
\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}
The \module{operator} also defines a few predicates to test the type
of objects. \strong{Note:} Be careful not to misinterpret the
The \module{operator} module also defines a few predicates to test the
type of objects. \strong{Note:} Be careful not to misinterpret the
results of these functions; only \function{isCallable()} has any
measure of reliability with instance objects. For example:
@ -239,7 +297,11 @@ symbols in the Python syntax and the functions in the
\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})}}
{\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}}}
@ -280,4 +342,16 @@ symbols in the Python syntax and the functions in the
{\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}