Migrate to Sphinx 1.0 C language constructs.
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index 45c46aa..aae2b4a 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -17,75 +17,75 @@
Python:
-.. ctype:: Py_UNICODE
+.. c:type:: Py_UNICODE
This type represents the storage type which is used by Python internally as
basis for holding Unicode ordinals. Python's default builds use a 16-bit type
- for :ctype:`Py_UNICODE` and store Unicode values internally as UCS2. It is also
+ for :c:type:`Py_UNICODE` and store Unicode values internally as UCS2. It is also
possible to build a UCS4 version of Python (most recent Linux distributions come
with UCS4 builds of Python). These builds then use a 32-bit type for
- :ctype:`Py_UNICODE` and store Unicode data internally as UCS4. On platforms
- where :ctype:`wchar_t` is available and compatible with the chosen Python
- Unicode build variant, :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 either :ctype:`unsigned
- short` (UCS2) or :ctype:`unsigned long` (UCS4).
+ :c:type:`Py_UNICODE` and store Unicode data internally as UCS4. On platforms
+ where :c:type:`wchar_t` is available and compatible with the chosen Python
+ Unicode build variant, :c:type:`Py_UNICODE` is a typedef alias for
+ :c:type:`wchar_t` to enhance native platform compatibility. On all other
+ platforms, :c:type:`Py_UNICODE` is a typedef alias for either :c:type:`unsigned
+ short` (UCS2) or :c:type:`unsigned long` (UCS4).
Note that UCS2 and UCS4 Python builds are not binary compatible. Please keep
this in mind when writing extensions or interfaces.
-.. ctype:: PyUnicodeObject
+.. c:type:: PyUnicodeObject
- This subtype of :ctype:`PyObject` represents a Python Unicode object.
+ This subtype of :c:type:`PyObject` represents a Python Unicode object.
-.. cvar:: PyTypeObject PyUnicode_Type
+.. c:var:: PyTypeObject PyUnicode_Type
- This instance of :ctype:`PyTypeObject` represents the Python Unicode type. It
+ This instance of :c:type:`PyTypeObject` represents the Python Unicode type. It
is exposed to Python code as ``str``.
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:
-.. cfunction:: int PyUnicode_Check(PyObject *o)
+.. c:function:: int PyUnicode_Check(PyObject *o)
Return true if the object *o* is a Unicode object or an instance of a Unicode
subtype.
-.. cfunction:: int PyUnicode_CheckExact(PyObject *o)
+.. c:function:: int PyUnicode_CheckExact(PyObject *o)
Return true if the object *o* is a Unicode object, but not an instance of a
subtype.
-.. cfunction:: Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)
+.. c:function:: Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)
- Return the size of the object. *o* has to be a :ctype:`PyUnicodeObject` (not
+ Return the size of the object. *o* has to be a :c:type:`PyUnicodeObject` (not
checked).
-.. cfunction:: Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)
+.. c:function:: Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)
Return the size of the object's internal buffer in bytes. *o* has to be a
- :ctype:`PyUnicodeObject` (not checked).
+ :c:type:`PyUnicodeObject` (not checked).
-.. cfunction:: Py_UNICODE* PyUnicode_AS_UNICODE(PyObject *o)
+.. c:function:: Py_UNICODE* PyUnicode_AS_UNICODE(PyObject *o)
- Return a pointer to the internal :ctype:`Py_UNICODE` buffer of the object. *o*
- has to be a :ctype:`PyUnicodeObject` (not checked).
+ Return a pointer to the internal :c:type:`Py_UNICODE` buffer of the object. *o*
+ has to be a :c:type:`PyUnicodeObject` (not checked).
-.. cfunction:: const char* PyUnicode_AS_DATA(PyObject *o)
+.. c:function:: const char* PyUnicode_AS_DATA(PyObject *o)
Return a pointer to the internal buffer of the object. *o* has to be a
- :ctype:`PyUnicodeObject` (not checked).
+ :c:type:`PyUnicodeObject` (not checked).
-.. cfunction:: int PyUnicode_ClearFreeList()
+.. c:function:: int PyUnicode_ClearFreeList()
Clear the free list. Return the total number of freed items.
@@ -98,57 +98,57 @@
the Python configuration.
-.. cfunction:: int Py_UNICODE_ISSPACE(Py_UNICODE ch)
+.. c:function:: int Py_UNICODE_ISSPACE(Py_UNICODE ch)
Return 1 or 0 depending on whether *ch* is a whitespace character.
-.. cfunction:: int Py_UNICODE_ISLOWER(Py_UNICODE ch)
+.. c:function:: int Py_UNICODE_ISLOWER(Py_UNICODE ch)
Return 1 or 0 depending on whether *ch* is a lowercase character.
-.. cfunction:: int Py_UNICODE_ISUPPER(Py_UNICODE ch)
+.. c:function:: int Py_UNICODE_ISUPPER(Py_UNICODE ch)
Return 1 or 0 depending on whether *ch* is an uppercase character.
-.. cfunction:: int Py_UNICODE_ISTITLE(Py_UNICODE ch)
+.. c:function:: int Py_UNICODE_ISTITLE(Py_UNICODE ch)
Return 1 or 0 depending on whether *ch* is a titlecase character.
-.. cfunction:: int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch)
+.. c:function:: int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch)
Return 1 or 0 depending on whether *ch* is a linebreak character.
-.. cfunction:: int Py_UNICODE_ISDECIMAL(Py_UNICODE ch)
+.. c:function:: int Py_UNICODE_ISDECIMAL(Py_UNICODE ch)
Return 1 or 0 depending on whether *ch* is a decimal character.
-.. cfunction:: int Py_UNICODE_ISDIGIT(Py_UNICODE ch)
+.. c:function:: int Py_UNICODE_ISDIGIT(Py_UNICODE ch)
Return 1 or 0 depending on whether *ch* is a digit character.
-.. cfunction:: int Py_UNICODE_ISNUMERIC(Py_UNICODE ch)
+.. c:function:: int Py_UNICODE_ISNUMERIC(Py_UNICODE ch)
Return 1 or 0 depending on whether *ch* is a numeric character.
-.. cfunction:: int Py_UNICODE_ISALPHA(Py_UNICODE ch)
+.. c:function:: int Py_UNICODE_ISALPHA(Py_UNICODE ch)
Return 1 or 0 depending on whether *ch* is an alphabetic character.
-.. cfunction:: int Py_UNICODE_ISALNUM(Py_UNICODE ch)
+.. c:function:: int Py_UNICODE_ISALNUM(Py_UNICODE ch)
Return 1 or 0 depending on whether *ch* is an alphanumeric character.
-.. cfunction:: int Py_UNICODE_ISPRINTABLE(Py_UNICODE ch)
+.. c:function:: int Py_UNICODE_ISPRINTABLE(Py_UNICODE ch)
Return 1 or 0 depending on whether *ch* is a printable character.
Nonprintable characters are those characters defined in the Unicode character
@@ -162,34 +162,34 @@
These APIs can be used for fast direct character conversions:
-.. cfunction:: Py_UNICODE Py_UNICODE_TOLOWER(Py_UNICODE ch)
+.. c:function:: Py_UNICODE Py_UNICODE_TOLOWER(Py_UNICODE ch)
Return the character *ch* converted to lower case.
-.. cfunction:: Py_UNICODE Py_UNICODE_TOUPPER(Py_UNICODE ch)
+.. c:function:: Py_UNICODE Py_UNICODE_TOUPPER(Py_UNICODE ch)
Return the character *ch* converted to upper case.
-.. cfunction:: Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE ch)
+.. c:function:: Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE ch)
Return the character *ch* converted to title case.
-.. cfunction:: int Py_UNICODE_TODECIMAL(Py_UNICODE ch)
+.. c:function:: int Py_UNICODE_TODECIMAL(Py_UNICODE ch)
Return the character *ch* converted to a decimal positive integer. Return
``-1`` if this is not possible. This macro does not raise exceptions.
-.. cfunction:: int Py_UNICODE_TODIGIT(Py_UNICODE ch)
+.. c:function:: int Py_UNICODE_TODIGIT(Py_UNICODE ch)
Return the character *ch* converted to a single digit integer. Return ``-1`` if
this is not possible. This macro does not raise exceptions.
-.. cfunction:: double Py_UNICODE_TONUMERIC(Py_UNICODE ch)
+.. c:function:: double Py_UNICODE_TONUMERIC(Py_UNICODE ch)
Return the character *ch* converted to a double. Return ``-1.0`` if this is not
possible. This macro does not raise exceptions.
@@ -202,7 +202,7 @@
APIs:
-.. cfunction:: PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)
+.. c:function:: PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)
Create a Unicode Object from the Py_UNICODE buffer *u* of the given size. *u*
may be *NULL* which causes the contents to be undefined. It is the user's
@@ -212,7 +212,7 @@
is *NULL*.
-.. cfunction:: PyObject* PyUnicode_FromStringAndSize(const char *u, Py_ssize_t size)
+.. c:function:: PyObject* PyUnicode_FromStringAndSize(const char *u, Py_ssize_t size)
Create a Unicode Object from the char buffer *u*. The bytes will be interpreted
as being UTF-8 encoded. *u* may also be *NULL* which
@@ -222,15 +222,15 @@
the resulting Unicode object is only allowed when *u* is *NULL*.
-.. cfunction:: PyObject *PyUnicode_FromString(const char *u)
+.. c:function:: PyObject *PyUnicode_FromString(const char *u)
Create a Unicode object from an UTF-8 encoded null-terminated char buffer
*u*.
-.. cfunction:: PyObject* PyUnicode_FromFormat(const char *format, ...)
+.. c:function:: PyObject* PyUnicode_FromFormat(const char *format, ...)
- Take a C :cfunc:`printf`\ -style *format* string and a variable number of
+ Take a C :c:func:`printf`\ -style *format* string and a variable number of
arguments, calculate the size of the resulting Python unicode string and return
a string with the values formatted into it. The variable arguments must be C
types and must correspond exactly to the format characters in the *format*
@@ -305,10 +305,10 @@
| | | *NULL*). |
+-------------------+---------------------+--------------------------------+
| :attr:`%S` | PyObject\* | The result of calling |
- | | | :cfunc:`PyObject_Str`. |
+ | | | :c:func:`PyObject_Str`. |
+-------------------+---------------------+--------------------------------+
| :attr:`%R` | PyObject\* | The result of calling |
- | | | :cfunc:`PyObject_Repr`. |
+ | | | :c:func:`PyObject_Repr`. |
+-------------------+---------------------+--------------------------------+
An unrecognized format character causes all the rest of the format string to be
@@ -323,34 +323,34 @@
Support for ``"%lld"`` and ``"%llu"`` added.
-.. cfunction:: PyObject* PyUnicode_FromFormatV(const char *format, va_list vargs)
+.. c:function:: PyObject* PyUnicode_FromFormatV(const char *format, va_list vargs)
- Identical to :cfunc:`PyUnicode_FromFormat` except that it takes exactly two
+ Identical to :c:func:`PyUnicode_FromFormat` except that it takes exactly two
arguments.
-.. cfunction:: Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)
+.. c:function:: Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)
- Return a read-only pointer to the Unicode object's internal :ctype:`Py_UNICODE`
+ Return a read-only pointer to the Unicode object's internal :c:type:`Py_UNICODE`
buffer, *NULL* if *unicode* is not a Unicode object.
-.. cfunction:: Py_UNICODE* PyUnicode_AsUnicodeCopy(PyObject *unicode)
+.. c:function:: Py_UNICODE* PyUnicode_AsUnicodeCopy(PyObject *unicode)
Create a copy of a unicode string ending with a nul character. Return *NULL*
and raise a :exc:`MemoryError` exception on memory allocation failure,
- otherwise return a new allocated buffer (use :cfunc:`PyMem_Free` to free the
+ otherwise return a new allocated buffer (use :c:func:`PyMem_Free` to free the
buffer).
.. versionadded:: 3.2
-.. cfunction:: Py_ssize_t PyUnicode_GetSize(PyObject *unicode)
+.. c:function:: Py_ssize_t PyUnicode_GetSize(PyObject *unicode)
Return the length of the Unicode object.
-.. cfunction:: PyObject* PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)
+.. c:function:: 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.
@@ -367,73 +367,73 @@
decref'ing the returned objects.
-.. cfunction:: PyObject* PyUnicode_FromObject(PyObject *obj)
+.. c:function:: PyObject* PyUnicode_FromObject(PyObject *obj)
Shortcut for ``PyUnicode_FromEncodedObject(obj, NULL, "strict")`` which is used
throughout the interpreter whenever coercion to Unicode is needed.
-If the platform supports :ctype:`wchar_t` and provides a header file wchar.h,
+If the platform supports :c:type:`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`.
+Support is optimized if Python's own :c:type:`Py_UNICODE` type is identical to
+the system's :c:type:`wchar_t`.
File System Encoding
""""""""""""""""""""
To encode and decode file names and other environment strings,
-:cdata:`Py_FileSystemEncoding` should be used as the encoding, and
+:c:data:`Py_FileSystemEncoding` should be used as the encoding, and
``"surrogateescape"`` should be used as the error handler (:pep:`383`). To
encode file names during argument parsing, the ``"O&"`` converter should be
-used, passing :cfunc:`PyUnicode_FSConverter` as the conversion function:
+used, passing :c:func:`PyUnicode_FSConverter` as the conversion function:
-.. cfunction:: int PyUnicode_FSConverter(PyObject* obj, void* result)
+.. c:function:: int PyUnicode_FSConverter(PyObject* obj, void* result)
ParseTuple converter: encode :class:`str` objects to :class:`bytes` using
- :cfunc:`PyUnicode_EncodeFSDefault`; :class:`bytes` objects are output as-is.
- *result* must be a :ctype:`PyBytesObject*` which must be released when it is
+ :c:func:`PyUnicode_EncodeFSDefault`; :class:`bytes` objects are output as-is.
+ *result* must be a :c:type:`PyBytesObject*` which must be released when it is
no longer used.
.. versionadded:: 3.1
To decode file names during argument parsing, the ``"O&"`` converter should be
-used, passing :cfunc:`PyUnicode_FSDecoder` as the conversion function:
+used, passing :c:func:`PyUnicode_FSDecoder` as the conversion function:
-.. cfunction:: int PyUnicode_FSDecoder(PyObject* obj, void* result)
+.. c:function:: int PyUnicode_FSDecoder(PyObject* obj, void* result)
ParseTuple converter: decode :class:`bytes` objects to :class:`str` using
- :cfunc:`PyUnicode_DecodeFSDefaultAndSize`; :class:`str` objects are output
- as-is. *result* must be a :ctype:`PyUnicodeObject*` which must be released
+ :c:func:`PyUnicode_DecodeFSDefaultAndSize`; :class:`str` objects are output
+ as-is. *result* must be a :c:type:`PyUnicodeObject*` which must be released
when it is no longer used.
.. versionadded:: 3.2
-.. cfunction:: PyObject* PyUnicode_DecodeFSDefaultAndSize(const char *s, Py_ssize_t size)
+.. c:function:: PyObject* PyUnicode_DecodeFSDefaultAndSize(const char *s, Py_ssize_t size)
- Decode a null-terminated string using :cdata:`Py_FileSystemDefaultEncoding`
+ Decode a null-terminated string using :c:data:`Py_FileSystemDefaultEncoding`
and the ``"surrogateescape"`` error handler.
- If :cdata:`Py_FileSystemDefaultEncoding` is not set, fall back to UTF-8.
+ If :c:data:`Py_FileSystemDefaultEncoding` is not set, fall back to UTF-8.
- Use :cfunc:`PyUnicode_DecodeFSDefaultAndSize` if you know the string length.
+ Use :c:func:`PyUnicode_DecodeFSDefaultAndSize` if you know the string length.
-.. cfunction:: PyObject* PyUnicode_DecodeFSDefault(const char *s)
+.. c:function:: PyObject* PyUnicode_DecodeFSDefault(const char *s)
- Decode a string using :cdata:`Py_FileSystemDefaultEncoding` and
+ Decode a string using :c:data:`Py_FileSystemDefaultEncoding` and
the ``"surrogateescape"`` error handler.
- If :cdata:`Py_FileSystemDefaultEncoding` is not set, fall back to UTF-8.
+ If :c:data:`Py_FileSystemDefaultEncoding` is not set, fall back to UTF-8.
-.. cfunction:: PyObject* PyUnicode_EncodeFSDefault(PyObject *unicode)
+.. c:function:: PyObject* PyUnicode_EncodeFSDefault(PyObject *unicode)
- Encode a Unicode object to :cdata:`Py_FileSystemDefaultEncoding` with the
+ Encode a Unicode object to :c:data:`Py_FileSystemDefaultEncoding` with the
``'surrogateescape'`` error handler, and return :class:`bytes`.
- If :cdata:`Py_FileSystemDefaultEncoding` is not set, fall back to UTF-8.
+ If :c:data:`Py_FileSystemDefaultEncoding` is not set, fall back to UTF-8.
.. versionadded:: 3.2
@@ -443,33 +443,33 @@
wchar_t support for platforms which support it:
-.. cfunction:: PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)
+.. c:function:: PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)
- Create a Unicode object from the :ctype:`wchar_t` buffer *w* of the given size.
+ Create a Unicode object from the :c:type:`wchar_t` buffer *w* of the given size.
Passing -1 as the size indicates that the function must itself compute the length,
using wcslen.
Return *NULL* on failure.
-.. cfunction:: Py_ssize_t PyUnicode_AsWideChar(PyUnicodeObject *unicode, wchar_t *w, Py_ssize_t size)
+.. c:function:: Py_ssize_t PyUnicode_AsWideChar(PyUnicodeObject *unicode, wchar_t *w, Py_ssize_t size)
- Copy the Unicode object contents into the :ctype:`wchar_t` buffer *w*. At most
- *size* :ctype:`wchar_t` characters are copied (excluding a possibly trailing
- 0-termination character). Return the number of :ctype:`wchar_t` characters
- copied or -1 in case of an error. Note that the resulting :ctype:`wchar_t`
+ Copy the Unicode object contents into the :c:type:`wchar_t` buffer *w*. At most
+ *size* :c:type:`wchar_t` characters are copied (excluding a possibly trailing
+ 0-termination character). Return the number of :c:type:`wchar_t` characters
+ copied or -1 in case of an error. Note that the resulting :c:type:`wchar_t`
string may or may not be 0-terminated. It is the responsibility of the caller
- to make sure that the :ctype:`wchar_t` string is 0-terminated in case this is
+ to make sure that the :c:type:`wchar_t` string is 0-terminated in case this is
required by the application.
-.. cfunction:: wchar_t* PyUnicode_AsWideCharString(PyUnicodeObject *unicode, Py_ssize_t *size)
+.. c:function:: wchar_t* PyUnicode_AsWideCharString(PyUnicodeObject *unicode, Py_ssize_t *size)
Convert the Unicode object to a wide character string. The output string
always ends with a nul character. If *size* is not *NULL*, write the number
of wide characters (excluding the trailing 0-termination character) into
*\*size*.
- Returns a buffer allocated by :cfunc:`PyMem_Alloc` (use :cfunc:`PyMem_Free`
+ Returns a buffer allocated by :c:func:`PyMem_Alloc` (use :c:func:`PyMem_Free`
to free it) on success. On error, returns *NULL*, *\*size* is undefined and
raises a :exc:`MemoryError`.
@@ -490,8 +490,8 @@
Setting encoding to *NULL* causes the default encoding to be used
which is ASCII. The file system calls should use
-:cfunc:`PyUnicode_FSConverter` for encoding file names. This uses the
-variable :cdata:`Py_FileSystemDefaultEncoding` internally. This
+:c:func:`PyUnicode_FSConverter` for encoding file names. This uses the
+variable :c:data:`Py_FileSystemDefaultEncoding` internally. This
variable should be treated as read-only: On some systems, it will be a
pointer to a static string, on others, it will change at run-time
(such as when the application invokes setlocale).
@@ -510,7 +510,7 @@
These are the generic codec APIs:
-.. cfunction:: PyObject* PyUnicode_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
+.. c:function:: PyObject* PyUnicode_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
Create a Unicode object by decoding *size* bytes of the encoded string *s*.
*encoding* and *errors* have the same meaning as the parameters of the same name
@@ -519,16 +519,16 @@
the codec.
-.. cfunction:: PyObject* PyUnicode_Encode(const Py_UNICODE *s, Py_ssize_t size, const char *encoding, const char *errors)
+.. c:function:: PyObject* PyUnicode_Encode(const Py_UNICODE *s, Py_ssize_t size, const char *encoding, const char *errors)
- Encode the :ctype:`Py_UNICODE` buffer of the given size and return a Python
+ Encode the :c:type:`Py_UNICODE` buffer of the given size and return a Python
bytes object. *encoding* and *errors* have the same meaning as the
parameters of the same name in the Unicode :meth:`encode` method. The codec
to be used is looked up using the Python codec registry. Return *NULL* if an
exception was raised by the codec.
-.. cfunction:: PyObject* PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)
+.. c:function:: PyObject* PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)
Encode a Unicode object and return the result as Python bytes object.
*encoding* and *errors* have the same meaning as the parameters of the same
@@ -543,28 +543,28 @@
These are the UTF-8 codec APIs:
-.. cfunction:: PyObject* PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors)
+.. c:function:: PyObject* PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors)
Create a Unicode object by decoding *size* bytes of the UTF-8 encoded string
*s*. Return *NULL* if an exception was raised by the codec.
-.. cfunction:: PyObject* PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
+.. c:function:: PyObject* PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
- If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeUTF8`. If
+ If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF8`. If
*consumed* is not *NULL*, trailing incomplete UTF-8 byte sequences will not be
treated as an error. Those bytes will not be decoded and the number of bytes
that have been decoded will be stored in *consumed*.
-.. cfunction:: PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
+.. c:function:: PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
- Encode the :ctype:`Py_UNICODE` buffer of the given size using UTF-8 and
+ Encode the :c:type:`Py_UNICODE` buffer of the given size using UTF-8 and
return a Python bytes object. Return *NULL* if an exception was raised by
the codec.
-.. cfunction:: PyObject* PyUnicode_AsUTF8String(PyObject *unicode)
+.. c:function:: PyObject* PyUnicode_AsUTF8String(PyObject *unicode)
Encode a Unicode object using UTF-8 and return the result as Python bytes
object. Error handling is "strict". Return *NULL* if an exception was
@@ -577,7 +577,7 @@
These are the UTF-32 codec APIs:
-.. cfunction:: PyObject* PyUnicode_DecodeUTF32(const char *s, Py_ssize_t size, const char *errors, int *byteorder)
+.. c:function:: PyObject* PyUnicode_DecodeUTF32(const char *s, Py_ssize_t size, const char *errors, int *byteorder)
Decode *length* bytes from a UTF-32 encoded buffer string and return the
corresponding Unicode object. *errors* (if non-*NULL*) defines the error
@@ -605,16 +605,16 @@
Return *NULL* if an exception was raised by the codec.
-.. cfunction:: PyObject* PyUnicode_DecodeUTF32Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
+.. c:function:: PyObject* PyUnicode_DecodeUTF32Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
- If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeUTF32`. If
- *consumed* is not *NULL*, :cfunc:`PyUnicode_DecodeUTF32Stateful` will not treat
+ If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF32`. If
+ *consumed* is not *NULL*, :c:func:`PyUnicode_DecodeUTF32Stateful` will not treat
trailing incomplete UTF-32 byte sequences (such as a number of bytes not divisible
by four) as an error. Those bytes will not be decoded and the number of bytes
that have been decoded will be stored in *consumed*.
-.. cfunction:: PyObject* PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)
+.. c:function:: PyObject* PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)
Return a Python bytes object holding the UTF-32 encoded value of the Unicode
data in *s*. Output is written according to the following byte order::
@@ -632,7 +632,7 @@
Return *NULL* if an exception was raised by the codec.
-.. cfunction:: PyObject* PyUnicode_AsUTF32String(PyObject *unicode)
+.. c:function:: PyObject* PyUnicode_AsUTF32String(PyObject *unicode)
Return a Python byte string using the UTF-32 encoding in native byte
order. The string always starts with a BOM mark. Error handling is "strict".
@@ -645,7 +645,7 @@
These are the UTF-16 codec APIs:
-.. cfunction:: PyObject* PyUnicode_DecodeUTF16(const char *s, Py_ssize_t size, const char *errors, int *byteorder)
+.. c:function:: PyObject* PyUnicode_DecodeUTF16(const char *s, Py_ssize_t size, const char *errors, int *byteorder)
Decode *length* bytes from a UTF-16 encoded buffer string and return the
corresponding Unicode object. *errors* (if non-*NULL*) defines the error
@@ -672,16 +672,16 @@
Return *NULL* if an exception was raised by the codec.
-.. cfunction:: PyObject* PyUnicode_DecodeUTF16Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
+.. c:function:: PyObject* PyUnicode_DecodeUTF16Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
- If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeUTF16`. If
- *consumed* is not *NULL*, :cfunc:`PyUnicode_DecodeUTF16Stateful` will not treat
+ If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF16`. If
+ *consumed* is not *NULL*, :c:func:`PyUnicode_DecodeUTF16Stateful` will not treat
trailing incomplete UTF-16 byte sequences (such as an odd number of bytes or a
split surrogate pair) as an error. Those bytes will not be decoded and the
number of bytes that have been decoded will be stored in *consumed*.
-.. cfunction:: PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)
+.. c:function:: PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)
Return a Python bytes object holding the UTF-16 encoded value of the Unicode
data in *s*. Output is written according to the following byte order::
@@ -693,14 +693,14 @@
If byteorder is ``0``, the output string will always start with the Unicode BOM
mark (U+FEFF). In the other two modes, no BOM mark is prepended.
- If *Py_UNICODE_WIDE* is defined, a single :ctype:`Py_UNICODE` value may get
- represented as a surrogate pair. If it is not defined, each :ctype:`Py_UNICODE`
+ If *Py_UNICODE_WIDE* is defined, a single :c:type:`Py_UNICODE` value may get
+ represented as a surrogate pair. If it is not defined, each :c:type:`Py_UNICODE`
values is interpreted as an UCS-2 character.
Return *NULL* if an exception was raised by the codec.
-.. cfunction:: PyObject* PyUnicode_AsUTF16String(PyObject *unicode)
+.. c:function:: PyObject* PyUnicode_AsUTF16String(PyObject *unicode)
Return a Python byte string using the UTF-16 encoding in native byte
order. The string always starts with a BOM mark. Error handling is "strict".
@@ -713,23 +713,23 @@
These are the UTF-7 codec APIs:
-.. cfunction:: PyObject* PyUnicode_DecodeUTF7(const char *s, Py_ssize_t size, const char *errors)
+.. c:function:: PyObject* PyUnicode_DecodeUTF7(const char *s, Py_ssize_t size, const char *errors)
Create a Unicode object by decoding *size* bytes of the UTF-7 encoded string
*s*. Return *NULL* if an exception was raised by the codec.
-.. cfunction:: PyObject* PyUnicode_DecodeUTF7Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
+.. c:function:: PyObject* PyUnicode_DecodeUTF7Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
- If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeUTF7`. If
+ If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF7`. If
*consumed* is not *NULL*, trailing incomplete UTF-7 base-64 sections will not
be treated as an error. Those bytes will not be decoded and the number of
bytes that have been decoded will be stored in *consumed*.
-.. cfunction:: PyObject* PyUnicode_EncodeUTF7(const Py_UNICODE *s, Py_ssize_t size, int base64SetO, int base64WhiteSpace, const char *errors)
+.. c:function:: PyObject* PyUnicode_EncodeUTF7(const Py_UNICODE *s, Py_ssize_t size, int base64SetO, int base64WhiteSpace, const char *errors)
- Encode the :ctype:`Py_UNICODE` buffer of the given size using UTF-7 and
+ Encode the :c:type:`Py_UNICODE` buffer of the given size using UTF-7 and
return a Python bytes object. Return *NULL* if an exception was raised by
the codec.
@@ -745,20 +745,20 @@
These are the "Unicode Escape" codec APIs:
-.. cfunction:: PyObject* PyUnicode_DecodeUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)
+.. c:function:: PyObject* PyUnicode_DecodeUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)
Create a Unicode object by decoding *size* bytes of the Unicode-Escape encoded
string *s*. Return *NULL* if an exception was raised by the codec.
-.. cfunction:: PyObject* PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)
+.. c:function:: PyObject* PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)
- Encode the :ctype:`Py_UNICODE` buffer of the given size using Unicode-Escape and
+ Encode the :c:type:`Py_UNICODE` buffer of the given size using Unicode-Escape and
return a Python string object. Return *NULL* if an exception was raised by the
codec.
-.. cfunction:: PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode)
+.. c:function:: PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode)
Encode a Unicode object using Unicode-Escape and return the result as Python
string object. Error handling is "strict". Return *NULL* if an exception was
@@ -771,20 +771,20 @@
These are the "Raw Unicode Escape" codec APIs:
-.. cfunction:: PyObject* PyUnicode_DecodeRawUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)
+.. c:function:: PyObject* PyUnicode_DecodeRawUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)
Create a Unicode object by decoding *size* bytes of the Raw-Unicode-Escape
encoded string *s*. Return *NULL* if an exception was raised by the codec.
-.. cfunction:: PyObject* PyUnicode_EncodeRawUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
+.. c:function:: PyObject* PyUnicode_EncodeRawUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
- Encode the :ctype:`Py_UNICODE` buffer of the given size using Raw-Unicode-Escape
+ Encode the :c:type:`Py_UNICODE` buffer of the given size using Raw-Unicode-Escape
and return a Python string object. Return *NULL* if an exception was raised by
the codec.
-.. cfunction:: PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)
+.. c:function:: PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)
Encode a Unicode object using Raw-Unicode-Escape and return the result as
Python string object. Error handling is "strict". Return *NULL* if an exception
@@ -798,20 +798,20 @@
ordinals and only these are accepted by the codecs during encoding.
-.. cfunction:: PyObject* PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors)
+.. c:function:: PyObject* PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors)
Create a Unicode object by decoding *size* bytes of the Latin-1 encoded string
*s*. Return *NULL* if an exception was raised by the codec.
-.. cfunction:: PyObject* PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
+.. c:function:: PyObject* PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
- Encode the :ctype:`Py_UNICODE` buffer of the given size using Latin-1 and
+ Encode the :c:type:`Py_UNICODE` buffer of the given size using Latin-1 and
return a Python bytes object. Return *NULL* if an exception was raised by
the codec.
-.. cfunction:: PyObject* PyUnicode_AsLatin1String(PyObject *unicode)
+.. c:function:: PyObject* PyUnicode_AsLatin1String(PyObject *unicode)
Encode a Unicode object using Latin-1 and return the result as Python bytes
object. Error handling is "strict". Return *NULL* if an exception was
@@ -825,20 +825,20 @@
codes generate errors.
-.. cfunction:: PyObject* PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors)
+.. c:function:: PyObject* PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors)
Create a Unicode object by decoding *size* bytes of the ASCII encoded string
*s*. Return *NULL* if an exception was raised by the codec.
-.. cfunction:: PyObject* PyUnicode_EncodeASCII(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
+.. c:function:: PyObject* PyUnicode_EncodeASCII(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
- Encode the :ctype:`Py_UNICODE` buffer of the given size using ASCII and
+ Encode the :c:type:`Py_UNICODE` buffer of the given size using ASCII and
return a Python bytes object. Return *NULL* if an exception was raised by
the codec.
-.. cfunction:: PyObject* PyUnicode_AsASCIIString(PyObject *unicode)
+.. c:function:: PyObject* PyUnicode_AsASCIIString(PyObject *unicode)
Encode a Unicode object using ASCII and return the result as Python bytes
object. Error handling is "strict". Return *NULL* if an exception was
@@ -872,7 +872,7 @@
characters to different code points.
-.. cfunction:: PyObject* PyUnicode_DecodeCharmap(const char *s, Py_ssize_t size, PyObject *mapping, const char *errors)
+.. c:function:: PyObject* PyUnicode_DecodeCharmap(const char *s, Py_ssize_t size, PyObject *mapping, const char *errors)
Create a Unicode object by decoding *size* bytes of the encoded string *s* using
the given *mapping* object. Return *NULL* if an exception was raised by the
@@ -882,14 +882,14 @@
treated as "undefined mapping".
-.. cfunction:: PyObject* PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)
+.. c:function:: PyObject* PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)
- Encode the :ctype:`Py_UNICODE` buffer of the given size using the given
+ Encode the :c:type:`Py_UNICODE` buffer of the given size using the given
*mapping* object and return a Python string object. Return *NULL* if an
exception was raised by the codec.
-.. cfunction:: PyObject* PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)
+.. c:function:: PyObject* PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)
Encode a Unicode object using the given *mapping* object and return the result
as Python string object. Error handling is "strict". Return *NULL* if an
@@ -898,9 +898,9 @@
The following codec API is special in that maps Unicode to Unicode.
-.. cfunction:: PyObject* PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *table, const char *errors)
+.. c:function:: PyObject* PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *table, const char *errors)
- Translate a :ctype:`Py_UNICODE` buffer of the given length by applying a
+ Translate a :c:type:`Py_UNICODE` buffer of the given length by applying a
character mapping *table* to it and return the resulting Unicode object. Return
*NULL* when an exception was raised by the codec.
@@ -922,28 +922,28 @@
"""""""""""""""""""""""
-.. cfunction:: PyObject* PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors)
+.. c:function:: PyObject* PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors)
Create a Unicode object by decoding *size* bytes of the MBCS encoded string *s*.
Return *NULL* if an exception was raised by the codec.
-.. cfunction:: PyObject* PyUnicode_DecodeMBCSStateful(const char *s, int size, const char *errors, int *consumed)
+.. c:function:: PyObject* PyUnicode_DecodeMBCSStateful(const char *s, int size, const char *errors, int *consumed)
- If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeMBCS`. If
- *consumed* is not *NULL*, :cfunc:`PyUnicode_DecodeMBCSStateful` will not decode
+ If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeMBCS`. If
+ *consumed* is not *NULL*, :c:func:`PyUnicode_DecodeMBCSStateful` will not decode
trailing lead byte and the number of bytes that have been decoded will be stored
in *consumed*.
-.. cfunction:: PyObject* PyUnicode_EncodeMBCS(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
+.. c:function:: PyObject* PyUnicode_EncodeMBCS(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
- Encode the :ctype:`Py_UNICODE` buffer of the given size using MBCS and return
+ Encode the :c:type:`Py_UNICODE` buffer of the given size using MBCS and return
a Python bytes object. Return *NULL* if an exception was raised by the
codec.
-.. cfunction:: PyObject* PyUnicode_AsMBCSString(PyObject *unicode)
+.. c:function:: PyObject* PyUnicode_AsMBCSString(PyObject *unicode)
Encode a Unicode object using MBCS and return the result as Python bytes
object. Error handling is "strict". Return *NULL* if an exception was
@@ -966,12 +966,12 @@
They all return *NULL* or ``-1`` if an exception occurs.
-.. cfunction:: PyObject* PyUnicode_Concat(PyObject *left, PyObject *right)
+.. c:function:: PyObject* PyUnicode_Concat(PyObject *left, PyObject *right)
Concat two strings giving a new Unicode string.
-.. cfunction:: PyObject* PyUnicode_Split(PyObject *s, PyObject *sep, Py_ssize_t maxsplit)
+.. c:function:: PyObject* PyUnicode_Split(PyObject *s, PyObject *sep, Py_ssize_t 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
@@ -979,14 +979,14 @@
set. Separators are not included in the resulting list.
-.. cfunction:: PyObject* PyUnicode_Splitlines(PyObject *s, int keepend)
+.. c:function:: PyObject* PyUnicode_Splitlines(PyObject *s, int keepend)
Split a Unicode string at line breaks, returning a list of Unicode strings.
CRLF is considered to be one line break. If *keepend* is 0, the Line break
characters are not included in the resulting strings.
-.. cfunction:: PyObject* PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors)
+.. c:function:: 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.
@@ -1002,20 +1002,20 @@
use the default error handling.
-.. cfunction:: PyObject* PyUnicode_Join(PyObject *separator, PyObject *seq)
+.. c:function:: PyObject* PyUnicode_Join(PyObject *separator, PyObject *seq)
Join a sequence of strings using the given separator and return the resulting
Unicode string.
-.. cfunction:: int PyUnicode_Tailmatch(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
+.. c:function:: int PyUnicode_Tailmatch(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
Return 1 if *substr* matches *str*[*start*:*end*] at the given tail end
(*direction* == -1 means to do a prefix match, *direction* == 1 a suffix match),
0 otherwise. Return ``-1`` if an error occurred.
-.. cfunction:: Py_ssize_t PyUnicode_Find(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
+.. c:function:: Py_ssize_t PyUnicode_Find(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
Return the first position of *substr* in *str*[*start*:*end*] using the given
*direction* (*direction* == 1 means to do a forward search, *direction* == -1 a
@@ -1024,32 +1024,32 @@
occurred and an exception has been set.
-.. cfunction:: Py_ssize_t PyUnicode_Count(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end)
+.. c:function:: Py_ssize_t PyUnicode_Count(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end)
Return the number of non-overlapping occurrences of *substr* in
``str[start:end]``. Return ``-1`` if an error occurred.
-.. cfunction:: PyObject* PyUnicode_Replace(PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)
+.. c:function:: PyObject* PyUnicode_Replace(PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)
Replace at most *maxcount* occurrences of *substr* in *str* with *replstr* and
return the resulting Unicode object. *maxcount* == -1 means replace all
occurrences.
-.. cfunction:: int PyUnicode_Compare(PyObject *left, PyObject *right)
+.. c:function:: int PyUnicode_Compare(PyObject *left, PyObject *right)
Compare two strings and return -1, 0, 1 for less than, equal, and greater than,
respectively.
-.. cfunction:: int PyUnicode_CompareWithASCIIString(PyObject *uni, char *string)
+.. c:function:: int PyUnicode_CompareWithASCIIString(PyObject *uni, char *string)
Compare a unicode object, *uni*, with *string* and return -1, 0, 1 for less
than, equal, and greater than, respectively.
-.. cfunction:: int PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)
+.. c:function:: int PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)
Rich compare two unicode strings and return one of the following:
@@ -1065,13 +1065,13 @@
:const:`Py_NE`, :const:`Py_LT`, and :const:`Py_LE`.
-.. cfunction:: PyObject* PyUnicode_Format(PyObject *format, PyObject *args)
+.. c:function:: PyObject* PyUnicode_Format(PyObject *format, PyObject *args)
Return a new string object from *format* and *args*; this is analogous to
``format % args``. The *args* argument must be a tuple.
-.. cfunction:: int PyUnicode_Contains(PyObject *container, PyObject *element)
+.. c:function:: int PyUnicode_Contains(PyObject *container, PyObject *element)
Check whether *element* is contained in *container* and return true or false
accordingly.
@@ -1080,7 +1080,7 @@
there was an error.
-.. cfunction:: void PyUnicode_InternInPlace(PyObject **string)
+.. c:function:: void PyUnicode_InternInPlace(PyObject **string)
Intern the argument *\*string* in place. The argument must be the address of a
pointer variable pointing to a Python unicode string object. If there is an
@@ -1093,10 +1093,10 @@
if and only if you owned it before the call.)
-.. cfunction:: PyObject* PyUnicode_InternFromString(const char *v)
+.. c:function:: PyObject* PyUnicode_InternFromString(const char *v)
- A combination of :cfunc:`PyUnicode_FromString` and
- :cfunc:`PyUnicode_InternInPlace`, returning either a new unicode string object
+ A combination of :c:func:`PyUnicode_FromString` and
+ :c:func:`PyUnicode_InternInPlace`, returning either a new unicode string object
that has been interned, or a new ("owned") reference to an earlier interned
string object with the same value.