From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Tue, 4 Nov 2025 21:33:52 +0000 (+0100)
Subject: [3.14] gh-141004: Document `Py_UNICODE_{HIGH, LOW}_SURROGATE` functions (GH-141019... 
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=7ab08d2c5171e35f4a2295070f843c786c7da7d0;p=thirdparty%2FPython%2Fcpython.git

[3.14] gh-141004: Document `Py_UNICODE_{HIGH, LOW}_SURROGATE` functions (GH-141019) (GH-141027)

gh-141004: Document `Py_UNICODE_{HIGH, LOW}_SURROGATE` functions (GH-141019)
(cherry picked from commit bfe54810c408ff066591d1af0411b1d9c10084b1)

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
---

diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index aeb86e06d993..9fa88915c3c0 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -305,12 +305,22 @@ These APIs can be used to work with surrogates:
 
    Check if *ch* is a low surrogate (``0xDC00 <= ch <= 0xDFFF``).
 
+.. c:function:: Py_UCS4 Py_UNICODE_HIGH_SURROGATE(Py_UCS4 ch)
+
+    Return the high UTF-16 surrogate (``0xD800`` to ``0xDBFF``) for a Unicode
+    code point in the range ``[0x10000; 0x10FFFF]``.
+
+.. c:function:: Py_UCS4 Py_UNICODE_LOW_SURROGATE(Py_UCS4 ch)
+
+    Return the low UTF-16 surrogate (``0xDC00`` to ``0xDFFF``) for a Unicode
+    code point in the range ``[0x10000; 0x10FFFF]``.
+
 .. c:function:: Py_UCS4 Py_UNICODE_JOIN_SURROGATES(Py_UCS4 high, Py_UCS4 low)
 
    Join two surrogate code points and return a single :c:type:`Py_UCS4` value.
    *high* and *low* are respectively the leading and trailing surrogates in a
-   surrogate pair. *high* must be in the range [0xD800; 0xDBFF] and *low* must
-   be in the range [0xDC00; 0xDFFF].
+   surrogate pair. *high* must be in the range ``[0xD800; 0xDBFF]`` and *low* must
+   be in the range ``[0xDC00; 0xDFFF]``.
 
 
 Creating and accessing Unicode strings