From e89659c02d5490780d736e1d38ba5e0196e15679 Mon Sep 17 00:00:00 2001 From: Fred Drake Date: Fri, 10 Aug 2001 15:55:09 +0000 Subject: [PATCH] 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. --- Doc/lib/liboperator.tex | 246 ++++++++++++++++++++++++++-------------- 1 file changed, 160 insertions(+), 86 deletions(-) diff --git a/Doc/lib/liboperator.tex b/Doc/lib/liboperator.tex index 9c7c3892ed2..e8348eda832 100644 --- a/Doc/lib/liboperator.tex +++ b/Doc/lib/liboperator.tex @@ -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}