[Python-checkins] python/dist/src/Doc/lib libfuncs.tex, 1.143.8.8, 1.143.8.9

Sun Dec 7 06:03:11 EST 2003

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv14229
Modified Files:
 Tag: release23-maint
	libfuncs.tex 
Log Message:
Backports:
* Put str() in alphabetical order
* Move apply(), buffer(), coerce(), and intern() to a separate section.
Index: libfuncs.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libfuncs.tex,v
retrieving revision 1.143.8.8
retrieving revision 1.143.8.9
diff -C2 -d -r1.143.8.8 -r1.143.8.9
*** libfuncs.tex	5 Dec 2003 18:55:46 -0000	1.143.8.8
--- libfuncs.tex	7 Dec 2003 11:03:08 -0000	1.143.8.9
***************
*** 61,84 ****
 \end{funcdesc}
 
- \begin{funcdesc}{apply}{function, args\optional{, keywords}}
- The \var{function} argument must be a callable object (a
- user-defined or built-in function or method, or a class object) and
- the \var{args} argument must be a sequence. The \var{function} is
- called with \var{args} as the argument list; the number of arguments
- is the length of the tuple.
- If the optional \var{keywords} argument is present, it must be a
- dictionary whose keys are strings. It specifies keyword arguments
- to be added to the end of the argument list.
- Calling \function{apply()} is different from just calling
- \code{\var{function}(\var{args})}, since in that case there is always
- exactly one argument. The use of \function{apply()} is equivalent
- to \code{\var{function}(*\var{args}, **\var{keywords})}.
- Use of \function{apply()} is not necessary since the ``extended call
- syntax,'' as used in the last example, is completely equivalent.
- 
- \deprecated{2.3}{Use the extended call syntax instead, as described
- above.}
- \end{funcdesc}
- 
 \begin{funcdesc}{basestring}{}
 This abstract type is the superclass for \class{str} and \class{unicode}.
--- 61,64 ----
***************
*** 104,117 ****
 \end{funcdesc}
 
- \begin{funcdesc}{buffer}{object\optional{, offset\optional{, size}}}
- The \var{object} argument must be an object that supports the buffer
- call interface (such as strings, arrays, and buffers). A new buffer
- object will be created which references the \var{object} argument.
- The buffer object will be a slice from the beginning of \var{object}
- (or from the specified \var{offset}). The slice will extend to the
- end of \var{object} (or will have a length given by the \var{size}
- argument).
- \end{funcdesc}
- 
 \begin{funcdesc}{callable}{object}
 Return true if the \var{object} argument appears callable, false if
--- 84,87 ----
***************
*** 162,171 ****
 \end{funcdesc}
 
- \begin{funcdesc}{coerce}{x, y}
- Return a tuple consisting of the two numeric arguments converted to
- a common type, using the same rules as used by arithmetic
- operations.
- \end{funcdesc}
- 
 \begin{funcdesc}{compile}{string, filename, kind\optional{,
 flags\optional{, dont_inherit}}}
--- 132,135 ----
***************
*** 571,589 ****
 \end{funcdesc}
 
- \begin{funcdesc}{intern}{string}
- Enter \var{string} in the table of ``interned'' strings and return
- the interned string -- which is \var{string} itself or a copy.
- Interning strings is useful to gain a little performance on
- dictionary lookup -- if the keys in a dictionary are interned, and
- the lookup key is interned, the key comparisons (after hashing) can
- be done by a pointer compare instead of a string compare. Normally,
- the names used in Python programs are automatically interned, and
- the dictionaries used to hold module, class or instance attributes
- have interned keys. \versionchanged[Interned strings are not
- immortal (like they used to be in Python 2.2 and before);
- you must keep a reference to the return value of \function{intern()}
- around to benefit from it]{2.3}
- \end{funcdesc}
- 
 \begin{funcdesc}{isinstance}{object, classinfo}
 Return true if the \var{object} argument is an instance of the
--- 535,538 ----
***************
*** 933,936 ****
--- 882,895 ----
 \end{funcdesc}
 
