update to new C roles and directives
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index 8308304..73f6fe6 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -18,39 +18,39 @@
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 ``unicode`` and ``types.UnicodeType``.
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.
@@ -59,7 +59,7 @@
Allowed subtypes to be accepted.
-.. 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.
@@ -67,39 +67,39 @@
.. versionadded:: 2.2
-.. 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).
.. versionchanged:: 2.5
- This function returned an :ctype:`int` type. This might require changes
+ This function returned an :c:type:`int` type. This might require changes
in your code for properly supporting 64-bit systems.
-.. 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).
.. versionchanged:: 2.5
- This function returned an :ctype:`int` type. This might require changes
+ This function returned an :c:type:`int` type. This might require changes
in your code for properly supporting 64-bit systems.
-.. 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.
@@ -114,86 +114,86 @@
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.
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.
@@ -206,7 +206,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
@@ -216,11 +216,11 @@
is *NULL*.
.. versionchanged:: 2.5
- This function used an :ctype:`int` type for *size*. This might require
+ This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
-.. 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
@@ -232,7 +232,7 @@
.. versionadded:: 2.6
-.. 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*.
@@ -240,9 +240,9 @@
.. versionadded:: 2.6
-.. 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*
@@ -317,7 +317,7 @@
.. versionadded:: 2.6
-.. cfunction:: PyObject* PyUnicode_FromFormatV(const char *format, va_list vargs)
+.. c:function:: PyObject* PyUnicode_FromFormatV(const char *format, va_list vargs)
Identical to :func:`PyUnicode_FromFormat` except that it takes exactly two
arguments.
@@ -325,25 +325,25 @@
.. versionadded:: 2.6
-.. 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` buffer, *NULL* if *unicode* is not a Unicode object.
- Note that the resulting :ctype:`Py_UNICODE*` string may contain embedded
+ :c:type:`Py_UNICODE` buffer, *NULL* if *unicode* is not a Unicode object.
+ Note that the resulting :c:type:`Py_UNICODE*` string may contain embedded
null characters, which would cause the string to be truncated when used in
most C functions.
-.. cfunction:: Py_ssize_t PyUnicode_GetSize(PyObject *unicode)
+.. c:function:: Py_ssize_t PyUnicode_GetSize(PyObject *unicode)
Return the length of the Unicode object.
.. versionchanged:: 2.5
- This function returned an :ctype:`int` type. This might require changes
+ This function returned an :c:type:`int` type. This might require changes
in your code for properly supporting 64-bit systems.
-.. 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.
@@ -360,46 +360,46 @@
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`.
wchar_t Support
"""""""""""""""
-:ctype:`wchar_t` support for platforms which support it:
+:c:type:`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*.
Return *NULL* on failure.
.. versionchanged:: 2.5
- This function used an :ctype:`int` type for *size*. This might require
+ This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
-.. 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
- required by the application. Also, note that the :ctype:`wchar_t*` string
+ to make sure that the :c:type:`wchar_t` string is 0-terminated in case this is
+ required by the application. Also, note that the :c:type:`wchar_t*` string
might contain null characters, which would cause the string to be truncated
when used with most C functions.
.. versionchanged:: 2.5
- This function returned an :ctype:`int` type and used an :ctype:`int`
+ This function returned an :c:type:`int` type and used an :c:type:`int`
type for *size*. This might require changes in your code for properly
supporting 64-bit systems.
@@ -417,7 +417,7 @@
object constructor.
Setting encoding to *NULL* causes the default encoding to be used which is
-ASCII. The file system calls should use :cdata:`Py_FileSystemDefaultEncoding`
+ASCII. The file system calls should use :c:data:`Py_FileSystemDefaultEncoding`
as the encoding for file names. 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).
@@ -436,7 +436,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
@@ -445,24 +445,24 @@
the codec.
.. versionchanged:: 2.5
- This function used an :ctype:`int` type for *size*. This might require
+ This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
-.. 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 *s* of the given *size* and return a Python
+ Encode the :c:type:`Py_UNICODE` buffer *s* of the given *size* and return a Python
string 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.
.. versionchanged:: 2.5
- This function used an :ctype:`int` type for *size*. This might require
+ This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
-.. 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 string object.
*encoding* and *errors* have the same meaning as the parameters of the same name
@@ -477,19 +477,19 @@
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.
.. versionchanged:: 2.5
- This function used an :ctype:`int` type for *size*. This might require
+ This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
-.. 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*.
@@ -497,21 +497,21 @@
.. versionadded:: 2.4
.. versionchanged:: 2.5
- This function used an :ctype:`int` type for *size*. This might require
+ This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
-.. 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 *s* of the given *size* using UTF-8 and return a
+ Encode the :c:type:`Py_UNICODE` buffer *s* of the given *size* using UTF-8 and return a
Python string object. Return *NULL* if an exception was raised by the codec.
.. versionchanged:: 2.5
- This function used an :ctype:`int` type for *size*. This might require
+ This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
-.. 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 string
object. Error handling is "strict". Return *NULL* if an exception was raised
@@ -524,7 +524,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 *size* bytes from a UTF-32 encoded buffer string and return the
corresponding Unicode object. *errors* (if non-*NULL*) defines the error
@@ -554,10 +554,10 @@
.. versionadded:: 2.6
-.. 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*.
@@ -565,7 +565,7 @@
.. versionadded:: 2.6
-.. 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::
@@ -585,7 +585,7 @@
.. versionadded:: 2.6
-.. cfunction:: PyObject* PyUnicode_AsUTF32String(PyObject *unicode)
+.. c:function:: PyObject* PyUnicode_AsUTF32String(PyObject *unicode)
Return a Python string using the UTF-32 encoding in native byte order. The
string always starts with a BOM mark. Error handling is "strict". Return
@@ -600,7 +600,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 *size* bytes from a UTF-16 encoded buffer string and return the
corresponding Unicode object. *errors* (if non-*NULL*) defines the error
@@ -627,14 +627,14 @@
Return *NULL* if an exception was raised by the codec.
.. versionchanged:: 2.5
- This function used an :ctype:`int` type for *size*. This might require
+ This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
-.. 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*.
@@ -642,12 +642,12 @@
.. versionadded:: 2.4
.. versionchanged:: 2.5
- This function used an :ctype:`int` type for *size* and an :ctype:`int *`
+ This function used an :c:type:`int` type for *size* and an :c:type:`int *`
type for *consumed*. This might require changes in your code for
properly supporting 64-bit systems.
-.. 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 string object holding the UTF-16 encoded value of the Unicode
data in *s*. Output is written according to the following byte order::
@@ -659,18 +659,18 @@
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.
.. versionchanged:: 2.5
- This function used an :ctype:`int` type for *size*. This might require
+ This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
-.. cfunction:: PyObject* PyUnicode_AsUTF16String(PyObject *unicode)
+.. c:function:: PyObject* PyUnicode_AsUTF16String(PyObject *unicode)
Return a Python string using the UTF-16 encoding in native byte order. The
string always starts with a BOM mark. Error handling is "strict". Return
@@ -683,23 +683,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.
@@ -715,28 +715,28 @@
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.
.. versionchanged:: 2.5
- This function used an :ctype:`int` type for *size*. This might require
+ This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
-.. 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.
.. versionchanged:: 2.5
- This function used an :ctype:`int` type for *size*. This might require
+ This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
-.. 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
@@ -749,28 +749,28 @@
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.
.. versionchanged:: 2.5
- This function used an :ctype:`int` type for *size*. This might require
+ This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
-.. 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.
.. versionchanged:: 2.5
- This function used an :ctype:`int` type for *size*. This might require
+ This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
-.. 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
@@ -784,27 +784,27 @@
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.
.. versionchanged:: 2.5
- This function used an :ctype:`int` type for *size*. This might require
+ This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
-.. 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 return
+ Encode the :c:type:`Py_UNICODE` buffer of the given *size* using Latin-1 and return
a Python string object. Return *NULL* if an exception was raised by the codec.
.. versionchanged:: 2.5
- This function used an :ctype:`int` type for *size*. This might require
+ This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
-.. 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 string
object. Error handling is "strict". Return *NULL* if an exception was raised
@@ -818,27 +818,27 @@
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.
.. versionchanged:: 2.5
- This function used an :ctype:`int` type for *size*. This might require
+ This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
-.. 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 return a
+ Encode the :c:type:`Py_UNICODE` buffer of the given *size* using ASCII and return a
Python string object. Return *NULL* if an exception was raised by the codec.
.. versionchanged:: 2.5
- This function used an :ctype:`int` type for *size*. This might require
+ This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
-.. 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 string
object. Error handling is "strict". Return *NULL* if an exception was raised
@@ -871,7 +871,7 @@
These are the mapping codec APIs:
-.. 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
@@ -884,22 +884,22 @@
Allowed unicode string as mapping argument.
.. versionchanged:: 2.5
- This function used an :ctype:`int` type for *size*. This might require
+ This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
-.. 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.
.. versionchanged:: 2.5
- This function used an :ctype:`int` type for *size*. This might require
+ This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
-.. 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
@@ -908,9 +908,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 *size* by applying a
+ Translate a :c:type:`Py_UNICODE` buffer of the given *size* 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,7 +922,7 @@
:exc:`LookupError`) are left untouched and are copied as-is.
.. versionchanged:: 2.5
- This function used an :ctype:`int` type for *size*. This might require
+ This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
@@ -935,37 +935,37 @@
the user settings on the machine running the codec.
-.. 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.
.. versionchanged:: 2.5
- This function used an :ctype:`int` type for *size*. This might require
+ This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
-.. 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*.
.. versionadded:: 2.5
-.. 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 a
+ Encode the :c:type:`Py_UNICODE` buffer of the given *size* using MBCS and return a
Python string object. Return *NULL* if an exception was raised by the codec.
.. versionchanged:: 2.5
- This function used an :ctype:`int` type for *size*. This might require
+ This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
-.. 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 string
object. Error handling is "strict". Return *NULL* if an exception was raised
@@ -987,12 +987,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
@@ -1000,18 +1000,18 @@
set. Separators are not included in the resulting list.
.. versionchanged:: 2.5
- This function used an :ctype:`int` type for *maxsplit*. This might require
+ This function used an :c:type:`int` type for *maxsplit*. This might require
changes in your code for properly supporting 64-bit systems.
-.. 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.
@@ -1027,25 +1027,25 @@
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.
.. versionchanged:: 2.5
- This function used an :ctype:`int` type for *start* and *end*. This
+ This function used an :c:type:`int` type for *start* and *end*. This
might require changes in your code for properly supporting 64-bit
systems.
-.. 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
@@ -1054,40 +1054,40 @@
occurred and an exception has been set.
.. versionchanged:: 2.5
- This function used an :ctype:`int` type for *start* and *end*. This
+ This function used an :c:type:`int` type for *start* and *end*. This
might require changes in your code for properly supporting 64-bit
systems.
-.. 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.
.. versionchanged:: 2.5
- This function returned an :ctype:`int` type and used an :ctype:`int`
+ This function returned an :c:type:`int` type and used an :c:type:`int`
type for *start* and *end*. This might require changes in your code for
properly supporting 64-bit systems.
-.. 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.
.. versionchanged:: 2.5
- This function used an :ctype:`int` type for *maxcount*. This might
+ This function used an :c:type:`int` type for *maxcount*. This might
require changes in your code for properly supporting 64-bit systems.
-.. 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_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:
@@ -1103,13 +1103,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.