[Python-checkins] CVS: python/dist/src/Doc/api api.tex,1.72,1.73

[M.-A. Lemburg]

Update of /cvsroot/python/python/dist/src/Doc/api
In directory slayer.i.sourceforge.net:/tmp/cvs-serv5372/Doc/api

Modified Files:
	api.tex 
Log Message:
Added docs for the new Unicode and string APIs.

Index: api.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/api/api.tex,v
retrieving revision 1.72
retrieving revision 1.73
diff -C2 -r1.72 -r1.73
*** api.tex	2000/07/03 13:38:10	1.72
--- api.tex	2000/07/07 15:47:06	1.73
***************
*** 1924,1927 ****
--- 1924,1961 ----
  \end{cfuncdesc}
  
+ \begin{cfuncdesc}{PyObject*}{PyString_Decode}{const char *s,
+                                                int size,
+                                                const char *encoding,
+                                                const char *errors}
+ Create a string object by decoding \var{size} bytes of the encoded
+ buffer \var{s}. \var{encoding} and \var{errors} have the same meaning
+ as the parameters of the same name in the unicode() builtin
+ function. The codec to be used is looked up using the Python codec
+ registry. Returns \NULL{} in case an exception was raised by the
+ codec.
+ \end{cfuncdesc}
+ 
+ \begin{cfuncdesc}{PyObject*}{PyString_Encode}{const Py_UNICODE *s,
+                                                int size,
+                                                const char *encoding,
+                                                const char *errors}
+ Encodes the \ctype{Py_UNICODE} buffer of the given size and returns a
+ Python string object. \var{encoding} and \var{errors} have the same
+ meaning as the parameters of the same name in the string .encode()
+ method. The codec to be used is looked up using the Python codec
+ registry. Returns \NULL{} in case an exception was raised by the
+ codec.
+ \end{cfuncdesc}
+ 
+ \begin{cfuncdesc}{PyObject*}{PyString_AsEncodedString}{PyObject *unicode,
+                                                const char *encoding,
+                                                const char *errors}
+ Encodes a string object and returns the result as Python string
+ object. \var{encoding} and \var{errors} have the same meaning as the
+ parameters of the same name in the string .encode() method. The codec
+ to be used is looked up using the Python codec registry. Returns
+ \NULL{} in case an exception was raised by the codec.
+ \end{cfuncdesc}
+ 
  
  \subsection{Unicode Objects \label{unicodeObjects}}
***************
*** 2077,2098 ****
  \end{cfuncdesc}
  
! \begin{cfuncdesc}{PyObject*}{PyUnicode_FromObject}{PyObject *obj}
  
! Coerce obj to an Unicode object and return a reference with
! incremented refcount.
  
  Coercion is done in the following way:
  \begin{enumerate}
  \item  Unicode objects are passed back as-is with incremented
!       refcount.
  
  \item String and other char buffer compatible objects are decoded
!       under the assumptions that they contain UTF-8 data. Decoding
!       is done in "strict" mode.
  
! \item All other objects raise an exception.
  \end{enumerate}
  The API returns NULL in case of an error. The caller is responsible
  for decref'ing the returned objects.
  \end{cfuncdesc}
  
--- 2111,2143 ----
  \end{cfuncdesc}
  
! \begin{cfuncdesc}{PyObject*}{PyUnicode_FromEncodedObject}{PyObject *obj,
!                                                       const char *encoding,
!                                                       const char *errors}
  
! Coerce an encoded object obj to an Unicode object and return a
! reference with incremented refcount.
  
  Coercion is done in the following way:
  \begin{enumerate}
  \item  Unicode objects are passed back as-is with incremented
!       refcount. Note: these cannot be decoded; passing a non-NULL
!       value for encoding will result in a TypeError.
  
  \item String and other char buffer compatible objects are decoded
!       according to the given encoding and using the error handling
!       defined by errors. Both can be NULL to have the interface use
!       the default values (see the next section for details).
  
! \item All other objects cause an exception.
  \end{enumerate}
  The API returns NULL in case of an error. The caller is responsible
  for decref'ing the returned objects.
+ \end{cfuncdesc}
+ 
+ \begin{cfuncdesc}{PyObject*}{PyUnicode_FromObject}{PyObject *obj}
+ 
+ Shortcut for PyUnicode_FromEncodedObject(obj, NULL, ``strict'')
+ which is used throughout the interpreter whenever coercion to
+ Unicode is needed.
  \end{cfuncdesc}