Skip to content

C
cpython
Kaydet (Commit) e89659c0 authored tarafından Fred Drake's avatar Fred Drake
Dosyalara gözat
Seçenekler

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.
üst fcfc8d5c
Hide whitespace changes
Inline Side-by-side
Showing with 147 additions and 73 deletions
Doc/lib/liboperator.tex
Dosyayı görüntüle @ e89659c0
......@@ -12,55 +12,93 @@ 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.
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 and Boolean operations:
\begin{funcdesc}{add}{a, b}
\funcline{__add__}{a, b}
Return \var{a} \code{+} \var{b}, for \var{a} and \var{b} numbers.
\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}{sub}{a, b}
\funcline{__sub__}{a, b}
Return \var{a} \code{-} \var{b}.
\begin{funcdesc}{truth}{o}
Return \code{1} if \var{o} is true, and 0 otherwise.
\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}{div}{a, b}
\funcline{__div__}{a, b}
Return \var{a} \code{/} \var{b}.
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}{mod}{a, b}
\funcline{__mod__}{a, b}
Return \var{a} \code{\%} \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}{neg}{o}
\funcline{__neg__}{o}
Return \var{o} negated.
\begin{funcdesc}{and_}{a, b}
\funcline{__and__}{a, b}
Return the bitwise and of \var{a} and \var{b}.
\end{funcdesc}
\begin{funcdesc}{pos}{o}
\funcline{__pos__}{o}
Return \var{o} positive.
\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}{abs}{o}
\funcline{__abs__}{o}
Return the absolute value of \var{o}.
\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}. The names
\function{invert()} and \function{__invert__()} were added in Python
2.0.
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}
......@@ -68,14 +106,19 @@ Return the bitwise inverse of the number \var{o}. The names
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}{mod}{a, b}
\funcline{__mod__}{a, b}
Return \var{a} \code{\%} \var{b}.
\end{funcdesc}
\begin{funcdesc}{and_}{a, b}
\funcline{__and__}{a, b}
Return the bitwise and of \var{a} and \var{b}.
\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}
......@@ -83,33 +126,41 @@ Return the bitwise and of \var{a} and \var{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,17 +168,18 @@ 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}.
\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}
......@@ -135,19 +187,29 @@ Return the index of the first of occurrence of \var{b} in \var{a}.
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}.
\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}{delitem}{a, b}
\funcline{__delitem__}{a, b}
Remove the value of \var{a} at index \var{b}.
\begin{funcdesc}{indexOf}{a, b}
Return the index of the first of occurrence of \var{b} in \var{a}.
\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}.
\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}
......@@ -156,13 +218,9 @@ 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}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment