diff -r 86a412584c02 Doc/c-api/unicode.rst --- a/Doc/c-api/unicode.rst Tue Dec 27 17:41:07 2016 +0200 +++ b/Doc/c-api/unicode.rst Tue Dec 27 21:01:25 2016 +0200 @@ -57,6 +57,8 @@ Python: This is a typedef of :c:type:`wchar_t`, which is a 16-bit type or 32-bit type depending on the platform. + *Not part of the limited API.* + .. versionchanged:: 3.3 In previous versions, this was a 16-bit type or a 32-bit type depending on whether you selected a "narrow" or "wide" Unicode version of Python at @@ -73,6 +75,8 @@ Python: .. versionadded:: 3.3 + *Not part of the limited API.* + .. c:var:: PyTypeObject PyUnicode_Type @@ -107,6 +111,8 @@ access internal read-only data of Unicod .. versionadded:: 3.3 + *Not part of the limited API.* + .. c:function:: Py_ssize_t PyUnicode_GET_LENGTH(PyObject *o) @@ -115,6 +121,8 @@ access internal read-only data of Unicod .. versionadded:: 3.3 + *Not part of the limited API.* + .. c:function:: Py_UCS1* PyUnicode_1BYTE_DATA(PyObject *o) Py_UCS2* PyUnicode_2BYTE_DATA(PyObject *o) @@ -128,6 +136,8 @@ access internal read-only data of Unicod .. versionadded:: 3.3 + *Not part of the limited API.* + .. c:macro:: PyUnicode_WCHAR_KIND PyUnicode_1BYTE_KIND @@ -138,6 +148,8 @@ access internal read-only data of Unicod .. versionadded:: 3.3 + *Not part of the limited API.* + .. c:function:: int PyUnicode_KIND(PyObject *o) @@ -149,6 +161,8 @@ access internal read-only data of Unicod .. versionadded:: 3.3 + *Not part of the limited API.* + .. c:function:: void* PyUnicode_DATA(PyObject *o) @@ -157,6 +171,8 @@ access internal read-only data of Unicod .. versionadded:: 3.3 + *Not part of the limited API.* + .. c:function:: void PyUnicode_WRITE(int kind, void *data, Py_ssize_t index, \ Py_UCS4 value) @@ -170,6 +186,8 @@ access internal read-only data of Unicod .. versionadded:: 3.3 + *Not part of the limited API.* + .. c:function:: Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index) @@ -178,6 +196,8 @@ access internal read-only data of Unicod .. versionadded:: 3.3 + *Not part of the limited API.* + .. c:function:: Py_UCS4 PyUnicode_READ_CHAR(PyObject *o, Py_ssize_t index) @@ -187,6 +207,8 @@ access internal read-only data of Unicod .. versionadded:: 3.3 + *Not part of the limited API.* + .. c:function:: PyUnicode_MAX_CHAR_VALUE(PyObject *o) @@ -196,6 +218,8 @@ access internal read-only data of Unicod .. versionadded:: 3.3 + *Not part of the limited API.* + .. c:function:: int PyUnicode_ClearFreeList() @@ -208,6 +232,8 @@ access internal read-only data of Unicod code units (this includes surrogate pairs as 2 units). *o* has to be a Unicode object (not checked). + *Not part of the limited API.* + .. deprecated-removed:: 3.3 4.0 Part of the old-style Unicode API, please migrate to using :c:func:`PyUnicode_GET_LENGTH`. @@ -218,6 +244,8 @@ access internal read-only data of Unicod Return the size of the deprecated :c:type:`Py_UNICODE` representation in bytes. *o* has to be a Unicode object (not checked). + *Not part of the limited API.* + .. deprecated-removed:: 3.3 4.0 Part of the old-style Unicode API, please migrate to using :c:func:`PyUnicode_GET_LENGTH`. @@ -240,6 +268,8 @@ access internal read-only data of Unicod code to use the new :c:func:`PyUnicode_nBYTE_DATA` macros or use :c:func:`PyUnicode_WRITE` or :c:func:`PyUnicode_READ`. + *Not part of the limited API.* + .. deprecated-removed:: 3.3 4.0 Part of the old-style Unicode API, please migrate to using the :c:func:`PyUnicode_nBYTE_DATA` family of macros. @@ -257,51 +287,71 @@ the Python configuration. Return ``1`` or ``0`` depending on whether *ch* is a whitespace character. + *Not part of the limited API.* + .. c:function:: int Py_UNICODE_ISLOWER(Py_UNICODE ch) Return ``1`` or ``0`` depending on whether *ch* is a lowercase character. + *Not part of the limited API.* + .. c:function:: int Py_UNICODE_ISUPPER(Py_UNICODE ch) Return ``1`` or ``0`` depending on whether *ch* is an uppercase character. + *Not part of the limited API.* + .. c:function:: int Py_UNICODE_ISTITLE(Py_UNICODE ch) Return ``1`` or ``0`` depending on whether *ch* is a titlecase character. + *Not part of the limited API.* + .. c:function:: int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch) Return ``1`` or ``0`` depending on whether *ch* is a linebreak character. + *Not part of the limited API.* + .. c:function:: int Py_UNICODE_ISDECIMAL(Py_UNICODE ch) Return ``1`` or ``0`` depending on whether *ch* is a decimal character. + *Not part of the limited API.* + .. c:function:: int Py_UNICODE_ISDIGIT(Py_UNICODE ch) Return ``1`` or ``0`` depending on whether *ch* is a digit character. + *Not part of the limited API.* + .. c:function:: int Py_UNICODE_ISNUMERIC(Py_UNICODE ch) Return ``1`` or ``0`` depending on whether *ch* is a numeric character. + *Not part of the limited API.* + .. c:function:: int Py_UNICODE_ISALPHA(Py_UNICODE ch) Return ``1`` or ``0`` depending on whether *ch* is an alphabetic character. + *Not part of the limited API.* + .. c:function:: int Py_UNICODE_ISALNUM(Py_UNICODE ch) Return ``1`` or ``0`` depending on whether *ch* is an alphanumeric character. + *Not part of the limited API.* + .. c:function:: int Py_UNICODE_ISPRINTABLE(Py_UNICODE ch) @@ -313,6 +363,8 @@ the Python configuration. It has no bearing on the handling of strings written to :data:`sys.stdout` or :data:`sys.stderr`.) + *Not part of the limited API.* + These APIs can be used for fast direct character conversions: @@ -321,6 +373,8 @@ These APIs can be used for fast direct c Return the character *ch* converted to lower case. + *Not part of the limited API.* + .. deprecated:: 3.3 This function uses simple case mappings. @@ -329,6 +383,8 @@ These APIs can be used for fast direct c Return the character *ch* converted to upper case. + *Not part of the limited API.* + .. deprecated:: 3.3 This function uses simple case mappings. @@ -337,6 +393,8 @@ These APIs can be used for fast direct c Return the character *ch* converted to title case. + *Not part of the limited API.* + .. deprecated:: 3.3 This function uses simple case mappings. @@ -346,18 +404,24 @@ These APIs can be used for fast direct c Return the character *ch* converted to a decimal positive integer. Return ``-1`` if this is not possible. This macro does not raise exceptions. + *Not part of the limited API.* + .. 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. + *Not part of the limited API.* + .. 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. + *Not part of the limited API.* + These APIs can be used to work with surrogates: @@ -365,20 +429,28 @@ These APIs can be used to work with surr Check if *ch* is a surrogate (``0xD800 <= ch <= 0xDFFF``). + *Not part of the limited API.* + .. c:macro:: Py_UNICODE_IS_HIGH_SURROGATE(ch) Check if *ch* is a high surrogate (``0xD800 <= ch <= 0xDBFF``). + *Not part of the limited API.* + .. c:macro:: Py_UNICODE_IS_LOW_SURROGATE(ch) Check if *ch* is a low surrogate (``0xDC00 <= ch <= 0xDFFF``). + *Not part of the limited API.* + .. c:macro:: Py_UNICODE_JOIN_SURROGATES(high, low) Join two surrogate characters and return a single Py_UCS4 value. *high* and *low* are respectively the leading and trailing surrogates in a surrogate pair. + *Not part of the limited API.* + Creating and accessing Unicode strings """""""""""""""""""""""""""""""""""""" @@ -395,6 +467,8 @@ APIs: This is the recommended way to allocate a new Unicode object. Objects created using this function are not resizable. + *Not part of the limited API.* + .. versionadded:: 3.3 @@ -406,6 +480,8 @@ APIs: :c:func:`PyUnicode_KIND`). The *buffer* must point to an array of *size* units of 1, 2 or 4 bytes per character, as given by the kind. + *Not part of the limited API.* + .. versionadded:: 3.3 @@ -583,6 +659,8 @@ APIs: possible. Returns ``-1`` and sets an exception on error, otherwise returns the number of copied characters. + *Not part of the limited API.* + .. versionadded:: 3.3 @@ -598,6 +676,8 @@ APIs: Return the number of written character, or return ``-1`` and raise an exception on error. + *Not part of the limited API.* + .. versionadded:: 3.3 @@ -682,6 +762,8 @@ 3.x, but need to be aware that their use Please migrate to using :c:func:`PyUnicode_FromKindAndData`, :c:func:`PyUnicode_FromWideChar` or :c:func:`PyUnicode_New`. + *Not part of the limited API.* + .. c:function:: Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode) @@ -697,6 +779,8 @@ 3.x, but need to be aware that their use :c:func:`PyUnicode_AsWideChar`, :c:func:`PyUnicode_ReadChar` or similar new APIs. + *Not part of the limited API.* + .. c:function:: PyObject* PyUnicode_TransformDecimalToASCII(Py_UNICODE *s, Py_ssize_t size) @@ -704,6 +788,8 @@ 3.x, but need to be aware that their use :c:type:`Py_UNICODE` buffer of the given *size* by ASCII digits 0--9 according to their decimal value. Return *NULL* if an exception occurs. + *Not part of the limited API.* + .. c:function:: Py_UNICODE* PyUnicode_AsUnicodeAndSize(PyObject *unicode, Py_ssize_t *size) @@ -715,6 +801,8 @@ 3.x, but need to be aware that their use .. versionadded:: 3.3 + *Not part of the limited API.* + .. c:function:: Py_UNICODE* PyUnicode_AsUnicodeCopy(PyObject *unicode) @@ -727,6 +815,8 @@ 3.x, but need to be aware that their use .. versionadded:: 3.2 + *Not part of the limited API.* + Please migrate to using :c:func:`PyUnicode_AsUCS4Copy` or similar new APIs. @@ -1025,6 +1115,8 @@ These are the generic codec APIs: to be used is looked up using the Python codec registry. Return *NULL* if an exception was raised by the codec. + *Not part of the limited API.* + .. deprecated-removed:: 3.3 4.0 Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using :c:func:`PyUnicode_AsEncodedString`. @@ -1075,6 +1167,8 @@ These are the UTF-8 codec APIs: .. versionadded:: 3.3 + *Not part of the limited API.* + .. c:function:: char* PyUnicode_AsUTF8(PyObject *unicode) @@ -1082,6 +1176,8 @@ These are the UTF-8 codec APIs: .. versionadded:: 3.3 + *Not part of the limited API.* + .. c:function:: PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors) @@ -1089,6 +1185,8 @@ These are the UTF-8 codec APIs: return a Python bytes object. Return *NULL* if an exception was raised by the codec. + *Not part of the limited API.* + .. deprecated-removed:: 3.3 4.0 Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using :c:func:`PyUnicode_AsUTF8String`, :c:func:`PyUnicode_AsUTF8AndSize` or @@ -1163,6 +1261,8 @@ These are the UTF-32 codec APIs: Return *NULL* if an exception was raised by the codec. + *Not part of the limited API.* + .. deprecated-removed:: 3.3 4.0 Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using :c:func:`PyUnicode_AsUTF32String` or :c:func:`PyUnicode_AsEncodedString`. @@ -1238,6 +1338,8 @@ These are the UTF-16 codec APIs: Return *NULL* if an exception was raised by the codec. + *Not part of the limited API.* + .. deprecated-removed:: 3.3 4.0 Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using :c:func:`PyUnicode_AsUTF16String` or :c:func:`PyUnicode_AsEncodedString`. @@ -1276,6 +1378,8 @@ These are the UTF-7 codec APIs: nonzero, whitespace will be encoded in base-64. Both are set to zero for the Python "utf-7" codec. + *Not part of the limited API.* + .. deprecated-removed:: 3.3 4.0 Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using :c:func:`PyUnicode_AsEncodedString`. @@ -1306,6 +1410,8 @@ These are the "Unicode Escape" codec API Encode the :c:type:`Py_UNICODE` buffer of the given *size* using Unicode-Escape and return a bytes object. Return *NULL* if an exception was raised by the codec. + *Not part of the limited API.* + .. deprecated-removed:: 3.3 4.0 Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using :c:func:`PyUnicode_AsUnicodeEscapeString`. @@ -1337,6 +1443,8 @@ These are the "Raw Unicode Escape" codec Encode the :c:type:`Py_UNICODE` buffer of the given *size* using Raw-Unicode-Escape and return a bytes object. Return *NULL* if an exception was raised by the codec. + *Not part of the limited API.* + .. deprecated-removed:: 3.3 4.0 Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using :c:func:`PyUnicode_AsRawUnicodeEscapeString` or @@ -1369,6 +1477,8 @@ ordinals and only these are accepted by return a Python bytes object. Return *NULL* if an exception was raised by the codec. + *Not part of the limited API.* + .. deprecated-removed:: 3.3 4.0 Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using :c:func:`PyUnicode_AsLatin1String` or @@ -1401,6 +1511,8 @@ codes generate errors. return a Python bytes object. Return *NULL* if an exception was raised by the codec. + *Not part of the limited API.* + .. deprecated-removed:: 3.3 4.0 Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using :c:func:`PyUnicode_AsASCIIString` or @@ -1467,6 +1579,8 @@ The following codec API is special in th and sequences work well. Unmapped character ordinals (ones which cause a :exc:`LookupError`) are left untouched and are copied as-is. + *Not part of the limited API.* + .. deprecated-removed:: 3.3 4.0 Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using :c:func:`PyUnicode_Translate`. or :ref:`generic codec based API @@ -1480,6 +1594,8 @@ The following codec API is special in th *mapping* object and return a Python string object. Return *NULL* if an exception was raised by the codec. + *Not part of the limited API.* + .. deprecated-removed:: 3.3 4.0 Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using :c:func:`PyUnicode_AsCharmapString` or @@ -1531,6 +1647,8 @@ the user settings on the machine running a Python bytes object. Return *NULL* if an exception was raised by the codec. + *Not part of the limited API.* + .. deprecated-removed:: 3.3 4.0 Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using :c:func:`PyUnicode_AsMBCSString`, :c:func:`PyUnicode_EncodeCodePage` or