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

[rhettinger at users.sourceforge.net]

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

Modified Files:
	libcollections.tex 
Log Message:
Improvements to collections.deque():

* Add doctests for the examples in the library reference.
* Add two methods, left() and right(), modeled after deques in C++ STL.
* Apply the new method to asynchat.py.
* Add comparison operators to make deques more substitutable for lists.
* Replace the LookupErrors with IndexErrors to more closely match lists.



Index: libcollections.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libcollections.tex,v
retrieving revision 1.4
retrieving revision 1.5
diff -C2 -d -r1.4 -r1.5
*** libcollections.tex	7 Feb 2004 21:12:59 -0000	1.4
--- libcollections.tex	29 Feb 2004 02:15:55 -0000	1.5
***************
*** 55,66 ****
  \end{methoddesc}
  
  \begin{methoddesc}{pop}{}
     Remove and return an element from the right side of the deque.
!    If no elements are present, raises a \exception{LookupError}.
  \end{methoddesc}
  
  \begin{methoddesc}{popleft}{}
     Remove and return an element from the left side of the deque.
!    If no elements are present, raises a \exception{LookupError}.   
  \end{methoddesc}
  
--- 55,76 ----
  \end{methoddesc}
  
+ \begin{methoddesc}{left}{}
+    Return leftmost element from the deque.
+    If no elements are present, raises a \exception{IndexError}.   
+ \end{methoddesc}
+ 
  \begin{methoddesc}{pop}{}
     Remove and return an element from the right side of the deque.
!    If no elements are present, raises a \exception{IndexError}.
  \end{methoddesc}
  
  \begin{methoddesc}{popleft}{}
     Remove and return an element from the left side of the deque.
!    If no elements are present, raises a \exception{IndexError}.   
! \end{methoddesc}
! 
! \begin{methoddesc}{right}{}
!    Return the rightmost element from the deque.
!    If no elements are present, raises a \exception{IndexError}.   
  \end{methoddesc}
  
***************
*** 81,94 ****
  >>> d = deque('ghi')                 # make a new deque with three items
  >>> for elem in d:                   # iterate over the deque's elements
! 	print elem.upper()
! 
! 	
  G
  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'
--- 91,104 ----
  >>> d = deque('ghi')                 # make a new deque with three items
  >>> for elem in d:                   # iterate over the deque's elements
! ...     print elem.upper()	
  G
  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'
***************
*** 97,100 ****
--- 107,115 ----
  >>> list(d)                          # list the contents of the deque
  ['g', 'h', 'i']
+ 
+ >>> d.left()                         # peek at leftmost item
+ 'g'
+ >>> d.right()                        # peek at rightmost item
+ 'i'
  >>> list(reversed(d))                # list the contents of a deque in reverse
  ['i', 'h', 'g']
***************
*** 110,122 ****
  >>> 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):
    File "<pyshell#6>", line 1, in -toplevel-
      d.pop()
! LookupError: pop from an empty deque
  
  >>> d.extendleft('abc')              # extendleft() reverses the input order
--- 125,137 ----
  >>> 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):
    File "<pyshell#6>", line 1, in -toplevel-
      d.pop()
! IndexError: pop from an empty deque
  
  >>> d.extendleft('abc')              # extendleft() reverses the input order