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.

1 files changed, 74 insertions, 29 deletions

diff --git a/Doc/lib/libstdtypes.tex b/Doc/lib/libstdtypes.tex
index f6b6369..0006c76 100644
--- a/Doc/lib/libstdtypes.tex
+++ b/Doc/lib/libstdtypes.tex
@@ -228,8 +228,8 @@ to produce numbers of a specific type.
 \bifuncindex{float}
 \bifuncindex{complex}
 
-All numeric types support the following operations, sorted by
-ascending priority (operations in the same box have the same
+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):
 
@@ -239,7 +239,7 @@ comparison operations):
   \hline
   \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}}}{}
+  \lineiii{\var{x} \%{} \var{y}}{remainder of \code{\var{x} / \var{y}}}{(4)}
   \hline
   \lineiii{-\var{x}}{\var{x} negated}{}
   \lineiii{+\var{x}}{\var{x} unchanged}{}
@@ -250,7 +250,7 @@ comparison operations):
   \lineiii{float(\var{x})}{\var{x} converted to floating point}{}
   \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{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}}{}
 \end{tableiii}
@@ -283,6 +283,12 @@ for well-defined conversions.
 See section \ref{built-in-funcs}, ``Built-in Functions,'' for a full
 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
 
@@ -442,6 +448,7 @@ equal to \var{x}, else \code{1}}{(1)}
   \hline
   \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}}{}
   \lineiii{min(\var{s})}{smallest item of \var{s}}{}
@@ -455,6 +462,7 @@ equal to \var{x}, else \code{1}}{(1)}
 \indexii{repetition}{operation}
 \indexii{subscript}{operation}
 \indexii{slice}{operation}
+\indexii{extended slice}{operation}
 \opindex{in}
 \opindex{not in}
 
@@ -506,6 +514,15 @@ In Python 2.3 and beyond, \var{x} may be a string of any length.
   \code{len(\var{s})}, use \code{len(\var{s})}.  If \var{i} is omitted,
   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}
 
 
@@ -550,8 +567,8 @@ error handling scheme.  The default for \var{errors} is
 \end{methoddesc}
 
 \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
+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}
 
@@ -683,8 +700,8 @@ boundaries.  Line breaks are not included in the resulting list unless
 
 \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
+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.
 \end{methoddesc}
@@ -911,31 +928,36 @@ The following operations are defined on mutable sequence types (where
   	{slice of \var{s} from \var{i} to \var{j} is replaced by \var{t}}{}
   \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}]}}{(1)}
+	{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}}}{(2)}
+        {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}}}{(3)}
+    {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}}{(4)}
+	  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}}}{(5)}
+    {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})]}}{(3)}
+	{same as \code{del \var{s}[\var{s}.index(\var{x})]}}{(4)}
   \lineiii{\var{s}.reverse()}
-	{reverses the items of \var{s} in place}{(6)}
+	{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}{(6), (7), (8), (9)}
+	{sort the items of \var{s} in place}{(7), (8), (9), (10)}
 \end{tableiii}
 \indexiv{operations on}{mutable}{sequence}{types}
 \indexiii{operations on}{sequence}{types}
 \indexiii{operations on}{list}{type}
 \indexii{subscript}{assignment}
 \indexii{slice}{assignment}
+\indexii{extended slice}{assignment}
 \stindex{del}
 \withsubitem{(list method)}{
   \ttindex{append()}\ttindex{extend()}\ttindex{count()}\ttindex{index()}
@@ -944,30 +966,35 @@ The following operations are defined on mutable sequence types (where
 \noindent
 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[(1)] \var{t} must have the same length as the slice it is 
+  replacing.
 
-\item[(2)] Raises an exception when \var{x} is not an iterable object.
+\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 \exception{ValueError} when \var{x} is not found in
+\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[(4)] When a negative index is passed as the first parameter to
+\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[(5)] The \method{pop()} method is only supported by the list and
+\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[(6)] The \method{sort()} and \method{reverse()} methods modify the
+\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[(7)] The \method{sort()} method takes an optional argument
+\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
   the first argument is considered smaller than, equal to, or larger
@@ -979,7 +1006,7 @@ Notes:
   comparison function is semantically equivalent to calling
   \method{sort()} with no comparison function.
 
-\item[(8)] Whether the \method{sort()} method is stable is not defined by
+\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
   implementation of Python, sorts were stable only by accident through
@@ -987,7 +1014,7 @@ Notes:
   \method{sort()} method, but code that intends to be portable across
   implementations and versions must not rely on stability.
 
-\item[(9)] While a list is being sorted, the effect of attempting to
+\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
   \exception{ValueError} if it can detect that the list has been
@@ -1030,7 +1057,13 @@ arbitrary objects):
   \ttindex{keys()}
   \ttindex{update()}
   \ttindex{values()}
-  \ttindex{get()}}
+  \ttindex{get()}
+  \ttindex{setdefault()}
+  \ttindex{pop()}
+  \ttindex{popitem()}
+  \ttindex{iteritems()}
+  \ttindex{iterkeys)}
+  \ttindex{itervalues()}}
 
 \begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
   \lineiii{len(\var{a})}{the number of items in \var{a}}{}
@@ -1322,6 +1355,18 @@ 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}
+
 \begin{memberdesc}[file]{softspace}
 Boolean that indicates whether a space character needs to be printed
 before another value when using the \keyword{print} statement.