Commits

Fred Drake committed 2e2ef47

Move the section on concrete numeric objects before the section on
concrete sequence objects, since their API is simpler.

This is in response to a comment in SF bug #440037.

(Does this really belong in the bugfix release? Yes: this is a readability
bug, and those are important in the documentation.)

  • Participants
  • Parent commits dfb7742
  • Branches 2.1

Comments (0)

Files changed (1)

File Doc/api/api.tex

 \end{cvardesc}
 
 
-\section{Sequence Objects \label{sequenceObjects}}
-
-\obindex{sequence}
-Generic operations on sequence objects were discussed in the previous 
-chapter; this section deals with the specific kinds of sequence 
-objects that are intrinsic to the Python language.
-
-
-\subsection{String Objects \label{stringObjects}}
-
-These functions raise \exception{TypeError} when expecting a string
-parameter and are called with a non-string parameter.
-
-\obindex{string}
-\begin{ctypedesc}{PyStringObject}
-This subtype of \ctype{PyObject} represents a Python string object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyString_Type}
-This instance of \ctype{PyTypeObject} represents the Python string
-type; it is the same object as \code{types.TypeType} in the Python
-layer.\withsubitem{(in module types)}{\ttindex{StringType}}.
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyString_Check}{PyObject *o}
-Returns true if the object \var{o} is a string object.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_FromString}{const char *v}
-Returns a new string object with the value \var{v} on success, and
-\NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_FromStringAndSize}{const char *v,
-                                                         int len}
-Returns a new string object with the value \var{v} and length
-\var{len} on success, and \NULL{} on failure.  If \var{v} is \NULL{},
-the contents of the string are uninitialized.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyString_Size}{PyObject *string}
-Returns the length of the string in string object \var{string}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyObject *string}
-Macro form of \cfunction{PyString_Size()} but without error
-checking.
-\end{cfuncdesc}
-
-\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}
-
-\begin{cfuncdesc}{int}{PyString_AsStringAndSize}{PyObject *obj,
-                                                 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}.
-
-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
-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}
-
-\begin{cfuncdesc}{void}{PyString_Concat}{PyObject **string,
-                                         PyObject *newpart}
-Creates a new string object in \var{*string} containing the
-contents of \var{newpart} appended to \var{string}; the caller will
-own the new reference.  The reference to the old value of \var{string}
-will be stolen.  If the new string
-cannot be created, the old reference to \var{string} will still be
-discarded and the value of \var{*string} will be set to
-\NULL{}; the appropriate exception will be set.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **string,
-                                               PyObject *newpart}
-Creates a new string object in \var{*string} containing the contents
-of \var{newpart} appended to \var{string}.  This version decrements
-the reference count of \var{newpart}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **string, int newsize}
-A way to resize a string object even though it is ``immutable''.  
-Only use this to build up a brand new string object; don't use this if
-the string may already be known in other parts of the code.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_Format}{PyObject *format,
-                                              PyObject *args}
-Returns a new string object from \var{format} and \var{args}.  Analogous
-to \code{\var{format} \%\ \var{args}}.  The \var{args} argument must be
-a tuple.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyString_InternInPlace}{PyObject **string}
-Intern the argument \var{*string} in place.  The argument must be the
-address of a pointer variable pointing to a Python string object.
-If there is an existing interned string that is the same as
-\var{*string}, it sets \var{*string} to it (decrementing the reference 
-count of the old string object and incrementing the reference count of
-the interned string object), otherwise it leaves \var{*string} alone
-and interns it (incrementing its reference count).  (Clarification:
-even though there is a lot of talk about reference counts, think of
-this function as reference-count-neutral; you own the object after
-the call if and only if you owned it before the call.)
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_InternFromString}{const char *v}
-A combination of \cfunction{PyString_FromString()} and
-\cfunction{PyString_InternInPlace()}, returning either a new string object
-that has been interned, or a new (``owned'') reference to an earlier
-interned string object with the same value.
-\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}}
-\sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com}
-
-%--- Unicode Type -------------------------------------------------------
-
-These are the basic Unicode object types used for the Unicode
-implementation in Python:
-
-\begin{ctypedesc}{Py_UNICODE}
-This type represents a 16-bit unsigned storage type which is used by
-Python internally as basis for holding Unicode ordinals. On platforms
-where \ctype{wchar_t} is available and also has 16-bits,
-\ctype{Py_UNICODE} is a typedef alias for \ctype{wchar_t} to enhance
-native platform compatibility. On all other platforms,
-\ctype{Py_UNICODE} is a typedef alias for \ctype{unsigned short}.
-\end{ctypedesc}
-
-\begin{ctypedesc}{PyUnicodeObject}
-This subtype of \ctype{PyObject} represents a Python Unicode object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyUnicode_Type}
-This instance of \ctype{PyTypeObject} represents the Python Unicode type.
-\end{cvardesc}
-
-%--- These are really C macros... is there a macrodesc TeX macro ?
-
-The following APIs are really C macros and can be used to do fast
-checks and to access internal read-only data of Unicode objects:
-
-\begin{cfuncdesc}{int}{PyUnicode_Check}{PyObject *o}
-Returns true if the object \var{o} is a Unicode object.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyUnicode_GET_SIZE}{PyObject *o}
-Returns the size of the object.  o has to be a
-PyUnicodeObject (not checked).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyUnicode_GET_DATA_SIZE}{PyObject *o}
-Returns the size of the object's internal buffer in bytes. o has to be
-a PyUnicodeObject (not checked).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AS_UNICODE}{PyObject *o}
-Returns a pointer to the internal Py_UNICODE buffer of the object. o
-has to be a PyUnicodeObject (not checked).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{const char*}{PyUnicode_AS_DATA}{PyObject *o}
-Returns a (const char *) pointer to the internal buffer of the object.
-o has to be a PyUnicodeObject (not checked).
-\end{cfuncdesc}
-
-% --- Unicode character properties ---------------------------------------
-
-Unicode provides many different character properties. The most often
-needed ones are available through these macros which are mapped to C
-functions depending on the Python configuration.
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISSPACE}{Py_UNICODE ch}
-Returns 1/0 depending on whether \var{ch} is a whitespace character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISLOWER}{Py_UNICODE ch}
-Returns 1/0 depending on whether \var{ch} is a lowercase character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISUPPER}{Py_UNICODE ch}
-Returns 1/0 depending on whether \var{ch} is an uppercase character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISTITLE}{Py_UNICODE ch}
-Returns 1/0 depending on whether \var{ch} is a titlecase character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISLINEBREAK}{Py_UNICODE ch}
-Returns 1/0 depending on whether \var{ch} is a linebreak character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISDECIMAL}{Py_UNICODE ch}
-Returns 1/0 depending on whether \var{ch} is a decimal character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISDIGIT}{Py_UNICODE ch}
-Returns 1/0 depending on whether \var{ch} is a digit character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISNUMERIC}{Py_UNICODE ch}
-Returns 1/0 depending on whether \var{ch} is a numeric character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISALPHA}{Py_UNICODE ch}
-Returns 1/0 depending on whether \var{ch} is an alphabetic character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISALNUM}{Py_UNICODE ch}
-Returns 1/0 depending on whether \var{ch} is an alphanumeric character.
-\end{cfuncdesc}
-
-These APIs can be used for fast direct character conversions:
-
-\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOLOWER}{Py_UNICODE ch}
-Returns the character \var{ch} converted to lower case.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOUPPER}{Py_UNICODE ch}
-Returns the character \var{ch} converted to upper case.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOTITLE}{Py_UNICODE ch}
-Returns the character \var{ch} converted to title case.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_TODECIMAL}{Py_UNICODE ch}
-Returns the character \var{ch} converted to a decimal positive integer.
-Returns -1 in case this is not possible. Does not raise exceptions.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_TODIGIT}{Py_UNICODE ch}
-Returns the character \var{ch} converted to a single digit integer.
-Returns -1 in case this is not possible. Does not raise exceptions.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{double}{Py_UNICODE_TONUMERIC}{Py_UNICODE ch}
-Returns the character \var{ch} converted to a (positive) double.
-Returns -1.0 in case this is not possible. Does not raise exceptions.
-\end{cfuncdesc}
-
-% --- Plain Py_UNICODE ---------------------------------------------------
-
-To create Unicode objects and access their basic sequence properties,
-use these APIs:
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_FromUnicode}{const Py_UNICODE *u,
-                                                    int size} 
-
-Create a Unicode Object from the Py_UNICODE buffer \var{u} of the
-given size. \var{u} may be \NULL{} which causes the contents to be
-undefined. It is the user's responsibility to fill in the needed data.
-The buffer is copied into the new object.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AsUnicode}{PyObject *unicode}
-Return a read-only pointer to the Unicode object's internal
-\ctype{Py_UNICODE} buffer.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyUnicode_GetSize}{PyObject *unicode}
-Return the length of the Unicode object.
-\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}
-
-% --- wchar_t support for platforms which support it ---------------------
-
-If the platform supports \ctype{wchar_t} and provides a header file
-wchar.h, Python can interface directly to this type using the
-following functions. Support is optimized if Python's own
-\ctype{Py_UNICODE} type is identical to the system's \ctype{wchar_t}.
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_FromWideChar}{const wchar_t *w,
-                                                     int size}
-Create a Unicode Object from the \ctype{whcar_t} buffer \var{w} of the
-given size. Returns \NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyUnicode_AsWideChar}{PyUnicodeObject *unicode,
-                                             wchar_t *w,
-                                             int size}
-Copies the Unicode Object contents into the \ctype{whcar_t} buffer
-\var{w}.  At most \var{size} \ctype{whcar_t} characters are copied.
-Returns the number of \ctype{whcar_t} characters copied or -1 in case
-of an error.
-\end{cfuncdesc}
-
-
-\subsubsection{Builtin Codecs \label{builtinCodecs}}
-
-Python provides a set of builtin codecs which are written in C
-for speed. All of these codecs are directly usable via the
-following functions.
-
-Many of the following APIs take two arguments encoding and
-errors. These parameters encoding and errors have the same semantics
-as the ones of the builtin unicode() Unicode object constructor.
-
-Setting encoding to NULL causes the default encoding to be used which
-is UTF-8.
-
-Error handling is set by errors which may also be set to NULL meaning
-to use the default handling defined for the codec. Default error
-handling for all builtin codecs is ``strict'' (ValueErrors are raised).
-
-The codecs all use a similar interface. Only deviation from the
-following generic ones are documented for simplicity.
-
-% --- Generic Codecs -----------------------------------------------------
-
-These are the generic codec APIs:
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Decode}{const char *s,
-                                               int size,
-                                               const char *encoding,
-                                               const char *errors}
-Create a Unicode object by decoding \var{size} bytes of the encoded
-string \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*}{PyUnicode_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 Unicode .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*}{PyUnicode_AsEncodedString}{PyObject *unicode,
-                                               const char *encoding,
-                                               const char *errors}
-Encodes a Unicode 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 Unicode .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}
-
-% --- UTF-8 Codecs -------------------------------------------------------
-
-These are the UTF-8 codec APIs:
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF8}{const char *s,
-                                               int size,
-                                               const char *errors}
-Creates a Unicode object by decoding \var{size} bytes of the UTF-8
-encoded string \var{s}. Returns \NULL{} in case an exception was
-raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF8}{const Py_UNICODE *s,
-                                               int size,
-                                               const char *errors}
-Encodes the \ctype{Py_UNICODE} buffer of the given size using UTF-8
-and returns a Python string object.  Returns \NULL{} in case an
-exception was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF8String}{PyObject *unicode}
-Encodes a Unicode objects using UTF-8 and returns the result as Python
-string object. Error handling is ``strict''. Returns
-\NULL{} in case an exception was raised by the codec.
-\end{cfuncdesc}
-
-% --- UTF-16 Codecs ------------------------------------------------------ */
-
-These are the UTF-16 codec APIs:
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF16}{const char *s,
-                                               int size,
-                                               const char *errors,
-                                               int *byteorder}
-Decodes \var{length} bytes from a UTF-16 encoded buffer string and
-returns the corresponding Unicode object.
-
-\var{errors} (if non-NULL) defines the error handling. It defaults
-to ``strict''.
-
-If \var{byteorder} is non-\NULL{}, the decoder starts decoding using
-the given byte order:
-
-\begin{verbatim}
-   *byteorder == -1: little endian
-   *byteorder == 0:  native order
-   *byteorder == 1:  big endian
-\end{verbatim}
-
-and then switches according to all byte order marks (BOM) it finds in
-the input data. BOM marks are not copied into the resulting Unicode
-string.  After completion, \var{*byteorder} is set to the current byte
-order at the end of input data.
-
-If \var{byteorder} is \NULL{}, the codec starts in native order mode.
-
-Returns \NULL{} in case an exception was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF16}{const Py_UNICODE *s,
-                                               int size,
-                                               const char *errors,
-                                               int byteorder}
-Returns a Python string object holding the UTF-16 encoded value of the
-Unicode data in \var{s}.
-
-If \var{byteorder} is not \code{0}, output is written according to the
-following byte order:
-
-\begin{verbatim}
-   byteorder == -1: little endian
-   byteorder == 0:  native byte order (writes a BOM mark)
-   byteorder == 1:  big endian
-\end{verbatim}
-
-If byteorder is \code{0}, the output string will always start with the
-Unicode BOM mark (U+FEFF). In the other two modes, no BOM mark is
-prepended.
-
-Note that \ctype{Py_UNICODE} data is being interpreted as UTF-16
-reduced to UCS-2. This trick makes it possible to add full UTF-16
-capabilities at a later point without comprimising the APIs.
-
-Returns \NULL{} in case an exception was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF16String}{PyObject *unicode}
-Returns a Python string using the UTF-16 encoding in native byte
-order. The string always starts with a BOM mark. Error handling is
-``strict''. Returns \NULL{} in case an exception was raised by the
-codec.
-\end{cfuncdesc}
-
-% --- Unicode-Escape Codecs ----------------------------------------------
-
-These are the ``Unicode Esacpe'' codec APIs:
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUnicodeEscape}{const char *s,
-                                               int size,
-                                               const char *errors}
-Creates a Unicode object by decoding \var{size} bytes of the Unicode-Esacpe
-encoded string \var{s}. Returns \NULL{} in case an exception was
-raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUnicodeEscape}{const Py_UNICODE *s,
-                                               int size,
-                                               const char *errors}
-Encodes the \ctype{Py_UNICODE} buffer of the given size using Unicode-Escape
-and returns a Python string object.  Returns \NULL{} in case an
-exception was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUnicodeEscapeString}{PyObject *unicode}
-Encodes a Unicode objects using Unicode-Escape and returns the result
-as Python string object. Error handling is ``strict''. Returns
-\NULL{} in case an exception was raised by the codec.
-\end{cfuncdesc}
-
-% --- Raw-Unicode-Escape Codecs ------------------------------------------
-
-These are the ``Raw Unicode Esacpe'' codec APIs:
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeRawUnicodeEscape}{const char *s,
-                                               int size,
-                                               const char *errors}
-Creates a Unicode object by decoding \var{size} bytes of the Raw-Unicode-Esacpe
-encoded string \var{s}. Returns \NULL{} in case an exception was
-raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeRawUnicodeEscape}{const Py_UNICODE *s,
-                                               int size,
-                                               const char *errors}
-Encodes the \ctype{Py_UNICODE} buffer of the given size using Raw-Unicode-Escape
-and returns a Python string object.  Returns \NULL{} in case an
-exception was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_AsRawUnicodeEscapeString}{PyObject *unicode}
-Encodes a Unicode objects using Raw-Unicode-Escape and returns the result
-as Python string object. Error handling is ``strict''. Returns
-\NULL{} in case an exception was raised by the codec.
-\end{cfuncdesc}
-
-% --- Latin-1 Codecs ----------------------------------------------------- 
-
-These are the Latin-1 codec APIs:
-
-Latin-1 corresponds to the first 256 Unicode ordinals and only these
-are accepted by the codecs during encoding.
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeLatin1}{const char *s,
-                                                     int size,
-                                                     const char *errors}
-Creates a Unicode object by decoding \var{size} bytes of the Latin-1
-encoded string \var{s}. Returns \NULL{} in case an exception was
-raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeLatin1}{const Py_UNICODE *s,
-                                                     int size,
-                                                     const char *errors}
-Encodes the \ctype{Py_UNICODE} buffer of the given size using Latin-1
-and returns a Python string object.  Returns \NULL{} in case an
-exception was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_AsLatin1String}{PyObject *unicode}
-Encodes a Unicode objects using Latin-1 and returns the result as
-Python string object. Error handling is ``strict''. Returns
-\NULL{} in case an exception was raised by the codec.
-\end{cfuncdesc}
-
-% --- ASCII Codecs ------------------------------------------------------- 
-
-These are the \ASCII{} codec APIs.  Only 7-bit \ASCII{} data is
-accepted. All other codes generate errors.
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeASCII}{const char *s,
-                                                    int size,
-                                                    const char *errors}
-Creates a Unicode object by decoding \var{size} bytes of the
-\ASCII{} encoded string \var{s}. Returns \NULL{} in case an exception
-was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeASCII}{const Py_UNICODE *s,
-                                                    int size,
-                                                    const char *errors}
-Encodes the \ctype{Py_UNICODE} buffer of the given size using
-\ASCII{} and returns a Python string object.  Returns \NULL{} in case
-an exception was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_AsASCIIString}{PyObject *unicode}
-Encodes a Unicode objects using \ASCII{} and returns the result as Python
-string object. Error handling is ``strict''. Returns
-\NULL{} in case an exception was raised by the codec.
-\end{cfuncdesc}
-
-% --- Character Map Codecs ----------------------------------------------- 
-
-These are the mapping codec APIs:
-
-This codec is special in that it can be used to implement many
-different codecs (and this is in fact what was done to obtain most of
-the standard codecs included in the \module{encodings} package). The
-codec uses mapping to encode and decode characters.
-
-Decoding mappings must map single string characters to single Unicode
-characters, integers (which are then interpreted as Unicode ordinals)
-or None (meaning "undefined mapping" and causing an error). 
-
-Encoding mappings must map single Unicode characters to single string
-characters, integers (which are then interpreted as Latin-1 ordinals)
-or None (meaning "undefined mapping" and causing an error).
-
-The mapping objects provided must only support the __getitem__ mapping
-interface.
-
-If a character lookup fails with a LookupError, the character is
-copied as-is meaning that its ordinal value will be interpreted as
-Unicode or Latin-1 ordinal resp. Because of this, mappings only need
-to contain those mappings which map characters to different code
-points.
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeCharmap}{const char *s,
-                                               int size,
-                                               PyObject *mapping,
-                                               const char *errors}
-Creates a Unicode object by decoding \var{size} bytes of the encoded
-string \var{s} using the given \var{mapping} object.  Returns \NULL{}
-in case an exception was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeCharmap}{const Py_UNICODE *s,
-                                               int size,
-                                               PyObject *mapping,
-                                               const char *errors}
-Encodes the \ctype{Py_UNICODE} buffer of the given size using the
-given \var{mapping} object and returns a Python string object.
-Returns \NULL{} in case an exception was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_AsCharmapString}{PyObject *unicode,
-                                                        PyObject *mapping}
-Encodes a Unicode objects using the given \var{mapping} object and
-returns the result as Python string object. Error handling is
-``strict''. Returns \NULL{} in case an exception was raised by the
-codec.
-\end{cfuncdesc}
-
-The following codec API is special in that maps Unicode to Unicode.
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_TranslateCharmap}{const Py_UNICODE *s,
-                                               int size,
-                                               PyObject *table,
-                                               const char *errors}
-Translates a \ctype{Py_UNICODE} buffer of the given length by applying
-a character mapping \var{table} to it and returns the resulting
-Unicode object.  Returns \NULL{} when an exception was raised by the
-codec.
-
-The \var{mapping} table must map Unicode ordinal integers to Unicode
-ordinal integers or None (causing deletion of the character).
-
-Mapping tables must only provide the __getitem__ interface,
-e.g. dictionaries or sequences. Unmapped character ordinals (ones
-which cause a LookupError) are left untouched and are copied as-is.
-\end{cfuncdesc}
-
-% --- MBCS codecs for Windows --------------------------------------------
-
-These are the MBCS codec APIs. They are currently only available on
-Windows and use the Win32 MBCS converters to implement the
-conversions.  Note that MBCS (or DBCS) is a class of encodings, not
-just one.  The target encoding is defined by the user settings on the
-machine running the codec.
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeMBCS}{const char *s,
-                                               int size,
-                                               const char *errors}
-Creates a Unicode object by decoding \var{size} bytes of the MBCS
-encoded string \var{s}.  Returns \NULL{} in case an exception was
-raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeMBCS}{const Py_UNICODE *s,
-                                               int size,
-                                               const char *errors}
-Encodes the \ctype{Py_UNICODE} buffer of the given size using MBCS
-and returns a Python string object.  Returns \NULL{} in case an
-exception was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_AsMBCSString}{PyObject *unicode}
-Encodes a Unicode objects using MBCS and returns the result as Python
-string object.  Error handling is ``strict''.  Returns \NULL{} in case
-an exception was raised by the codec.
-\end{cfuncdesc}
-
-% --- Methods & Slots ----------------------------------------------------
-
-\subsubsection{Methods and Slot Functions \label{unicodeMethodsAndSlots}}
-
-The following APIs are capable of handling Unicode objects and strings
-on input (we refer to them as strings in the descriptions) and return
-Unicode objects or integers as apporpriate.
-
-They all return \NULL{} or -1 in case an exception occurrs.
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Concat}{PyObject *left,
-                                               PyObject *right}
-Concat two strings giving a new Unicode string.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Split}{PyObject *s,
-                                              PyObject *sep,
-                                              int maxsplit}
-Split a string giving a list of Unicode strings.
-
-If sep is NULL, splitting will be done at all whitespace
-substrings. Otherwise, splits occur at the given separator.
-
-At most maxsplit splits will be done. If negative, no limit is set.
-
-Separators are not included in the resulting list.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Splitlines}{PyObject *s,
-                                                   int maxsplit}
-Split a Unicode string at line breaks, returning a list of Unicode
-strings.  CRLF is considered to be one line break.  The Line break
-characters are not included in the resulting strings.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Translate}{PyObject *str,
-                                                  PyObject *table,
-                                                  const char *errors}
-Translate a string by applying a character mapping table to it and
-return the resulting Unicode object.
-
-The mapping table must map Unicode ordinal integers to Unicode ordinal
-integers or None (causing deletion of the character).
-
-Mapping tables must only provide the __getitem__ interface,
-e.g. dictionaries or sequences. Unmapped character ordinals (ones
-which cause a LookupError) are left untouched and are copied as-is.
-
-\var{errors} has the usual meaning for codecs. It may be \NULL{}
-which indicates to use the default error handling.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Join}{PyObject *separator,
-                                             PyObject *seq}
-Join a sequence of strings using the given separator and return
-the resulting Unicode string.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Tailmatch}{PyObject *str,
-                                                  PyObject *substr,
-                                                  int start,
-                                                  int end,
-                                                  int direction}
-Return 1 if \var{substr} matches \var{str}[\var{start}:\var{end}] at
-the given tail end (\var{direction} == -1 means to do a prefix match,
-\var{direction} == 1 a suffix match), 0 otherwise.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Find}{PyObject *str,
-                                                  PyObject *substr,
-                                                  int start,
-                                                  int end,
-                                                  int direction}
-Return the first position of \var{substr} in
-\var{str}[\var{start}:\var{end}] using the given \var{direction}
-(\var{direction} == 1 means to do a forward search,
-\var{direction} == -1 a backward search), 0 otherwise.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Count}{PyObject *str,
-                                                  PyObject *substr,
-                                                  int start,
-                                                  int end}
-Count the number of occurrences of \var{substr} in
-\var{str}[\var{start}:\var{end}]
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Replace}{PyObject *str,
-                                                PyObject *substr,
-                                                PyObject *replstr,
-                                                int maxcount}
-Replace at most \var{maxcount} occurrences of \var{substr} in
-\var{str} with \var{replstr} and return the resulting Unicode object.
-\var{maxcount} == -1 means: replace all occurrences.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyUnicode_Compare}{PyObject *left, PyObject *right}
-Compare two strings and return -1, 0, 1 for less than, equal,
-greater than resp.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Format}{PyObject *format,
-                                              PyObject *args}
-Returns a new string object from \var{format} and \var{args}; this is
-analogous to \code{\var{format} \%\ \var{args}}.  The
-\var{args} argument must be a tuple.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyUnicode_Contains}{PyObject *container,
-                                           PyObject *element}
-Checks whether \var{element} is contained in \var{container} and
-returns true or false accordingly.
-
-\var{element} has to coerce to a one element Unicode string. \code{-1} is
-returned in case of an error.
-\end{cfuncdesc}
-
-
-\subsection{Buffer Objects \label{bufferObjects}}
-\sectionauthor{Greg Stein}{gstein@lyra.org}
-
-\obindex{buffer}
-Python objects implemented in C can export a group of functions called
-the ``buffer\index{buffer interface} interface.''  These functions can
-be used by an object to expose its data in a raw, byte-oriented
-format. Clients of the object can use the buffer interface to access
-the object data directly, without needing to copy it first.
-
-Two examples of objects that support 
-the buffer interface are strings and arrays. The string object exposes 
-the character contents in the buffer interface's byte-oriented
-form. An array can also expose its contents, but it should be noted
-that array elements may be multi-byte values.
-
-An example user of the buffer interface is the file object's
-\method{write()} method. Any object that can export a series of bytes
-through the buffer interface can be written to a file. There are a
-number of format codes to \cfunction{PyArgs_ParseTuple()} that operate 
-against an object's buffer interface, returning data from the target
-object.
-
-More information on the buffer interface is provided in the section
-``Buffer Object Structures'' (section \ref{buffer-structs}), under
-the description for \ctype{PyBufferProcs}\ttindex{PyBufferProcs}.
-
-A ``buffer object'' is defined in the \file{bufferobject.h} header
-(included by \file{Python.h}). These objects look very similar to
-string objects at the Python programming level: they support slicing,
-indexing, concatenation, and some other standard string
-operations. However, their data can come from one of two sources: from
-a block of memory, or from another object which exports the buffer
-interface.
-
-Buffer objects are useful as a way to expose the data from another
-object's buffer interface to the Python programmer. They can also be
-used as a zero-copy slicing mechanism. Using their ability to
-reference a block of memory, it is possible to expose any data to the
-Python programmer quite easily. The memory could be a large, constant
-array in a C extension, it could be a raw block of memory for
-manipulation before passing to an operating system library, or it
-could be used to pass around structured data in its native, in-memory
-format.
-
-\begin{ctypedesc}{PyBufferObject}
-This subtype of \ctype{PyObject} represents a buffer object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyBuffer_Type}
-The instance of \ctype{PyTypeObject} which represents the Python
-buffer type; it is the same object as \code{types.BufferType} in the
-Python layer.\withsubitem{(in module types)}{\ttindex{BufferType}}.
-\end{cvardesc}
-
-\begin{cvardesc}{int}{Py_END_OF_BUFFER}
-This constant may be passed as the \var{size} parameter to
-\cfunction{PyBuffer_FromObject()} or
-\cfunction{PyBuffer_FromReadWriteObject()}. It indicates that the new
-\ctype{PyBufferObject} should refer to \var{base} object from the
-specified \var{offset} to the end of its exported buffer. Using this
-enables the caller to avoid querying the \var{base} object for its
-length.
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyBuffer_Check}{PyObject *p}
-Return true if the argument has type \cdata{PyBuffer_Type}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyBuffer_FromObject}{PyObject *base,
-                                                  int offset, int size}
-Return a new read-only buffer object.  This raises
-\exception{TypeError} if \var{base} doesn't support the read-only
-buffer protocol or doesn't provide exactly one buffer segment, or it
-raises \exception{ValueError} if \var{offset} is less than zero. The
-buffer will hold a reference to the \var{base} object, and the
-buffer's contents will refer to the \var{base} object's buffer
-interface, starting as position \var{offset} and extending for
-\var{size} bytes. If \var{size} is \constant{Py_END_OF_BUFFER}, then
-the new buffer's contents extend to the length of the
-\var{base} object's exported buffer data.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyBuffer_FromReadWriteObject}{PyObject *base,
-                                                           int offset,
-                                                           int size}
-Return a new writable buffer object.  Parameters and exceptions are
-similar to those for \cfunction{PyBuffer_FromObject()}.
-If the \var{base} object does not export the writeable buffer
-protocol, then \exception{TypeError} is raised.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyBuffer_FromMemory}{void *ptr, int size}
-Return a new read-only buffer object that reads from a specified
-location in memory, with a specified size.
-The caller is responsible for ensuring that the memory buffer, passed
-in as \var{ptr}, is not deallocated while the returned buffer object
-exists.  Raises \exception{ValueError} if \var{size} is less than
-zero.  Note that \constant{Py_END_OF_BUFFER} may \emph{not} be passed
-for the \var{size} parameter; \exception{ValueError} will be raised in 
-that case.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyBuffer_FromReadWriteMemory}{void *ptr, int size}
-Similar to \cfunction{PyBuffer_FromMemory()}, but the returned buffer
-is writable.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyBuffer_New}{int size}
-Returns a new writable buffer object that maintains its own memory
-buffer of \var{size} bytes.  \exception{ValueError} is returned if
-\var{size} is not zero or positive.
-\end{cfuncdesc}
-
-
-\subsection{Tuple Objects \label{tupleObjects}}
-
-\obindex{tuple}
-\begin{ctypedesc}{PyTupleObject}
-This subtype of \ctype{PyObject} represents a Python tuple object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyTuple_Type}
-This instance of \ctype{PyTypeObject} represents the Python tuple
-type; it is the same object as \code{types.TupleType} in the Python
-layer.\withsubitem{(in module types)}{\ttindex{TupleType}}.
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p}
-Return true if the argument is a tuple object.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyTuple_New}{int len}
-Return a new tuple object of size \var{len}, or \NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyTuple_Size}{PyObject *p}
-Takes a pointer to a tuple object, and returns the size
-of that tuple.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyTuple_GetItem}{PyObject *p, int pos}
-Returns the object at position \var{pos} in the tuple pointed
-to by \var{p}.  If \var{pos} is out of bounds, returns \NULL{} and
-sets an \exception{IndexError} exception.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyTuple_GET_ITEM}{PyObject *p, int pos}
-Does the same, but does no checking of its arguments.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyTuple_GetSlice}{PyObject *p,
-                                               int low, int high}
-Takes a slice of the tuple pointed to by \var{p} from
-\var{low} to \var{high} and returns it as a new tuple.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyTuple_SetItem}{PyObject *p,
-                                        int pos, PyObject *o}
-Inserts a reference to object \var{o} at position \var{pos} of
-the tuple pointed to by \var{p}. It returns \code{0} on success.
-\strong{Note:}  This function ``steals'' a reference to \var{o}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyTuple_SET_ITEM}{PyObject *p,
-                                          int pos, PyObject *o}
-Does the same, but does no error checking, and
-should \emph{only} be used to fill in brand new tuples.
-\strong{Note:}  This function ``steals'' a reference to \var{o}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{_PyTuple_Resize}{PyObject **p,
-                                        int newsize, int last_is_sticky}
-Can be used to resize a tuple.  \var{newsize} will be the new length
-of the tuple.  Because tuples are \emph{supposed} to be immutable,
-this should only be used if there is only one reference to the object.
-Do \emph{not} use this if the tuple may already be known to some other
-part of the code.  The tuple will always grow or shrink at the end.  The
-\var{last_is_sticky} flag is not used and should always be false.  Think
-of this as destroying the old tuple and creating a new one, only more
-efficiently.  Returns \code{0} on success and \code{-1} on failure (in
-which case a \exception{MemoryError} or \exception{SystemError} will be
-raised).
-\end{cfuncdesc}
-
-
-\subsection{List Objects \label{listObjects}}
-
-\obindex{list}
-\begin{ctypedesc}{PyListObject}
-This subtype of \ctype{PyObject} represents a Python list object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyList_Type}
-This instance of \ctype{PyTypeObject} represents the Python list
-type.  This is the same object as \code{types.ListType}.
-\withsubitem{(in module types)}{\ttindex{ListType}}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyList_Check}{PyObject *p}
-Returns true if its argument is a \ctype{PyListObject}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyList_New}{int len}
-Returns a new list of length \var{len} on success, or \NULL{} on
-failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_Size}{PyObject *list}
-Returns the length of the list object in \var{list}; this is
-equivalent to \samp{len(\var{list})} on a list object.
-\bifuncindex{len}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_GET_SIZE}{PyObject *list}
-Macro form of \cfunction{PyList_Size()} without error checking.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyList_GetItem}{PyObject *list, int index}
-Returns the object at position \var{pos} in the list pointed
-to by \var{p}.  If \var{pos} is out of bounds, returns \NULL{} and
-sets an \exception{IndexError} exception.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyList_GET_ITEM}{PyObject *list, int i}
-Macro form of \cfunction{PyList_GetItem()} without error checking.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *list, int index,
-                                       PyObject *item}
-Sets the item at index \var{index} in list to \var{item}.
-Returns \code{0} on success or \code{-1} on failure.
-\strong{Note:}  This function ``steals'' a reference to \var{item} and
-discards a reference to an item already in the list at the affected
-position.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyList_SET_ITEM}{PyObject *list, int i,
-                                              PyObject *o}
-Macro form of \cfunction{PyList_SetItem()} without error checking.
-\strong{Note:}  This function ``steals'' a reference to \var{item},
-and, unlike \cfunction{PyList_SetItem()}, does \emph{not} discard a
-reference to any item that it being replaced; any reference in
-\var{list} at position \var{i} will be leaked.  This is normally only
-used to fill in new lists where there is no previous content.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *list, int index,
-                                      PyObject *item}
-Inserts the item \var{item} into list \var{list} in front of index
-\var{index}.  Returns \code{0} if successful; returns \code{-1} and
-raises an exception if unsuccessful.  Analogous to
-\code{\var{list}.insert(\var{index}, \var{item})}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_Append}{PyObject *list, PyObject *item}
-Appends the object \var{item} at the end of list \var{list}.  Returns
-\code{0} if successful; returns \code{-1} and sets an exception if
-unsuccessful.  Analogous to \code{\var{list}.append(\var{item})}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyList_GetSlice}{PyObject *list,
-                                              int low, int high}
-Returns a list of the objects in \var{list} containing the objects 
-\emph{between} \var{low} and \var{high}.  Returns NULL and sets an
-exception if unsuccessful.
-Analogous to \code{\var{list}[\var{low}:\var{high}]}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *list,
-                                        int low, int high,
-                                        PyObject *itemlist}
-Sets the slice of \var{list} between \var{low} and \var{high} to the
-contents of \var{itemlist}.  Analogous to
-\code{\var{list}[\var{low}:\var{high}] = \var{itemlist}}.  Returns
-\code{0} on success, \code{-1} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_Sort}{PyObject *list}
-Sorts the items of \var{list} in place.  Returns \code{0} on success,
-\code{-1} on failure.  This is equivalent to
-\samp{\var{list}.sort()}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *list}
-Reverses the items of \var{list} in place.  Returns \code{0} on
-success, \code{-1} on failure.  This is the equivalent of
-\samp{\var{list}.reverse()}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyList_AsTuple}{PyObject *list}
-Returns a new tuple object containing the contents of \var{list};
-equivalent to \samp{tuple(\var{list})}.\bifuncindex{tuple}
-\end{cfuncdesc}
-
-
-\section{Mapping Objects \label{mapObjects}}
-
-\obindex{mapping}
-
-
-\subsection{Dictionary Objects \label{dictObjects}}
-
-\obindex{dictionary}
-\begin{ctypedesc}{PyDictObject}
-This subtype of \ctype{PyObject} represents a Python dictionary object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyDict_Type}
-This instance of \ctype{PyTypeObject} represents the Python dictionary 
-type.  This is exposed to Python programs as \code{types.DictType} and 
-\code{types.DictionaryType}.
-\withsubitem{(in module types)}{\ttindex{DictType}\ttindex{DictionaryType}}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyDict_Check}{PyObject *p}
-Returns true if its argument is a \ctype{PyDictObject}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDict_New}{}
-Returns a new empty dictionary, or \NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyDict_Clear}{PyObject *p}
-Empties an existing dictionary of all key-value pairs.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDict_Copy}{PyObject *p}
-Returns a new dictionary that contains the same key-value pairs as p.
-Empties an existing dictionary of all key-value pairs.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDict_SetItem}{PyObject *p, PyObject *key,
-                                       PyObject *val}
-Inserts \var{value} into the dictionary \var{p} with a key of \var{key}.
-\var{key} must be hashable; if it isn't, \exception{TypeError} will be 
-raised.
-Returns \code{0} on success or \code{-1} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDict_SetItemString}{PyObject *p,
-            char *key,
-            PyObject *val}
-Inserts \var{value} into the dictionary \var{p} using \var{key}
-as a key. \var{key} should be a \ctype{char*}.  The key object is
-created using \code{PyString_FromString(\var{key})}.
-Returns \code{0} on success or \code{-1} on failure.
-\ttindex{PyString_FromString()}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDict_DelItem}{PyObject *p, PyObject *key}
-Removes the entry in dictionary \var{p} with key \var{key}.
-\var{key} must be hashable; if it isn't, \exception{TypeError} is
-raised.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDict_DelItemString}{PyObject *p, char *key}
-Removes the entry in dictionary \var{p} which has a key
-specified by the string \var{key}.
-Returns \code{0} on success or \code{-1} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDict_GetItem}{PyObject *p, PyObject *key}
-Returns the object from dictionary \var{p} which has a key
-\var{key}.  Returns \NULL{} if the key \var{key} is not present, but
-\emph{without} setting an exception.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDict_GetItemString}{PyObject *p, char *key}
-This is the same as \cfunction{PyDict_GetItem()}, but \var{key} is
-specified as a \ctype{char*}, rather than a \ctype{PyObject*}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDict_Items}{PyObject *p}
-Returns a \ctype{PyListObject} containing all the items 
-from the dictionary, as in the dictinoary method \method{items()} (see
-the \citetitle[../lib/lib.html]{Python Library Reference}).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDict_Keys}{PyObject *p}
-Returns a \ctype{PyListObject} containing all the keys 
-from the dictionary, as in the dictionary method \method{keys()} (see the
-\citetitle[../lib/lib.html]{Python Library Reference}).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDict_Values}{PyObject *p}
-Returns a \ctype{PyListObject} containing all the values 
-from the dictionary \var{p}, as in the dictionary method
-\method{values()} (see the \citetitle[../lib/lib.html]{Python Library
-Reference}).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDict_Size}{PyObject *p}
-Returns the number of items in the dictionary.  This is equivalent to
-\samp{len(\var{p})} on a dictionary.\bifuncindex{len}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDict_Next}{PyObject *p, int *ppos,
-                                    PyObject **pkey, PyObject **pvalue}
-Iterate over all key-value pairs in the dictionary \var{p}.  The
-\ctype{int} referred to by \var{ppos} must be initialized to \code{0}
-prior to the first call to this function to start the iteration; the
-function returns true for each pair in the dictionary, and false once
-all pairs have been reported.  The parameters \var{pkey} and
-\var{pvalue} should either point to \ctype{PyObject*} variables that
-will be filled in with each key and value, respectively, or may be
-\NULL.
-
-For example:
-
-\begin{verbatim}
-PyObject *key, *value;
-int pos = 0;
-
-while (PyDict_Next(self->dict, &pos, &key, &value)) {
-    /* do something interesting with the values... */
-    ...
-}
-\end{verbatim}
-
-The dictionary \var{p} should not be mutated during iteration.  It is
-safe (since Python 2.1) to modify the values of the keys as you
-iterate over the dictionary, for example:
-
-\begin{verbatim}
-PyObject *key, *value;
-int pos = 0;
-
-while (PyDict_Next(self->dict, &pos, &key, &value)) {
-    int i = PyInt_AS_LONG(value) + 1;
-    PyObject *o = PyInt_FromLong(i);
-    if (o == NULL)
-        return -1;
-    if (PyDict_SetItem(self->dict, key, o) < 0) {
-        Py_DECREF(o);
-        return -1;
-    }
-    Py_DECREF(o);
-}
-\end{verbatim}
-\end{cfuncdesc}
-
-
 \section{Numeric Objects \label{numericObjects}}
 
 \obindex{numeric}
 
 
 