+ \begin{funcdesc}{str}{\optional{object}}
+ Return a string containing a nicely printable representation of an
+ object. For strings, this returns the string itself. The
+ difference with \code{repr(\var{object})} is that
+ \code{str(\var{object})} does not always attempt to return a string
+ that is acceptable to \function{eval()}; its goal is to return a
+ printable string. If no argument is given, returns the empty
+ string, \code{''}.
+ \end{funcdesc}
+ 
 \begin{funcdesc}{sum}{sequence\optional{, start}}
 Sums \var{start} and the items of a \var{sequence}, from left to
***************
*** 961,974 ****
 \end{funcdesc}
 
- \begin{funcdesc}{str}{\optional{object}}
- Return a string containing a nicely printable representation of an
- object. For strings, this returns the string itself. The
- difference with \code{repr(\var{object})} is that
- \code{str(\var{object})} does not always attempt to return a string
- that is acceptable to \function{eval()}; its goal is to return a
- printable string. If no argument is given, returns the empty
- string, \code{''}.
- \end{funcdesc}
- 
 \begin{funcdesc}{tuple}{\optional{sequence}}
 Return a tuple whose items are the same and in the same order as
--- 920,923 ----
***************
*** 1084,1086 ****
--- 1033,1103 ----
 With a single sequence argument, it returns a list of 1-tuples.
 \versionadded{2.0}
+ \end{funcdesc}
+ 
+ 
+ % ---------------------------------------------------------------------------	
+ 
+ 
+ \section{Non-essential Built-in Functions \label{non-essential-built-in-funcs}}
+ 
+ There are several built-in functions that are no longer essential to learn,
+ know or use in modern Python programming. They have been kept here to
+ maintain backwards compatability with programs written for older versions
+ of Python.
+ 
+ Python programmers, trainers, students and bookwriters should feel free to
+ bypass these functions without concerns about missing something important.
+ 
+ 
+ \setindexsubitem{(non-essential built-in functions)}
+ 
+ \begin{funcdesc}{apply}{function, args\optional{, keywords}}
+ The \var{function} argument must be a callable object (a
+ user-defined or built-in function or method, or a class object) and
+ the \var{args} argument must be a sequence. The \var{function} is
+ called with \var{args} as the argument list; the number of arguments
+ is the length of the tuple.
+ If the optional \var{keywords} argument is present, it must be a
+ dictionary whose keys are strings. It specifies keyword arguments
+ to be added to the end of the argument list.
+ Calling \function{apply()} is different from just calling
+ \code{\var{function}(\var{args})}, since in that case there is always
+ exactly one argument. The use of \function{apply()} is equivalent
+ to \code{\var{function}(*\var{args}, **\var{keywords})}.
+ Use of \function{apply()} is not necessary since the ``extended call
+ syntax,'' as used in the last example, is completely equivalent.
+ 
+ \deprecated{2.3}{Use the extended call syntax instead, as described
+ above.}
+ \end{funcdesc}
+ 
+ \begin{funcdesc}{buffer}{object\optional{, offset\optional{, size}}}
+ The \var{object} argument must be an object that supports the buffer
+ call interface (such as strings, arrays, and buffers). A new buffer
+ object will be created which references the \var{object} argument.
+ The buffer object will be a slice from the beginning of \var{object}
+ (or from the specified \var{offset}). The slice will extend to the
+ end of \var{object} (or will have a length given by the \var{size}
+ argument).
+ \end{funcdesc}
+ 
+ \begin{funcdesc}{coerce}{x, y}
+ Return a tuple consisting of the two numeric arguments converted to
+ a common type, using the same rules as used by arithmetic
+ operations.
+ \end{funcdesc}
+ 
+ \begin{funcdesc}{intern}{string}
+ Enter \var{string} in the table of ``interned'' strings and return
+ the interned string -- which is \var{string} itself or a copy.
+ Interning strings is useful to gain a little performance on
+ dictionary lookup -- if the keys in a dictionary are interned, and
+ the lookup key is interned, the key comparisons (after hashing) can
+ be done by a pointer compare instead of a string compare. Normally,
+ the names used in Python programs are automatically interned, and
+ the dictionaries used to hold module, class or instance attributes
+ have interned keys. \versionchanged[Interned strings are not
+ immortal (like they used to be in Python 2.2 and before);
+ you must keep a reference to the return value of \function{intern()}
+ around to benefit from it]{2.3}
 \end{funcdesc}