[Python-checkins] python/dist/src/Doc/lib libstdtypes.tex,1.118,1.119
mwh@users.sourceforge.net
mwh@users.sourceforge.net
Wed, 05 Mar 2003 06:42:15 -0800
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv5741
Modified Files:
libstdtypes.tex
Log Message:
Back in June in revision 1.98 Steve (accidentally, presumably) wiped
out a month's worth of checkins to libstdtypes.tex (including my
extended slice docs).
I think this checkin merges them all back in, but if you make one of
these checkins:
revision 1.97
date: 2002/06/14 00:27:13; author: nnorwitz
Use \code{True} (or False) instead of true/false.
Not sure if code is correct, but that is what's in this file.
I've seen \constant{True} in other places.
----------------------------
revision 1.95
date: 2002/05/22 20:39:43; author: bwarsaw
Jack's documentation for the U mode character on the file()
constructor, vetted by Barry.
----------------------------
revision 1.94
date: 2002/05/21 18:19:15; author: rhettinger
Patch 543387. Document deprecation of complex %, //,and divmod().
----------------------------
revision 1.93
date: 2002/05/15 15:45:25; author: rhettinger
Added missing index entries for mapping methods. Closes patch
#548693.
some checking may be in order.
Index: libstdtypes.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libstdtypes.tex,v
retrieving revision 1.118
retrieving revision 1.119
diff -C2 -d -r1.118 -r1.119
*** libstdtypes.tex 17 Feb 2003 18:57:06 -0000 1.118
--- libstdtypes.tex 5 Mar 2003 14:42:09 -0000 1.119
***************
*** 229,234 ****
\bifuncindex{complex}
! All numeric types support the following operations, sorted by
! ascending priority (operations in the same box have the same
priority; all numeric operations have a higher priority than
comparison operations):
--- 229,234 ----
\bifuncindex{complex}
! All numeric types (except complex) support the following operations,
! sorted by ascending priority (operations in the same box have the same
priority; all numeric operations have a higher priority than
comparison operations):
***************
*** 240,244 ****
\lineiii{\var{x} * \var{y}}{product of \var{x} and \var{y}}{}
\lineiii{\var{x} / \var{y}}{quotient of \var{x} and \var{y}}{(1)}
! \lineiii{\var{x} \%{} \var{y}}{remainder of \code{\var{x} / \var{y}}}{}
\hline
\lineiii{-\var{x}}{\var{x} negated}{}
--- 240,244 ----
\lineiii{\var{x} * \var{y}}{product of \var{x} and \var{y}}{}
\lineiii{\var{x} / \var{y}}{quotient of \var{x} and \var{y}}{(1)}
! \lineiii{\var{x} \%{} \var{y}}{remainder of \code{\var{x} / \var{y}}}{(4)}
\hline
\lineiii{-\var{x}}{\var{x} negated}{}
***************
*** 251,255 ****
\lineiii{complex(\var{re},\var{im})}{a complex number with real part \var{re}, imaginary part \var{im}. \var{im} defaults to zero.}{}
\lineiii{\var{c}.conjugate()}{conjugate of the complex number \var{c}}{}
! \lineiii{divmod(\var{x}, \var{y})}{the pair \code{(\var{x} / \var{y}, \var{x} \%{} \var{y})}}{(3)}
\lineiii{pow(\var{x}, \var{y})}{\var{x} to the power \var{y}}{}
\lineiii{\var{x} ** \var{y}}{\var{x} to the power \var{y}}{}
--- 251,255 ----
\lineiii{complex(\var{re},\var{im})}{a complex number with real part \var{re}, imaginary part \var{im}. \var{im} defaults to zero.}{}
\lineiii{\var{c}.conjugate()}{conjugate of the complex number \var{c}}{}
! \lineiii{divmod(\var{x}, \var{y})}{the pair \code{(\var{x} / \var{y}, \var{x} \%{} \var{y})}}{(3)(4)}
\lineiii{pow(\var{x}, \var{y})}{\var{x} to the power \var{y}}{}
\lineiii{\var{x} ** \var{y}}{\var{x} to the power \var{y}}{}
***************
*** 284,287 ****
--- 284,293 ----
description.
+ \item[(4)]
+ Complex floor division operator, modulo operator, and \function{divmod()}.
+
+ \deprecated{2.3}{Instead convert to float using \function{abs()}
+ if appropriate.}
+
\end{description}
% XXXJH exceptions: overflow (when? what operations?) zerodivision
***************
*** 443,446 ****
--- 449,453 ----
\lineiii{\var{s}[\var{i}]}{\var{i}'th item of \var{s}, origin 0}{(3)}
\lineiii{\var{s}[\var{i}:\var{j}]}{slice of \var{s} from \var{i} to \var{j}}{(3), (4)}
+ \lineiii{\var{s}[\var{i}:\var{j}:\var{k}]}{slice of \var{s} from \var{i} to \var{j} with step \var{k}}{(3), (5)}
\hline
\lineiii{len(\var{s})}{length of \var{s}}{}
***************
*** 456,459 ****
--- 463,467 ----
\indexii{subscript}{operation}
\indexii{slice}{operation}
+ \indexii{extended slice}{operation}
\opindex{in}
\opindex{not in}
***************
*** 507,510 ****
--- 515,527 ----
use \code{0}. If \var{j} is omitted, use \code{len(\var{s})}. If
\var{i} is greater than or equal to \var{j}, the slice is empty.
+
+ \item[(5)] The slice of \var{s} from \var{i} to \var{j} with step
+ \var{k} is defined as the sequence of items with index
+ \code{\var{x} = \var{i} + \var{n}*\var{k}} such that \code{0}
+ \code{<=} \var{n} \code{<} \code{abs(i-j)}. If \var{i} or \var{j}
+ is greater than \code{len(\var{s})}, use \code{len(\var{s})}. If
+ \var{i} or \var{j} are ommitted then they become ``end'' values
+ (which end depends on the sign of \var{k}).
+
\end{description}
***************
*** 551,556 ****
\begin{methoddesc}[string]{endswith}{suffix\optional{, start\optional{, end}}}
! Return true if the string ends with the specified \var{suffix},
! otherwise return false. With optional \var{start}, test beginning at
that position. With optional \var{end}, stop comparing at that position.
\end{methoddesc}
--- 568,573 ----
\begin{methoddesc}[string]{endswith}{suffix\optional{, start\optional{, end}}}
! Return \code{True} if the string ends with the specified \var{suffix},
! otherwise return \code{False}. With optional \var{start}, test beginning at
that position. With optional \var{end}, stop comparing at that position.
\end{methoddesc}
***************
*** 684,689 ****
\begin{methoddesc}[string]{startswith}{prefix\optional{,
start\optional{, end}}}
! Return true if string starts with the \var{prefix}, otherwise
! return false. With optional \var{start}, test string beginning at
that position. With optional \var{end}, stop comparing string at that
position.
--- 701,706 ----
\begin{methoddesc}[string]{startswith}{prefix\optional{,
start\optional{, end}}}
! Return \code{True} if string starts with the \var{prefix}, otherwise
! return \code{False}. With optional \var{start}, test string beginning at
that position. With optional \var{end}, stop comparing string at that
position.
***************
*** 912,934 ****
\lineiii{del \var{s}[\var{i}:\var{j}]}
{same as \code{\var{s}[\var{i}:\var{j}] = []}}{}
\lineiii{\var{s}.append(\var{x})}
! {same as \code{\var{s}[len(\var{s}):len(\var{s})] = [\var{x}]}}{(1)}
\lineiii{\var{s}.extend(\var{x})}
! {same as \code{\var{s}[len(\var{s}):len(\var{s})] = \var{x}}}{(2)}
\lineiii{\var{s}.count(\var{x})}
{return number of \var{i}'s for which \code{\var{s}[\var{i}] == \var{x}}}{}
\lineiii{\var{s}.index(\var{x})}
! {return smallest \var{i} such that \code{\var{s}[\var{i}] == \var{x}}}{(3)}
\lineiii{\var{s}.insert(\var{i}, \var{x})}
{same as \code{\var{s}[\var{i}:\var{i}] = [\var{x}]}
! if \code{\var{i} >= 0}}{(4)}
\lineiii{\var{s}.pop(\optional{\var{i}})}
! {same as \code{\var{x} = \var{s}[\var{i}]; del \var{s}[\var{i}]; return \var{x}}}{(5)}
\lineiii{\var{s}.remove(\var{x})}
! {same as \code{del \var{s}[\var{s}.index(\var{x})]}}{(3)}
\lineiii{\var{s}.reverse()}
! {reverses the items of \var{s} in place}{(6)}
\lineiii{\var{s}.sort(\optional{\var{cmpfunc=None}})}
! {sort the items of \var{s} in place}{(6), (7), (8), (9)}
\end{tableiii}
\indexiv{operations on}{mutable}{sequence}{types}
--- 929,955 ----
\lineiii{del \var{s}[\var{i}:\var{j}]}
{same as \code{\var{s}[\var{i}:\var{j}] = []}}{}
+ \lineiii{\var{s}[\var{i}:\var{j}:\var{k}] = \var{t}}
+ {the elements of \code{\var{s}[\var{i}:\var{j}:\var{k}]} are replaced by those of \var{t}}{(1)}
+ \lineiii{del \var{s}[\var{i}:\var{j}:\var{k}]}
+ {removes the elements of \code{\var{s}[\var{i}:\var{j}:\var{k}]} from the list}{}
\lineiii{\var{s}.append(\var{x})}
! {same as \code{\var{s}[len(\var{s}):len(\var{s})] = [\var{x}]}}{(2)}
\lineiii{\var{s}.extend(\var{x})}
! {same as \code{\var{s}[len(\var{s}):len(\var{s})] = \var{x}}}{(3)}
\lineiii{\var{s}.count(\var{x})}
{return number of \var{i}'s for which \code{\var{s}[\var{i}] == \var{x}}}{}
\lineiii{\var{s}.index(\var{x})}
! {return smallest \var{i} such that \code{\var{s}[\var{i}] == \var{x}}}{(4)}
\lineiii{\var{s}.insert(\var{i}, \var{x})}
{same as \code{\var{s}[\var{i}:\var{i}] = [\var{x}]}
! if \code{\var{i} >= 0}}{(5)}
\lineiii{\var{s}.pop(\optional{\var{i}})}
! {same as \code{\var{x} = \var{s}[\var{i}]; del \var{s}[\var{i}]; return \var{x}}}{(6)}
\lineiii{\var{s}.remove(\var{x})}
! {same as \code{del \var{s}[\var{s}.index(\var{x})]}}{(4)}
\lineiii{\var{s}.reverse()}
! {reverses the items of \var{s} in place}{(7)}
\lineiii{\var{s}.sort(\optional{\var{cmpfunc=None}})}
! {sort the items of \var{s} in place}{(7), (8), (9), (10)}
\end{tableiii}
\indexiv{operations on}{mutable}{sequence}{types}
***************
*** 937,940 ****
--- 958,962 ----
\indexii{subscript}{assignment}
\indexii{slice}{assignment}
+ \indexii{extended slice}{assignment}
\stindex{del}
\withsubitem{(list method)}{
***************
*** 945,972 ****
Notes:
\begin{description}
! \item[(1)] The C implementation of Python historically accepted
! multiple parameters and implicitly joined them into a tuple;
! Use of this misfeature has been deprecated since Python 1.4,
! and became an error with the introduction of Python 2.0.
! \item[(2)] Raises an exception when \var{x} is not an iterable object.
! \item[(3)] Raises \exception{ValueError} when \var{x} is not found in
\var{s}.
! \item[(4)] When a negative index is passed as the first parameter to
the \method{insert()} method, the new element is prepended to the
sequence.
! \item[(5)] The \method{pop()} method is only supported by the list and
array types. The optional argument \var{i} defaults to \code{-1},
so that by default the last item is removed and returned.
! \item[(6)] The \method{sort()} and \method{reverse()} methods modify the
list in place for economy of space when sorting or reversing a large
list. To remind you that they operate by side effect, they don't return
the sorted or reversed list.
! \item[(7)] The \method{sort()} method takes an optional argument
specifying a comparison function of two arguments (list items) which
should return a negative, zero or positive number depending on whether
--- 967,999 ----
Notes:
\begin{description}
! \item[(1)] \var{t} must have the same length as the slice it is
! replacing.
! \item[(2)] The C implementation of Python has historically accepted
! multiple parameters and implicitly joined them into a tuple; this
! no longer works in Python 2.0. Use of this misfeature has been
! deprecated since Python 1.4.
! \item[(3)] Raises an exception when \var{x} is not a list object. The
! \method{extend()} method is experimental and not supported by
! mutable sequence types other than lists.
!
! \item[(4)] Raises \exception{ValueError} when \var{x} is not found in
\var{s}.
! \item[(5)] When a negative index is passed as the first parameter to
the \method{insert()} method, the new element is prepended to the
sequence.
! \item[(6)] The \method{pop()} method is only supported by the list and
array types. The optional argument \var{i} defaults to \code{-1},
so that by default the last item is removed and returned.
! \item[(7)] The \method{sort()} and \method{reverse()} methods modify the
list in place for economy of space when sorting or reversing a large
list. To remind you that they operate by side effect, they don't return
the sorted or reversed list.
! \item[(8)] The \method{sort()} method takes an optional argument
specifying a comparison function of two arguments (list items) which
should return a negative, zero or positive number depending on whether
***************
*** 980,984 ****
\method{sort()} with no comparison function.
! \item[(8)] Whether the \method{sort()} method is stable is not defined by
the language (a sort is stable if it guarantees not to change the
relative order of elements that compare equal). In the C
--- 1007,1011 ----
\method{sort()} with no comparison function.
! \item[(9)] Whether the \method{sort()} method is stable is not defined by
the language (a sort is stable if it guarantees not to change the
relative order of elements that compare equal). In the C
***************
*** 988,992 ****
implementations and versions must not rely on stability.
! \item[(9)] While a list is being sorted, the effect of attempting to
mutate, or even inspect, the list is undefined. The C implementation
of Python 2.3 makes the list appear empty for the duration, and raises
--- 1015,1019 ----
implementations and versions must not rely on stability.
! \item[(10)] While a list is being sorted, the effect of attempting to
mutate, or even inspect, the list is undefined. The C implementation
of Python 2.3 makes the list appear empty for the duration, and raises
***************
*** 1031,1035 ****
\ttindex{update()}
\ttindex{values()}
! \ttindex{get()}}
\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
--- 1058,1068 ----
\ttindex{update()}
\ttindex{values()}
! \ttindex{get()}
! \ttindex{setdefault()}
! \ttindex{pop()}
! \ttindex{popitem()}
! \ttindex{iteritems()}
! \ttindex{iterkeys)}
! \ttindex{itervalues()}}
\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
***************
*** 1321,1324 ****
--- 1354,1369 ----
file object, of the form \samp{<\mbox{\ldots}>}. This is a read-only
attribute and may not be present on all file-like objects.
+ \end{memberdesc}
+
+ \begin{memberdesc}[file]{newlines}
+ If Python was built with the \code{--with-universal-newlines} option
+ (the default) this read-only attribute exists, and for files opened in
+ universal newline read mode it keeps track of the types of newlines
+ encountered while reading the file. The values it can take are
+ \code{'\e r'}, \code{'\e n'}, \code{'\e r\e n'}, \code{None} (unknown,
+ no newlines read yet) or a tuple containing all the newline
+ types seen, to indicate that multiple
+ newline conventions were encountered. For files not opened in universal
+ newline read mode the value of this attribute will be \code{None}.
\end{memberdesc}