From: Zackery Spytz <zspytz@gmail.com>
Date: Thu, 3 Jun 2021 13:33:44 +0000 (-0700)
Subject: bpo-39560: Document PyUnicode_FromKindAndData() kind transformation (GH-23848)
X-Git-Tag: v3.11.0a1~959
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=4eed2821d40373345ed133b2b8d912fef59acab7;p=thirdparty%2FPython%2Fcpython.git

bpo-39560: Document PyUnicode_FromKindAndData() kind transformation (GH-23848)
---

diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index 8322d3da76dc..ddc2346e92dc 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -421,6 +421,12 @@ 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.
 
+   If necessary, the input *buffer* is copied and transformed into the
+   canonical representation.  For example, if the *buffer* is a UCS4 string
+   (:c:macro:`PyUnicode_4BYTE_KIND`) and it consists only of codepoints in
+   the UCS1 range, it will be transformed into UCS1
+   (:c:macro:`PyUnicode_1BYTE_KIND`).
+
    .. versionadded:: 3.3