[Python-checkins] CVS: python/dist/src/Doc/api api.tex,1.67,1.68
Fred L. Drake
python-dev@python.org
Sat, 17 Jun 2000 22:21:23 -0700
Update of /cvsroot/python/python/dist/src/Doc/api
In directory slayer.i.sourceforge.net:/tmp/cvs-serv32618/Doc/api
Modified Files:
api.tex
Log Message:
Markup consistency nits.
Index: api.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/api/api.tex,v
retrieving revision 1.67
retrieving revision 1.68
diff -C2 -r1.67 -r1.68
*** api.tex 2000/06/16 21:04:15 1.67
--- api.tex 2000/06/18 05:21:21 1.68
***************
*** 1176,1184 ****
\end{cfuncdesc}
! \begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *}
! Load a frozen module. Return \code{1} for success, \code{0} if the
! module is not found, and \code{-1} with an exception set if the
! initialization failed. To access the imported module on a successful
! load, use \cfunction{PyImport_ImportModule()}.
(Note the misnomer --- this function would reload the module if it was
already imported.)
--- 1176,1184 ----
\end{cfuncdesc}
! \begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *name}
! Load a frozen module named \var{name}. Return \code{1} for success,
! \code{0} if the module is not found, and \code{-1} with an exception
! set if the initialization failed. To access the imported module on a
! successful load, use \cfunction{PyImport_ImportModule()}.
(Note the misnomer --- this function would reload the module if it was
already imported.)
***************
*** 2058,2062 ****
\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.
--- 2058,2062 ----
\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.
***************
*** 2103,2107 ****
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.
--- 2103,2106 ----
***************
*** 2139,2143 ****
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
--- 2138,2141 ----
***************
*** 2152,2156 ****
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
--- 2150,2153 ----
***************
*** 2164,2168 ****
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
--- 2161,2164 ----
***************
*** 2179,2183 ****
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
--- 2175,2178 ----
***************
*** 2188,2192 ****
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
--- 2183,2186 ----
***************
*** 2195,2199 ****
\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
--- 2189,2192 ----
***************
*** 2209,2213 ****
const char *errors,
int *byteorder}
-
Decodes \var{length} bytes from a UTF-16 encoded buffer string and
returns the corresponding Unicode object.
--- 2202,2205 ----
***************
*** 2239,2243 ****
const char *errors,
int byteorder}
-
Returns a Python string object holding the UTF-16 encoded value of the
Unicode data in \var{s}.
--- 2231,2234 ----
***************
*** 2277,2281 ****
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
--- 2268,2271 ----
***************
*** 2286,2290 ****
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
--- 2276,2279 ----
***************
*** 2293,2297 ****
\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
--- 2282,2285 ----
***************
*** 2306,2310 ****
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
--- 2294,2297 ----
***************
*** 2315,2319 ****
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
--- 2302,2305 ----
***************
*** 2322,2326 ****
\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
--- 2308,2311 ----
***************
*** 2336,2342 ****
\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
--- 2321,2326 ----
\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
***************
*** 2345,2351 ****
\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
--- 2329,2334 ----
\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
***************
*** 2354,2358 ****
\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
--- 2337,2340 ----
***************
*** 2362,2390 ****
% --- ASCII Codecs -------------------------------------------------------
! These are the ASCII codec APIs:
- Only 7-bit ASCII data is excepted. 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.
--- 2344,2368 ----
% --- 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.
***************
*** 2421,2425 ****
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{}
--- 2399,2402 ----
***************
*** 2431,2435 ****
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.
--- 2408,2411 ----
***************
*** 2439,2443 ****
\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
--- 2415,2418 ----
***************
*** 2452,2459 ****
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.
The \var{mapping} table must map Unicode ordinal integers to Unicode
--- 2427,2434 ----
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
***************
*** 2463,2486 ****
e.g. dictionaries or sequences. Unmapped character ordinals (ones
which cause a LookupError) are left untouched and are copied as-is.
-
- Returns \NULL{} in case an exception was raised by the codec.
\end{cfuncdesc}
% --- MBCS codecs for Windows --------------------------------------------
! These are the MBCS codec APIs. They are currently only available
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}
--- 2438,2456 ----
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}
***************
*** 2489,2493 ****
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
--- 2459,2462 ----
***************
*** 2496,2503 ****
\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}
--- 2465,2471 ----
\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}
***************
*** 2514,2518 ****
\begin{cfuncdesc}{PyObject*}{PyUnicode_Concat}{PyObject *left,
PyObject *right}
-
Concat two strings giving a new Unicode string.
\end{cfuncdesc}
--- 2482,2485 ----
***************
*** 2521,2525 ****
PyObject *sep,
int maxsplit}
-
Split a string giving a list of Unicode strings.
--- 2488,2491 ----
***************
*** 2534,2542 ****
\begin{cfuncdesc}{PyObject*}{PyUnicode_Splitlines}{PyObject *s,
int maxsplit}
!
! Dito, but split at line breaks.
!
! CRLF is considered to be one line break. Line breaks are not
! included in the resulting list.
\end{cfuncdesc}
--- 2500,2506 ----
\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}
***************
*** 2544,2548 ****
PyObject *table,
const char *errors}
-
Translate a string by applying a character mapping table to it and
return the resulting Unicode object.
--- 2508,2511 ----
***************
*** 2557,2566 ****
\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.
--- 2520,2527 ----
***************
*** 2572,2576 ****
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,
--- 2533,2536 ----
***************
*** 2583,2587 ****
int end,
int direction}
-
Return the first position of \var{substr} in
\var{str}[\var{start}:\var{end}] using the given \var{direction}
--- 2543,2546 ----
***************
*** 2594,2598 ****
int start,
int end}
-
Count the number of occurrences of \var{substr} in
\var{str}[\var{start}:\var{end}]
--- 2553,2556 ----
***************
*** 2603,2615 ****
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.
--- 2561,2570 ----
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.
***************
*** 2618,2633 ****
\begin{cfuncdesc}{PyObject*}{PyUnicode_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}{int}{PyUnicode_Contains}{PyObject *container,
PyObject *element}
-
Checks whether \var{element} is contained in \var{container} and
! returns 1/0 accordingly.
! \var{element} has to coerce to an one element Unicode string. -1 is
returned in case of an error.
\end{cfuncdesc}
--- 2573,2587 ----
\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}
***************
*** 2971,2975 ****
PyObject *val}
Inserts \var{value} into the dictionary using \var{key}
! as a key. \var{key} should be a \ctype{char *}. The key object is
created using \code{PyString_FromString(\var{key})}.
\ttindex{PyString_FromString()}
--- 2925,2929 ----
PyObject *val}
Inserts \var{value} into the dictionary using \var{key}
! as a key. \var{key} should be a \ctype{char*}. The key object is
created using \code{PyString_FromString(\var{key})}.
\ttindex{PyString_FromString()}
***************
*** 3448,3452 ****
\begin{cfuncdesc}{PyObject*}{PyCObject_FromVoidPtr}{void* cobj,
void (*destr)(void *)}
! Creates a \ctype{PyCObject} from the \code{void *} \var{cobj}. The
\var{destr} function will be called when the object is reclaimed, unless
it is \NULL.
--- 3402,3406 ----
\begin{cfuncdesc}{PyObject*}{PyCObject_FromVoidPtr}{void* cobj,
void (*destr)(void *)}
! Creates a \ctype{PyCObject} from the \code{void *}\var{cobj}. The
\var{destr} function will be called when the object is reclaimed, unless
it is \NULL.