diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/api/concrete.tex | 26 | ||||
| -rw-r--r-- | Doc/lib/libstdtypes.tex | 49 | ||||
| -rw-r--r-- | Doc/ref/ref3.tex | 7 | ||||
| -rw-r--r-- | Doc/whatsnew/whatsnew23.tex | 9 |
4 files changed, 76 insertions, 15 deletions
diff --git a/Doc/api/concrete.tex b/Doc/api/concrete.tex index 8316b2d..2face20 100644 --- a/Doc/api/concrete.tex +++ b/Doc/api/concrete.tex @@ -2288,6 +2288,32 @@ They are found in the dictionary of type objects. \begin{cfuncdesc}{int}{PySlice_GetIndices}{PySliceObject *slice, int length, int *start, int *stop, int *step} +Retrieve the start, stop and step indices from the slice object +\var{slice}, assuming a sequence of length \var{length}. Treats +indices greater than \var{length} as errors. + +Returns 0 on success and -1 on error with no exception set (unless one +of the indices was not \constant{None} and failed to be converted to +an integer, in which case -1 is returned with an exception set). + +You probably do not want to use this function. If you want to use +slice objects in versions of Python prior to 2.3, you would probably +do well to incorporate the source of \cfunction{PySlice_GetIndicesEx}, +suitably renamed, in the source of your extension. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PySlice_GetIndicesEx}{PySliceObject *slice, int length, + int *start, int *stop, int *step, + int *slicelength} +Usable replacement for \cfunction{PySlice_GetIndices}. Retrieve the +start, stop, and step indices from the slice object \var{slice} +assuming a sequence of length \var{length}, and store the length of +the slice in \var{slicelength}. Out of bounds indices are clipped in +a manner consistent with the handling of normal slices. + +Returns 0 on success and -1 on error with exception set. + +\versionadded{2.3} \end{cfuncdesc} diff --git a/Doc/lib/libstdtypes.tex b/Doc/lib/libstdtypes.tex index 55e77a7..f7db943 100644 --- a/Doc/lib/libstdtypes.tex +++ b/Doc/lib/libstdtypes.tex @@ -433,6 +433,7 @@ equal to \var{x}, else \code{1}}{} \hline \lineiii{\var{s}[\var{i}]}{\var{i}'th item of \var{s}, origin 0}{(2)} \lineiii{\var{s}[\var{i}:\var{j}]}{slice of \var{s} from \var{i} to \var{j}}{(2), (3)} + \lineiii{\var{s}[\var{i}:\var{j}:\var{k}]}{slice of \var{s} from \var{i} to \var{j} with step \var{k}}{(2), (4)} \hline \lineiii{len(\var{s})}{length of \var{s}}{} \lineiii{min(\var{s})}{smallest item of \var{s}}{} @@ -446,6 +447,7 @@ equal to \var{x}, else \code{1}}{} \indexii{repetition}{operation} \indexii{subscript}{operation} \indexii{slice}{operation} +\indexii{extended slice}{operation} \opindex{in} \opindex{not in} @@ -492,6 +494,15 @@ Notes: \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[(4)] 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 \var{n} \code{>=} \code{0} and + \code{\var{i} <= \var{x} < \var{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} @@ -875,31 +886,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}})} - {sort the items of \var{s} in place}{(6), (7)} + {sort the items of \var{s} in place}{(7), (8)} \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()} @@ -908,32 +924,35 @@ The following operations are defined on mutable sequence types (where \noindent Notes: \begin{description} -\item[(1)] The C implementation of Python has historically accepted +\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[(2)] Raises an exception when \var{x} is not a list object. The +\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[(3)] Raises \exception{ValueError} when \var{x} is not found in +\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 diff --git a/Doc/ref/ref3.tex b/Doc/ref/ref3.tex index 2eb5739..c319fb8 100644 --- a/Doc/ref/ref3.tex +++ b/Doc/ref/ref3.tex @@ -252,6 +252,13 @@ sequence of the same type. This implies that the index set is renumbered so that it starts at 0. \index{slicing} +Some sequences also support ``extended slicing'' with a third ``step'' +parameter: \code{\var{a}[\var{i}:\var{j}:\var{k}]} selects all items +of \var{a} with index \var{x} where \code{\var{x} = \var{i} + +\var{n}*\var{k}}, \var{n} \code{>=} \code{0} and \var{i} \code{<=} +\var{x} \code{<} \var{j}. +\index{extended slicing} + Sequences are distinguished according to their mutability: \begin{description} diff --git a/Doc/whatsnew/whatsnew23.tex b/Doc/whatsnew/whatsnew23.tex index 2a34faf..0759c9d 100644 --- a/Doc/whatsnew/whatsnew23.tex +++ b/Doc/whatsnew/whatsnew23.tex @@ -336,6 +336,15 @@ strings \samp{True} and \samp{False} instead of \samp{1} and \samp{0}. \end{seealso} +\section{Extended Slices\label{extended-slices}} + +Ever since Python 1.4 the slice syntax has supported a third +``stride'' argument, but the builtin sequence types have not supported +this feature (it was initially included at the behest of the +developers of the Numerical Python package). This changes with Python +2.3. + +% XXX examples, etc. %====================================================================== %\section{Other Language Changes} |