[Python-checkins] CVS: python/dist/src/Doc/lib liboperator.tex,1.19,1.20
Fred L. Drake
fdrake@users.sourceforge.net
Fri, 10 Aug 2001 08:55:12 -0700
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory usw-pr-cvs1:/tmp/cvs-serv22135/lib
Modified Files:
liboperator.tex
Log Message:
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.
Index: liboperator.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/liboperator.tex,v
retrieving revision 1.19
retrieving revision 1.20
diff -C2 -d -r1.19 -r1.20
*** liboperator.tex 2000/12/15 05:41:49 1.19
--- liboperator.tex 2001/08/10 15:55:09 1.20
***************
*** 13,56 ****
leading and trailing \samp{__} are also provided for convenience.
! The \module{operator} module defines the following functions:
! \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}{sub}{a, b}
! \funcline{__sub__}{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}{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}
! \begin{funcdesc}{abs}{o}
! \funcline{__abs__}{o}
! Return the absolute value of \var{o}.
\end{funcdesc}
--- 13,94 ----
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 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 \code{1} if \var{o} is true, and 0 otherwise.
\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}
***************
*** 59,65 ****
\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}
--- 97,103 ----
\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}
***************
*** 69,80 ****
\end{funcdesc}
! \begin{funcdesc}{rshift}{a, b}
! \funcline{__rshift__}{a, b}
! Return \var{a} shifted right by \var{b}.
\end{funcdesc}
! \begin{funcdesc}{and_}{a, b}
! \funcline{__and__}{a, b}
! Return the bitwise and of \var{a} and \var{b}.
\end{funcdesc}
--- 107,123 ----
\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}
***************
*** 84,87 ****
--- 127,152 ----
\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}
***************
*** 89,102 ****
\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}
\begin{funcdesc}{concat}{a, b}
--- 154,159 ----
\end{funcdesc}
! Operations which work with sequences include:
\begin{funcdesc}{concat}{a, b}
***************
*** 105,114 ****
\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}
--- 162,165 ----
***************
*** 118,132 ****
\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}
--- 169,184 ----
\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}
***************
*** 136,152 ****
\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}{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}
--- 188,214 ----
\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}
***************
*** 157,167 ****
\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
results of these functions; only \function{isCallable()} has any
measure of reliability with instance objects. For example:
--- 219,225 ----
\end{funcdesc}
! 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:
***************
*** 240,244 ****
{\code{contains(\var{seq}, \var{o})}}
\lineiii{Division}{\code{\var{a} / \var{b}}}
! {\code{div(\var{a}, \var{b})}}
\lineiii{Bitwise And}{\code{\var{a} \&\ \var{b}}}
{\code{and_(\var{a}, \var{b})}}
--- 298,306 ----
{\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})}}
***************
*** 281,283 ****
--- 343,357 ----
\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}