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

Fri, 7 Jul 2000 08:47:09 -0700

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}