[Python-checkins] CVS: python/dist/src/Doc/lib libfuncs.tex,1.84,1.85

[Tim Peters]

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

Modified Files:
	libfuncs.tex 
Log Message:
Document new file() constructor, with the body of open()'s text, plus a
"new in 2.2" blurb at the end.  Replace open()'s text by pointing back
to file().


Index: libfuncs.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libfuncs.tex,v
retrieving revision 1.84
retrieving revision 1.85
diff -C2 -d -r1.84 -r1.85
*** libfuncs.tex	2001/09/06 19:04:29	1.84
--- libfuncs.tex	2001/09/20 19:55:29	1.85
***************
*** 253,256 ****
--- 253,299 ----
  \end{funcdesc}
  
+ \begin{funcdesc}{file}{filename\optional{, mode\optional{, bufsize}}}
+   Return a new file object (described earlier under Built-in Types).
+   The first two arguments are the same as for \code{stdio}'s
+   \cfunction{fopen()}: \var{filename} is the file name to be opened,
+   \var{mode} indicates how the file is to be opened: \code{'r'} for
+   reading, \code{'w'} for writing (truncating an existing file), and
+   \code{'a'} opens it for appending (which on \emph{some} \UNIX{}
+   systems means that \emph{all} writes append to the end of the file,
+   regardless of the current seek position).
+ 
+   Modes \code{'r+'}, \code{'w+'} and \code{'a+'} open the file for
+   updating (note that \code{'w+'} truncates the file).  Append
+   \code{'b'} to the mode to open the file in binary mode, on systems
+   that differentiate between binary and text files (else it is
+   ignored).  If the file cannot be opened, \exception{IOError} is
+   raised.
+ 
+   If \var{mode} is omitted, it defaults to \code{'r'}.  When opening a
+   binary file, you should append \code{'b'} to the \var{mode} value
+   for improved portability.  (It's useful even on systems which don't
+   treat binary and text files differently, where it serves as
+   documentation.)
+   \index{line-buffered I/O}\index{unbuffered I/O}\index{buffer size, I/O}
+   \index{I/O control!buffering}
+   The optional \var{bufsize} argument specifies the
+   file's desired buffer size: 0 means unbuffered, 1 means line
+   buffered, any other positive value means use a buffer of
+   (approximately) that size.  A negative \var{bufsize} means to use
+   the system default, which is usually line buffered for for tty
+   devices and fully buffered for other files.  If omitted, the system
+   default is used.\footnote{
+     Specifying a buffer size currently has no effect on systems that
+     don't have \cfunction{setvbuf()}.  The interface to specify the
+     buffer size is not done using a method that calls
+     \cfunction{setvbuf()}, because that may dump core when called
+     after any I/O has been performed, and there's no reliable way to
+     determine whether this is the case.}
+ 
+   The \function{file()} constructor is new in Python 2.2.  The previous
+   spelling, \function{open()}, is retained for compatibility, and is an
+   alias for \function{file()}.
+ \end{funcdesc}
+ 
  \begin{funcdesc}{filter}{function, list}
    Construct a list from those elements of \var{list} for which
***************
*** 480,519 ****
  
  \begin{funcdesc}{open}{filename\optional{, mode\optional{, bufsize}}}
!   Return a new file object (described earlier under Built-in Types).
!   The first two arguments are the same as for \code{stdio}'s
!   \cfunction{fopen()}: \var{filename} is the file name to be opened,
!   \var{mode} indicates how the file is to be opened: \code{'r'} for
!   reading, \code{'w'} for writing (truncating an existing file), and
!   \code{'a'} opens it for appending (which on \emph{some} \UNIX{}
!   systems means that \emph{all} writes append to the end of the file,
!   regardless of the current seek position).
! 
!   Modes \code{'r+'}, \code{'w+'} and \code{'a+'} open the file for
!   updating (note that \code{'w+'} truncates the file).  Append
!   \code{'b'} to the mode to open the file in binary mode, on systems
!   that differentiate between binary and text files (else it is
!   ignored).  If the file cannot be opened, \exception{IOError} is
!   raised.
! 
!   If \var{mode} is omitted, it defaults to \code{'r'}.  When opening a
!   binary file, you should append \code{'b'} to the \var{mode} value
!   for improved portability.  (It's useful even on systems which don't
!   treat binary and text files differently, where it serves as
!   documentation.)
!   \index{line-buffered I/O}\index{unbuffered I/O}\index{buffer size, I/O}
!   \index{I/O control!buffering}
!   The optional \var{bufsize} argument specifies the
!   file's desired buffer size: 0 means unbuffered, 1 means line
!   buffered, any other positive value means use a buffer of
!   (approximately) that size.  A negative \var{bufsize} means to use
!   the system default, which is usually line buffered for for tty
!   devices and fully buffered for other files.  If omitted, the system
!   default is used.\footnote{
!     Specifying a buffer size currently has no effect on systems that
!     don't have \cfunction{setvbuf()}.  The interface to specify the
!     buffer size is not done using a method that calls
!     \cfunction{setvbuf()}, because that may dump core when called
!     after any I/O has been performed, and there's no reliable way to
!     determine whether this is the case.}
  \end{funcdesc}
  
--- 523,527 ----
  
  \begin{funcdesc}{open}{filename\optional{, mode\optional{, bufsize}}}
!   An alias for the \function{file()} function above.
  \end{funcdesc}
  
***************
*** 539,543 ****
    Python 2.2.  In Python 2.1 and before, if both arguments were of integer
    types and the second argument was negative, an exception was raised.)
!   If the second argument is negative, the third argument must be omitted. 
    If \var{z} is present, \var{x} and \var{y} must be of integer types,
    and \var{y} must be non-negative.  (This restriction was added in
--- 547,551 ----
    Python 2.2.  In Python 2.1 and before, if both arguments were of integer
    types and the second argument was negative, an exception was raised.)
!   If the second argument is negative, the third argument must be omitted.
    If \var{z} is present, \var{x} and \var{y} must be of integer types,
    and \var{y} must be non-negative.  (This restriction was added in