Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

gh-89653: PEP 670: Update C API unicode documentation (#92702)

This commit is contained in:
Victor Stinner 2022-05-12 01:33:52 +02:00 committed by GitHub
parent f9b67ad770
commit 92f0ed1d90
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 11 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
Doc/c-api/unicode.rst
View File

@ -130,7 +130,7 @@ access to internal read-only data of Unicode objects:
Return a pointer to the canonical representation cast to UCS1, UCS2 or UCS4
integer types for direct character access. No checks are performed if the
canonical representation has the correct character size; use
:c:func:`PyUnicode_KIND` to select the right macro. Make sure
:c:func:`PyUnicode_KIND` to select the right function. Make sure
:c:func:`PyUnicode_READY` has been called before accessing this.
.. versionadded:: 3.3
@ -360,40 +360,41 @@ These APIs can be used for fast direct character conversions:
.. c:function:: int Py_UNICODE_TODECIMAL(Py_UCS4 ch)
Return the character *ch* converted to a decimal positive integer. Return
``-1`` if this is not possible. This macro does not raise exceptions.
``-1`` if this is not possible. This function does not raise exceptions.
.. c:function:: int Py_UNICODE_TODIGIT(Py_UCS4 ch)
Return the character *ch* converted to a single digit integer. Return ``-1`` if
this is not possible. This macro does not raise exceptions.
this is not possible. This function does not raise exceptions.
.. c:function:: double Py_UNICODE_TONUMERIC(Py_UCS4 ch)
Return the character *ch* converted to a double. Return ``-1.0`` if this is not
possible. This macro does not raise exceptions.
possible. This function does not raise exceptions.
These APIs can be used to work with surrogates:
.. c:macro:: Py_UNICODE_IS_SURROGATE(ch)
.. c:func:: int Py_UNICODE_IS_SURROGATE(Py_UCS4 ch)
Check if *ch* is a surrogate (``0xD800 <= ch <= 0xDFFF``).
.. c:macro:: Py_UNICODE_IS_HIGH_SURROGATE(ch)
.. c:func:: int Py_UNICODE_IS_HIGH_SURROGATE(Py_UCS4 ch)
Check if *ch* is a high surrogate (``0xD800 <= ch <= 0xDBFF``).
.. c:macro:: Py_UNICODE_IS_LOW_SURROGATE(ch)
.. c:func:: int Py_UNICODE_IS_LOW_SURROGATE(Py_UCS4 ch)
Check if *ch* is a low surrogate (``0xDC00 <= ch <= 0xDFFF``).
.. c:macro:: Py_UNICODE_JOIN_SURROGATES(high, low)
.. c:func:: Py_UCS4 Py_UNICODE_JOIN_SURROGATES(Py_UCS4 high, Py_UCS4 low)
Join two surrogate characters and return a single Py_UCS4 value.
Join two surrogate characters and return a single :c:type:`Py_UCS4` value.
*high* and *low* are respectively the leading and trailing surrogates in a
surrogate pair.
surrogate pair. *high* must be in the range [0xD800; 0xDBFF] and *low* must
be in the range [0xDC00; 0xDFFF].
Creating and accessing Unicode strings