[Python-checkins] CVS: python/dist/src/Doc/api abstract.tex,1.1,1.2

[Tim Peters]

Update of /cvsroot/python/python/dist/src/Doc/api
In directory usw-pr-cvs1:/tmp/cvs-serv13745/python/Doc/api

Modified Files:
	abstract.tex 
Log Message:
Generalize dictionary() to accept a sequence of 2-sequences.  At the
outer level, the iterator protocol is used for memory-efficiency (the
outer sequence may be very large if fully materialized); at the inner
level, PySequence_Fast() is used for time-efficiency (these should
always be sequences of length 2).

dictobject.c, new functions PyDict_{Merge,Update}FromSeq2.  These are
wholly analogous to PyDict_{Merge,Update}, but process a sequence-of-2-
sequences argument instead of a mapping object.  For now, I left these
functions file static, so no corresponding doc changes.  It's tempting
to change dict.update() to allow a sequence-of-2-seqs argument too.

Also changed the name of dictionary's keyword argument from "mapping"
to "x".  Got a better name?  "mapping_or_sequence_of_pairs" isn't
attractive, although more so than "mosop" <wink>.

abstract.h, abstract.tex:  Added new PySequence_Fast_GET_SIZE function,
much faster than going thru the all-purpose PySequence_Size.

libfuncs.tex:
- Document dictionary().
- Fiddle tuple() and list() to admit that their argument is optional.
- The long-winded repetitions of "a sequence, a container that supports
  iteration, or an iterator object" is getting to be a PITA.  Many
  months ago I suggested factoring this out into "iterable object",
  where the definition of that could include being explicit about
  generators too (as is, I'm not sure a reader outside of PythonLabs
  could guess that "an iterator object" includes a generator call).
- Please check my curly braces -- I'm going blind <0.9 wink>.

abstract.c, PySequence_Tuple():  When PyObject_GetIter() fails, leave
its error msg alone now (the msg it produces has improved since
PySequence_Tuple was generalized to accept iterable objects, and
PySequence_Tuple was also stomping on the msg in cases it shouldn't
have even before PyObject_GetIter grew a better msg).


Index: abstract.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/api/abstract.tex,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** abstract.tex	2001/10/12 19:01:43	1.1
--- abstract.tex	2001/10/26 05:06:49	1.2
***************
*** 126,130 ****
    This is the equivalent of the Python expression
    \samp{unistr(\var{o})}.  Called by the
!   \function{unistr()}\bifuncindex{unistr} built-in function. 
  \end{cfuncdesc}
  
--- 126,130 ----
    This is the equivalent of the Python expression
    \samp{unistr(\var{o})}.  Called by the
!   \function{unistr()}\bifuncindex{unistr} built-in function.
  \end{cfuncdesc}
  
***************
*** 716,723 ****
  \begin{cfuncdesc}{PyObject*}{PySequence_Fast_GET_ITEM}{PyObject *o, int i}
    Return the \var{i}th element of \var{o}, assuming that \var{o} was
!   returned by \cfunction{PySequence_Fast()}, and that \var{i} is
!   within bounds.  The caller is expected to get the length of the
!   sequence by calling \cfunction{PySequence_Size()} on \var{o}, since
!   lists and tuples are guaranteed to always return their true length.
  \end{cfuncdesc}
  
--- 716,730 ----
  \begin{cfuncdesc}{PyObject*}{PySequence_Fast_GET_ITEM}{PyObject *o, int i}
    Return the \var{i}th element of \var{o}, assuming that \var{o} was
!   returned by \cfunction{PySequence_Fast()}, \var{o} is not \NULL{},
!   and that \var{i} is within bounds.
! \end{cfuncdesc}
! 
! \begin{cfuncdesc}{int}{PySequence_Fast_GET_SIZE}{PyObject *o}
!   Returns the length of \var{o}, assuming that \var{o} was
!   returned by \cfunction{PySequence_Fast()} and that \var{o} is
!   not \NULL{}.  The size can also be gotten by calling
!   \cfunction{PySequence_Size()} on \var{o}, but
!   \cfunction{PySequence_Fast_GET_SIZE()} is faster because it can
!   assume \var{o} is a list or tuple.
  \end{cfuncdesc}