+\section{Sequence Objects \label{sequenceObjects}}
+
+\obindex{sequence}
+Generic operations on sequence objects were discussed in the previous 
+chapter; this section deals with the specific kinds of sequence 
+objects that are intrinsic to the Python language.
+
+
+\subsection{String Objects \label{stringObjects}}
+
+These functions raise \exception{TypeError} when expecting a string
+parameter and are called with a non-string parameter.
+
+\obindex{string}
+\begin{ctypedesc}{PyStringObject}
+This subtype of \ctype{PyObject} represents a Python string object.
+\end{ctypedesc}
+
+\begin{cvardesc}{PyTypeObject}{PyString_Type}
+This instance of \ctype{PyTypeObject} represents the Python string
+type; it is the same object as \code{types.TypeType} in the Python
+layer.\withsubitem{(in module types)}{\ttindex{StringType}}.
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyString_Check}{PyObject *o}
+Returns true if the object \var{o} is a string object.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyString_FromString}{const char *v}
+Returns a new string object with the value \var{v} on success, and
+\NULL{} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyString_FromStringAndSize}{const char *v,
+                                                         int len}
+Returns a new string object with the value \var{v} and length
+\var{len} on success, and \NULL{} on failure.  If \var{v} is \NULL{},
+the contents of the string are uninitialized.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyString_Size}{PyObject *string}
+Returns the length of the string in string object \var{string}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyObject *string}
+Macro form of \cfunction{PyString_Size()} but without error
+checking.
+\end{cfuncdesc}
+
+\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}
+
+\begin{cfuncdesc}{int}{PyString_AsStringAndSize}{PyObject *obj,
+                                                 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}.
+
+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
+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}
+
+\begin{cfuncdesc}{void}{PyString_Concat}{PyObject **string,
+                                         PyObject *newpart}
+Creates a new string object in \var{*string} containing the
+contents of \var{newpart} appended to \var{string}; the caller will
+own the new reference.  The reference to the old value of \var{string}
+will be stolen.  If the new string
+cannot be created, the old reference to \var{string} will still be
+discarded and the value of \var{*string} will be set to
+\NULL{}; the appropriate exception will be set.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **string,
+                                               PyObject *newpart}
+Creates a new string object in \var{*string} containing the contents
+of \var{newpart} appended to \var{string}.  This version decrements
+the reference count of \var{newpart}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **string, int newsize}
+A way to resize a string object even though it is ``immutable''.  
+Only use this to build up a brand new string object; don't use this if
+the string may already be known in other parts of the code.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyString_Format}{PyObject *format,
+                                              PyObject *args}
+Returns a new string object from \var{format} and \var{args}.  Analogous
+to \code{\var{format} \%\ \var{args}}.  The \var{args} argument must be
+a tuple.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyString_InternInPlace}{PyObject **string}
+Intern the argument \var{*string} in place.  The argument must be the
+address of a pointer variable pointing to a Python string object.
+If there is an existing interned string that is the same as
+\var{*string}, it sets \var{*string} to it (decrementing the reference 
+count of the old string object and incrementing the reference count of
+the interned string object), otherwise it leaves \var{*string} alone
+and interns it (incrementing its reference count).  (Clarification:
+even though there is a lot of talk about reference counts, think of
+this function as reference-count-neutral; you own the object after
+the call if and only if you owned it before the call.)
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyString_InternFromString}{const char *v}
+A combination of \cfunction{PyString_FromString()} and
+\cfunction{PyString_InternInPlace()}, returning either a new string object
+that has been interned, or a new (``owned'') reference to an earlier
+interned string object with the same value.
+\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}}
+\sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com}
+
+%--- Unicode Type -------------------------------------------------------
+
+These are the basic Unicode object types used for the Unicode
+implementation in Python:
+
+\begin{ctypedesc}{Py_UNICODE}
+This type represents a 16-bit unsigned storage type which is used by
+Python internally as basis for holding Unicode ordinals. On platforms
+where \ctype{wchar_t} is available and also has 16-bits,
+\ctype{Py_UNICODE} is a typedef alias for \ctype{wchar_t} to enhance
+native platform compatibility. On all other platforms,
+\ctype{Py_UNICODE} is a typedef alias for \ctype{unsigned short}.
+\end{ctypedesc}
+
+\begin{ctypedesc}{PyUnicodeObject}
+This subtype of \ctype{PyObject} represents a Python Unicode object.
+\end{ctypedesc}
+
+\begin{cvardesc}{PyTypeObject}{PyUnicode_Type}
+This instance of \ctype{PyTypeObject} represents the Python Unicode type.
+\end{cvardesc}
+
+%--- These are really C macros... is there a macrodesc TeX macro ?
+
+The following APIs are really C macros and can be used to do fast
+checks and to access internal read-only data of Unicode objects:
+
+\begin{cfuncdesc}{int}{PyUnicode_Check}{PyObject *o}
+Returns true if the object \var{o} is a Unicode object.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyUnicode_GET_SIZE}{PyObject *o}
+Returns the size of the object.  o has to be a
+PyUnicodeObject (not checked).
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyUnicode_GET_DATA_SIZE}{PyObject *o}
+Returns the size of the object's internal buffer in bytes. o has to be
+a PyUnicodeObject (not checked).
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AS_UNICODE}{PyObject *o}
+Returns a pointer to the internal Py_UNICODE buffer of the object. o
+has to be a PyUnicodeObject (not checked).
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{const char*}{PyUnicode_AS_DATA}{PyObject *o}
+Returns a (const char *) pointer to the internal buffer of the object.
+o has to be a PyUnicodeObject (not checked).
+\end{cfuncdesc}
+
+% --- Unicode character properties ---------------------------------------
+
+Unicode provides many different character properties. The most often
+needed ones are available through these macros which are mapped to C
+functions depending on the Python configuration.
+
+\begin{cfuncdesc}{int}{Py_UNICODE_ISSPACE}{Py_UNICODE ch}
+Returns 1/0 depending on whether \var{ch} is a whitespace character.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_ISLOWER}{Py_UNICODE ch}
+Returns 1/0 depending on whether \var{ch} is a lowercase character.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_ISUPPER}{Py_UNICODE ch}
+Returns 1/0 depending on whether \var{ch} is an uppercase character.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_ISTITLE}{Py_UNICODE ch}
+Returns 1/0 depending on whether \var{ch} is a titlecase character.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_ISLINEBREAK}{Py_UNICODE ch}
+Returns 1/0 depending on whether \var{ch} is a linebreak character.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_ISDECIMAL}{Py_UNICODE ch}
+Returns 1/0 depending on whether \var{ch} is a decimal character.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_ISDIGIT}{Py_UNICODE ch}
+Returns 1/0 depending on whether \var{ch} is a digit character.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_ISNUMERIC}{Py_UNICODE ch}
+Returns 1/0 depending on whether \var{ch} is a numeric character.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_ISALPHA}{Py_UNICODE ch}
+Returns 1/0 depending on whether \var{ch} is an alphabetic character.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_ISALNUM}{Py_UNICODE ch}
+Returns 1/0 depending on whether \var{ch} is an alphanumeric character.
+\end{cfuncdesc}
+
+These APIs can be used for fast direct character conversions:
+
+\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOLOWER}{Py_UNICODE ch}
+Returns the character \var{ch} converted to lower case.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOUPPER}{Py_UNICODE ch}
+Returns the character \var{ch} converted to upper case.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOTITLE}{Py_UNICODE ch}
+Returns the character \var{ch} converted to title case.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_TODECIMAL}{Py_UNICODE ch}
+Returns the character \var{ch} converted to a decimal positive integer.
+Returns -1 in case this is not possible. Does not raise exceptions.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_UNICODE_TODIGIT}{Py_UNICODE ch}
+Returns the character \var{ch} converted to a single digit integer.
+Returns -1 in case this is not possible. Does not raise exceptions.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{double}{Py_UNICODE_TONUMERIC}{Py_UNICODE ch}
+Returns the character \var{ch} converted to a (positive) double.
+Returns -1.0 in case this is not possible. Does not raise exceptions.
+\end{cfuncdesc}
+
+% --- Plain Py_UNICODE ---------------------------------------------------
+
+To create Unicode objects and access their basic sequence properties,
+use these APIs:
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_FromUnicode}{const Py_UNICODE *u,
+                                                    int size} 
+
+Create a Unicode Object from the Py_UNICODE buffer \var{u} of the
+given size. \var{u} may be \NULL{} which causes the contents to be
+undefined. It is the user's responsibility to fill in the needed data.
+The buffer is copied into the new object.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AsUnicode}{PyObject *unicode}
+Return a read-only pointer to the Unicode object's internal
+\ctype{Py_UNICODE} buffer.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyUnicode_GetSize}{PyObject *unicode}
+Return the length of the Unicode object.
+\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}
+
+% --- wchar_t support for platforms which support it ---------------------
+
+If the platform supports \ctype{wchar_t} and provides a header file
+wchar.h, Python can interface directly to this type using the
+following functions. Support is optimized if Python's own
+\ctype{Py_UNICODE} type is identical to the system's \ctype{wchar_t}.
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_FromWideChar}{const wchar_t *w,
+                                                     int size}
+Create a Unicode Object from the \ctype{whcar_t} buffer \var{w} of the
+given size. Returns \NULL{} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyUnicode_AsWideChar}{PyUnicodeObject *unicode,
+                                             wchar_t *w,
+                                             int size}
+Copies the Unicode Object contents into the \ctype{whcar_t} buffer
+\var{w}.  At most \var{size} \ctype{whcar_t} characters are copied.
+Returns the number of \ctype{whcar_t} characters copied or -1 in case
+of an error.
+\end{cfuncdesc}
+
+
+\subsubsection{Builtin Codecs \label{builtinCodecs}}
+
+Python provides a set of builtin codecs which are written in C
+for speed. All of these codecs are directly usable via the
+following functions.
+
+Many of the following APIs take two arguments encoding and
+errors. These parameters encoding and errors have the same semantics
+as the ones of the builtin unicode() Unicode object constructor.
+
+Setting encoding to NULL causes the default encoding to be used which
+is UTF-8.
+
+Error handling is set by errors which may also be set to NULL meaning
+to use the default handling defined for the codec. Default error
+handling for all builtin codecs is ``strict'' (ValueErrors are raised).
+
+The codecs all use a similar interface. Only deviation from the
+following generic ones are documented for simplicity.
+
+% --- Generic Codecs -----------------------------------------------------
+
+These are the generic codec APIs:
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_Decode}{const char *s,
+                                               int size,
+                                               const char *encoding,
+                                               const char *errors}
+Create a Unicode object by decoding \var{size} bytes of the encoded
+string \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*}{PyUnicode_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 Unicode .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*}{PyUnicode_AsEncodedString}{PyObject *unicode,
+                                               const char *encoding,
+                                               const char *errors}
+Encodes a Unicode 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 Unicode .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}
+
+% --- UTF-8 Codecs -------------------------------------------------------
+
+These are the UTF-8 codec APIs:
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF8}{const char *s,
+                                               int size,
+                                               const char *errors}
+Creates a Unicode object by decoding \var{size} bytes of the UTF-8
+encoded string \var{s}. Returns \NULL{} in case an exception was
+raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF8}{const Py_UNICODE *s,
+                                               int size,
+                                               const char *errors}
+Encodes the \ctype{Py_UNICODE} buffer of the given size using UTF-8
+and returns a Python string object.  Returns \NULL{} in case an
+exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF8String}{PyObject *unicode}
+Encodes a Unicode objects using UTF-8 and returns the result as Python
+string object. Error handling is ``strict''. Returns
+\NULL{} in case an exception was raised by the codec.
+\end{cfuncdesc}
+
+% --- UTF-16 Codecs ------------------------------------------------------ */
+
+These are the UTF-16 codec APIs:
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF16}{const char *s,
+                                               int size,
+                                               const char *errors,
+                                               int *byteorder}
+Decodes \var{length} bytes from a UTF-16 encoded buffer string and
+returns the corresponding Unicode object.
+
+\var{errors} (if non-NULL) defines the error handling. It defaults
+to ``strict''.
+
+If \var{byteorder} is non-\NULL{}, the decoder starts decoding using
+the given byte order:
+
+\begin{verbatim}
+   *byteorder == -1: little endian
+   *byteorder == 0:  native order
+   *byteorder == 1:  big endian
+\end{verbatim}
+
+and then switches according to all byte order marks (BOM) it finds in
+the input data. BOM marks are not copied into the resulting Unicode
+string.  After completion, \var{*byteorder} is set to the current byte
+order at the end of input data.
+
+If \var{byteorder} is \NULL{}, the codec starts in native order mode.
+
+Returns \NULL{} in case an exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF16}{const Py_UNICODE *s,
+                                               int size,
+                                               const char *errors,
+                                               int byteorder}
+Returns a Python string object holding the UTF-16 encoded value of the
+Unicode data in \var{s}.
+
+If \var{byteorder} is not \code{0}, output is written according to the
+following byte order:
+
+\begin{verbatim}
+   byteorder == -1: little endian
+   byteorder == 0:  native byte order (writes a BOM mark)
+   byteorder == 1:  big endian
+\end{verbatim}
+
+If byteorder is \code{0}, the output string will always start with the
+Unicode BOM mark (U+FEFF). In the other two modes, no BOM mark is
+prepended.
+
+Note that \ctype{Py_UNICODE} data is being interpreted as UTF-16
+reduced to UCS-2. This trick makes it possible to add full UTF-16
+capabilities at a later point without comprimising the APIs.
+
+Returns \NULL{} in case an exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF16String}{PyObject *unicode}
+Returns a Python string using the UTF-16 encoding in native byte
+order. The string always starts with a BOM mark. Error handling is
+``strict''. Returns \NULL{} in case an exception was raised by the
+codec.
+\end{cfuncdesc}
+
+% --- Unicode-Escape Codecs ----------------------------------------------
+
+These are the ``Unicode Esacpe'' codec APIs:
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUnicodeEscape}{const char *s,
+                                               int size,
+                                               const char *errors}
+Creates a Unicode object by decoding \var{size} bytes of the Unicode-Esacpe
+encoded string \var{s}. Returns \NULL{} in case an exception was
+raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUnicodeEscape}{const Py_UNICODE *s,
+                                               int size,
+                                               const char *errors}
+Encodes the \ctype{Py_UNICODE} buffer of the given size using Unicode-Escape
+and returns a Python string object.  Returns \NULL{} in case an
+exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUnicodeEscapeString}{PyObject *unicode}
+Encodes a Unicode objects using Unicode-Escape and returns the result
+as Python string object. Error handling is ``strict''. Returns
+\NULL{} in case an exception was raised by the codec.
+\end{cfuncdesc}
+
+% --- Raw-Unicode-Escape Codecs ------------------------------------------
+
+These are the ``Raw Unicode Esacpe'' codec APIs:
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeRawUnicodeEscape}{const char *s,
+                                               int size,
+                                               const char *errors}
+Creates a Unicode object by decoding \var{size} bytes of the Raw-Unicode-Esacpe
+encoded string \var{s}. Returns \NULL{} in case an exception was
+raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeRawUnicodeEscape}{const Py_UNICODE *s,
+                                               int size,
+                                               const char *errors}
+Encodes the \ctype{Py_UNICODE} buffer of the given size using Raw-Unicode-Escape
+and returns a Python string object.  Returns \NULL{} in case an
+exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_AsRawUnicodeEscapeString}{PyObject *unicode}
+Encodes a Unicode objects using Raw-Unicode-Escape and returns the result
+as Python string object. Error handling is ``strict''. Returns
+\NULL{} in case an exception was raised by the codec.
+\end{cfuncdesc}
+
+% --- Latin-1 Codecs ----------------------------------------------------- 
+
+These are the Latin-1 codec APIs:
+
+Latin-1 corresponds to the first 256 Unicode ordinals and only these
+are accepted by the codecs during encoding.
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeLatin1}{const char *s,
+                                                     int size,
+                                                     const char *errors}
+Creates a Unicode object by decoding \var{size} bytes of the Latin-1
+encoded string \var{s}. Returns \NULL{} in case an exception was
+raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeLatin1}{const Py_UNICODE *s,
+                                                     int size,
+                                                     const char *errors}
+Encodes the \ctype{Py_UNICODE} buffer of the given size using Latin-1
+and returns a Python string object.  Returns \NULL{} in case an
+exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_AsLatin1String}{PyObject *unicode}
+Encodes a Unicode objects using Latin-1 and returns the result as
+Python string object. Error handling is ``strict''. Returns
+\NULL{} in case an exception was raised by the codec.
+\end{cfuncdesc}
+
+% --- ASCII Codecs ------------------------------------------------------- 
+
+These are the \ASCII{} codec APIs.  Only 7-bit \ASCII{} data is
+accepted. All other codes generate errors.
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeASCII}{const char *s,
+                                                    int size,
+                                                    const char *errors}
+Creates a Unicode object by decoding \var{size} bytes of the
+\ASCII{} encoded string \var{s}. Returns \NULL{} in case an exception
+was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeASCII}{const Py_UNICODE *s,
+                                                    int size,
+                                                    const char *errors}
+Encodes the \ctype{Py_UNICODE} buffer of the given size using
+\ASCII{} and returns a Python string object.  Returns \NULL{} in case
+an exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_AsASCIIString}{PyObject *unicode}
+Encodes a Unicode objects using \ASCII{} and returns the result as Python
+string object. Error handling is ``strict''. Returns
+\NULL{} in case an exception was raised by the codec.
+\end{cfuncdesc}
+
+% --- Character Map Codecs ----------------------------------------------- 
+
+These are the mapping codec APIs:
+
+This codec is special in that it can be used to implement many
+different codecs (and this is in fact what was done to obtain most of
+the standard codecs included in the \module{encodings} package). The
+codec uses mapping to encode and decode characters.
+
+Decoding mappings must map single string characters to single Unicode
+characters, integers (which are then interpreted as Unicode ordinals)
+or None (meaning "undefined mapping" and causing an error). 
+
+Encoding mappings must map single Unicode characters to single string
+characters, integers (which are then interpreted as Latin-1 ordinals)
+or None (meaning "undefined mapping" and causing an error).
+
+The mapping objects provided must only support the __getitem__ mapping
+interface.
+
+If a character lookup fails with a LookupError, the character is
+copied as-is meaning that its ordinal value will be interpreted as
+Unicode or Latin-1 ordinal resp. Because of this, mappings only need
+to contain those mappings which map characters to different code
+points.
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeCharmap}{const char *s,
+                                               int size,
+                                               PyObject *mapping,
+                                               const char *errors}
+Creates a Unicode object by decoding \var{size} bytes of the encoded
+string \var{s} using the given \var{mapping} object.  Returns \NULL{}
+in case an exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeCharmap}{const Py_UNICODE *s,
+                                               int size,
+                                               PyObject *mapping,
+                                               const char *errors}
+Encodes the \ctype{Py_UNICODE} buffer of the given size using the
+given \var{mapping} object and returns a Python string object.
+Returns \NULL{} in case an exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_AsCharmapString}{PyObject *unicode,
+                                                        PyObject *mapping}
+Encodes a Unicode objects using the given \var{mapping} object and
+returns the result as Python string object. Error handling is
+``strict''. Returns \NULL{} in case an exception was raised by the
+codec.
+\end{cfuncdesc}
+
+The following codec API is special in that maps Unicode to Unicode.
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_TranslateCharmap}{const Py_UNICODE *s,
+                                               int size,
+                                               PyObject *table,
+                                               const char *errors}
+Translates a \ctype{Py_UNICODE} buffer of the given length by applying
+a character mapping \var{table} to it and returns the resulting
+Unicode object.  Returns \NULL{} when an exception was raised by the
+codec.
+
+The \var{mapping} table must map Unicode ordinal integers to Unicode
+ordinal integers or None (causing deletion of the character).
+
+Mapping tables must only provide the __getitem__ interface,
+e.g. dictionaries or sequences. Unmapped character ordinals (ones
+which cause a LookupError) are left untouched and are copied as-is.
+\end{cfuncdesc}
+
+% --- MBCS codecs for Windows --------------------------------------------
+
+These are the MBCS codec APIs. They are currently only available on
+Windows and use the Win32 MBCS converters to implement the
+conversions.  Note that MBCS (or DBCS) is a class of encodings, not
+just one.  The target encoding is defined by the user settings on the
+machine running the codec.
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeMBCS}{const char *s,
+                                               int size,
+                                               const char *errors}
+Creates a Unicode object by decoding \var{size} bytes of the MBCS
+encoded string \var{s}.  Returns \NULL{} in case an exception was
+raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeMBCS}{const Py_UNICODE *s,
+                                               int size,
+                                               const char *errors}
+Encodes the \ctype{Py_UNICODE} buffer of the given size using MBCS
+and returns a Python string object.  Returns \NULL{} in case an
+exception was raised by the codec.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_AsMBCSString}{PyObject *unicode}
+Encodes a Unicode objects using MBCS and returns the result as Python
+string object.  Error handling is ``strict''.  Returns \NULL{} in case
+an exception was raised by the codec.
+\end{cfuncdesc}
+
+% --- Methods & Slots ----------------------------------------------------
+
+\subsubsection{Methods and Slot Functions \label{unicodeMethodsAndSlots}}
+
+The following APIs are capable of handling Unicode objects and strings
+on input (we refer to them as strings in the descriptions) and return
+Unicode objects or integers as apporpriate.
+
+They all return \NULL{} or -1 in case an exception occurrs.
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_Concat}{PyObject *left,
+                                               PyObject *right}
+Concat two strings giving a new Unicode string.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_Split}{PyObject *s,
+                                              PyObject *sep,
+                                              int maxsplit}
+Split a string giving a list of Unicode strings.
+
+If sep is NULL, splitting will be done at all whitespace
+substrings. Otherwise, splits occur at the given separator.
+
+At most maxsplit splits will be done. If negative, no limit is set.
+
+Separators are not included in the resulting list.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_Splitlines}{PyObject *s,
+                                                   int maxsplit}
+Split a Unicode string at line breaks, returning a list of Unicode
+strings.  CRLF is considered to be one line break.  The Line break
+characters are not included in the resulting strings.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_Translate}{PyObject *str,
+                                                  PyObject *table,
+                                                  const char *errors}
+Translate a string by applying a character mapping table to it and
+return the resulting Unicode object.
+
+The mapping table must map Unicode ordinal integers to Unicode ordinal
+integers or None (causing deletion of the character).
+
+Mapping tables must only provide the __getitem__ interface,
+e.g. dictionaries or sequences. Unmapped character ordinals (ones
+which cause a LookupError) are left untouched and are copied as-is.
+
+\var{errors} has the usual meaning for codecs. It may be \NULL{}
+which indicates to use the default error handling.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_Join}{PyObject *separator,
+                                             PyObject *seq}
+Join a sequence of strings using the given separator and return
+the resulting Unicode string.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_Tailmatch}{PyObject *str,
+                                                  PyObject *substr,
+                                                  int start,
+                                                  int end,
+                                                  int direction}
+Return 1 if \var{substr} matches \var{str}[\var{start}:\var{end}] at
+the given tail end (\var{direction} == -1 means to do a prefix match,
+\var{direction} == 1 a suffix match), 0 otherwise.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_Find}{PyObject *str,
+                                                  PyObject *substr,
+                                                  int start,
+                                                  int end,
+                                                  int direction}
+Return the first position of \var{substr} in
+\var{str}[\var{start}:\var{end}] using the given \var{direction}
+(\var{direction} == 1 means to do a forward search,
+\var{direction} == -1 a backward search), 0 otherwise.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_Count}{PyObject *str,
+                                                  PyObject *substr,
+                                                  int start,
+                                                  int end}
+Count the number of occurrences of \var{substr} in
+\var{str}[\var{start}:\var{end}]
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_Replace}{PyObject *str,
+                                                PyObject *substr,
+                                                PyObject *replstr,
+                                                int maxcount}
+Replace at most \var{maxcount} occurrences of \var{substr} in
+\var{str} with \var{replstr} and return the resulting Unicode object.
+\var{maxcount} == -1 means: replace all occurrences.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyUnicode_Compare}{PyObject *left, PyObject *right}
+Compare two strings and return -1, 0, 1 for less than, equal,
+greater than resp.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyUnicode_Format}{PyObject *format,
+                                              PyObject *args}
+Returns a new string object from \var{format} and \var{args}; this is
+analogous to \code{\var{format} \%\ \var{args}}.  The
+\var{args} argument must be a tuple.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyUnicode_Contains}{PyObject *container,
+                                           PyObject *element}
+Checks whether \var{element} is contained in \var{container} and
+returns true or false accordingly.
+
+\var{element} has to coerce to a one element Unicode string. \code{-1} is
+returned in case of an error.
+\end{cfuncdesc}
+
+
+\subsection{Buffer Objects \label{bufferObjects}}
+\sectionauthor{Greg Stein}{gstein@lyra.org}
+
+\obindex{buffer}
+Python objects implemented in C can export a group of functions called
+the ``buffer\index{buffer interface} interface.''  These functions can
+be used by an object to expose its data in a raw, byte-oriented
+format. Clients of the object can use the buffer interface to access
+the object data directly, without needing to copy it first.
+
+Two examples of objects that support 
+the buffer interface are strings and arrays. The string object exposes