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

Sat Feb 7 16:13:02 EST 2004

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'])