Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 1 commit into from
May 11, 2022
Merged

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 11 additions & 10 deletions Doc/c-api/unicode.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down