[Python-checkins] python/dist/src/Doc/lib libcollections.tex, 1.3, 1.4

[rhettinger at users.sourceforge.net]

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv8513/Doc/lib

Modified Files:
	libcollections.tex 
Log Message:
* Incorporate Skip's suggestions for documentation  (explain the word deque
  comes from and show the differences from lists).
* Add a rotate() method.



Index: libcollections.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libcollections.tex,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** libcollections.tex	7 Feb 2004 02:45:21 -0000	1.3
--- libcollections.tex	7 Feb 2004 21:12:59 -0000	1.4
***************
*** 1,4 ****
  \section{\module{collections} ---
!          High-performance datatypes}
  
  \declaremodule{standard}{collections}
--- 1,4 ----
  \section{\module{collections} ---
!          High-performance container datatypes}
  
  \declaremodule{standard}{collections}
***************
*** 9,13 ****
  
  
! This module implements high-performance datatypes.  Currently, the
  only datatype is a deque.  Future additions may include B-trees
  and Fibonacci heaps.
--- 9,13 ----
  
  
! This module implements high-performance container datatypes.  Currently, the
  only datatype is a deque.  Future additions may include B-trees
  and Fibonacci heaps.
***************
*** 18,24 ****
    is not specified, the new deque is empty.
  
!   Deques are a generalization of stacks and queues.  They support
!   thread-safe, memory efficient appends and pops from either side of the
!   deque with approximately the same performance in either direction.
    \versionadded{2.4}
  \end{funcdesc}
--- 18,30 ----
    is not specified, the new deque is empty.
  
!   Deques are a generalization of stacks and queues (the name is pronounced
!   ``deck'' and is short for ``double-ended queue'').  Deques support
!   thread-safe, memory efficient appends and pops from either side of the deque
!   with approximately the same \code{O(1)} performance in either direction.
! 
!   Though \class{list} objects support similar operations, they are optimized
!   for fast fixed-length operations and incur \code{O(n)} memory movement costs
!   for \samp{pop(0)} and \samp{insert(0, v)} operations which change both the
!   size and position of the underlying data representation.
    \versionadded{2.4}
  \end{funcdesc}
***************
*** 59,65 ****
  \end{methoddesc}
  
! In addition to the above, deques support iteration, membership testing
! using the \keyword{in} operator, \samp{len(d)}, \samp{copy.copy(d)},
! \samp{copy.deepcopy(d)}, \samp{reversed(d)} and pickling.
  
  Example:
--- 65,77 ----
  \end{methoddesc}
  
! \begin{methoddesc}{rotate}{n}
!    Rotate the deque \var{n} steps to the right.  If \var{n} is
!    negative, rotate to the left.  Rotating one step to the right
!    is equivalent to:  \samp{d.appendleft(d.pop())}.
! \end{methoddesc}
! 
! In addition to the above, deques support iteration, pickling, \samp{len(d)},
! \samp{reversed(d)}, \samp{copy.copy(d)}, \samp{copy.deepcopy(d)}, and
! membership testing with the \keyword{in} operator.
  
  Example:
***************
*** 67,72 ****
  \begin{verbatim}
  >>> from collections import deque
! >>> d = deque('ghi')        # make a new deque with three items
! >>> for elem in d:          # iterate over the deque's elements
  	print elem.upper()
  
--- 79,84 ----
  \begin{verbatim}
  >>> from collections import deque
! >>> d = deque('ghi')                 # make a new deque with three items
! >>> for elem in d:                   # iterate over the deque's elements
  	print elem.upper()
  
***************
*** 75,97 ****
  H
  I
! >>> d.append('j')           # add a new entry to the right side
! >>> d.appendleft('f')       # add a new entry to the left side
! >>> d                       # show the representation of the deque
  deque(['f', 'g', 'h', 'i', 'j'])
! >>> d.pop()                 # return and remove the rightmost item
  'j'
! >>> d.popleft()             # return and remove the leftmost item
  'f'
! >>> list(d)                 # list the contents of the deque
  ['g', 'h', 'i']
! >>> list(reversed(d))       # list the contents of a deque in reverse
  ['i', 'h', 'g']
! >>> 'h' in d                # search the deque
  True
! >>> d.extend('jkl')         # extend() will append many elements at once
  >>> d
  deque(['g', 'h', 'i', 'j', 'k', 'l'])
! >>> d.clear()               # empty the deque
! >>> d.pop()                 # cannot pop from an empty deque
  
  Traceback (most recent call last):
--- 87,117 ----
  H
  I
! >>> d.append('j')                    # add a new entry to the right side
! >>> d.appendleft('f')                # add a new entry to the left side
! >>> d                                # show the representation of the deque
  deque(['f', 'g', 'h', 'i', 'j'])
! >>> d.pop()                          # return and remove the rightmost item
  'j'
! >>> d.popleft()                      # return and remove the leftmost item
  'f'
! >>> list(d)                          # list the contents of the deque
  ['g', 'h', 'i']
! >>> list(reversed(d))                # list the contents of a deque in reverse
  ['i', 'h', 'g']
! >>> 'h' in d                         # search the deque
  True
! >>> d.extend('jkl')                  # add multiple elements at once
  >>> d
  deque(['g', 'h', 'i', 'j', 'k', 'l'])
! >>> d.rotate(1)                      # right rotation
! >>> d
! deque(['l', 'g', 'h', 'i', 'j', 'k'])
! >>> d.rotate(-1)                     # left rotation
! >>> d
! deque(['g', 'h', 'i', 'j', 'k', 'l'])
! >>> deque(reversed(d))               # make a new deque in reverse order
! deque(['l', 'k', 'j', 'i', 'h', 'g'])
! >>> d.clear()                        # empty the deque
! >>> d.pop()                          # cannot pop from an empty deque
  
  Traceback (most recent call last):
***************
*** 100,104 ****
  LookupError: pop from an empty deque
  
! >>> d.extendleft('abc')     # extendleft() reverses the element order
  >>> d
  deque(['c', 'b', 'a'])
--- 120,124 ----
  LookupError: pop from an empty deque
  
! >>> d.extendleft('abc')              # extendleft() reverses the input order
  >>> d
  deque(['c', 'b', 'a'])