[Python-checkins] python/dist/src/Doc/api concrete.tex,1.6.6.5,1.6.6.6

[fdrake@users.sourceforge.net]

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

Modified Files:
      Tag: release22-maint
	concrete.tex 
Log Message:
Clarified the error cases and Unicode handling of PyString_AsString(),
PyString_AsStringAndSize(), and PyString_AS_STRING().
Closes SF bug #606463.


Index: concrete.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/api/concrete.tex,v
retrieving revision 1.6.6.5
retrieving revision 1.6.6.6
diff -C2 -d -r1.6.6.5 -r1.6.6.6
*** concrete.tex	20 Jun 2002 22:09:12 -0000	1.6.6.5
--- concrete.tex	22 Oct 2002 20:21:06 -0000	1.6.6.6
***************
*** 530,544 ****
  
  \begin{cfuncdesc}{char*}{PyString_AsString}{PyObject *string}
!   Returns a null-terminated representation of the contents of
    \var{string}.  The pointer refers to the internal buffer of
    \var{string}, not a copy.  The data must not be modified in any way,
    unless the string was just created using
    \code{PyString_FromStringAndSize(NULL, \var{size})}.
!   It must not be deallocated.
  \end{cfuncdesc}
  
  \begin{cfuncdesc}{char*}{PyString_AS_STRING}{PyObject *string}
    Macro form of \cfunction{PyString_AsString()} but without error
!   checking.
  \end{cfuncdesc}
  
--- 530,549 ----
  
  \begin{cfuncdesc}{char*}{PyString_AsString}{PyObject *string}
!   Returns a NUL-terminated representation of the contents of
    \var{string}.  The pointer refers to the internal buffer of
    \var{string}, not a copy.  The data must not be modified in any way,
    unless the string was just created using
    \code{PyString_FromStringAndSize(NULL, \var{size})}.
!   It must not be deallocated.  If \var{string} is a Unicode object,
!   this function computes the default encoding of \var{string} and
!   operates on that.  If \var{string} is not a string object at all,
!   \cfunction{PyString_AsString()} returns \NULL{} and raises
!   \exception{TypeError}.
  \end{cfuncdesc}
  
  \begin{cfuncdesc}{char*}{PyString_AS_STRING}{PyObject *string}
    Macro form of \cfunction{PyString_AsString()} but without error
!   checking.  Only string objects are supported; no Unicode objects
!   should be passed.
  \end{cfuncdesc}
  
***************
*** 546,550 ****
                                                   char **buffer,
                                                   int *length}
!   Returns a null-terminated representation of the contents of the
    object \var{obj} through the output variables \var{buffer} and
    \var{length}.
--- 551,555 ----
                                                   char **buffer,
                                                   int *length}
!   Returns a NUL-terminated representation of the contents of the
    object \var{obj} through the output variables \var{buffer} and
    \var{length}.
***************
*** 552,563 ****
    The function accepts both string and Unicode objects as input. For
    Unicode objects it returns the default encoded version of the
!   object.  If \var{length} is set to \NULL, the resulting buffer may
!   not contain null characters; if it does, the function returns -1 and
!   a \exception{TypeError} is raised.
  
    The buffer refers to an internal string buffer of \var{obj}, not a
    copy. The data must not be modified in any way, unless the string
    was just created using \code{PyString_FromStringAndSize(NULL,
!   \var{size})}.  It must not be deallocated.
  \end{cfuncdesc}
  
--- 557,572 ----
    The function accepts both string and Unicode objects as input. For
    Unicode objects it returns the default encoded version of the
!   object.  If \var{length} is \NULL, the resulting buffer may not
!   contain NUL characters; if it does, the function returns \code{-1}
!   and a \exception{TypeError} is raised.
  
    The buffer refers to an internal string buffer of \var{obj}, not a
    copy. The data must not be modified in any way, unless the string
    was just created using \code{PyString_FromStringAndSize(NULL,
!   \var{size})}.  It must not be deallocated.  If \var{string} is a
!   Unicode object, this function computes the default encoding of
!   \var{string} and operates on that.  If \var{string} is not a string
!   object at all, \cfunction{PyString_AsString()} returns \NULL{} and
!   raises \exception{TypeError}.
  \end{cfuncdesc}