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.
diff --git a/Doc/lib/liboperator.tex b/Doc/lib/liboperator.tex
index 9c7c389..e8348ed 100644
--- a/Doc/lib/liboperator.tex
+++ b/Doc/lib/liboperator.tex
@@ -12,65 +12,67 @@
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 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 @@
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 @@
\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 @@
{\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}