gh-76535: Make PyUnicode_ToLowerFull and friends public

Doc/c-api/unicode.rst

@@ -307,6 +307,51 @@ These APIs can be used for fast direct character conversions:
    possible.  This function does not raise exceptions.
 
 
+.. c:function:: Py_ssize_t PyUnicode_ToLower(Py_UCS4 ch, Py_UCS4 *buffer, int size)
+
+   Convert *ch* to lower case, store result in *buffer*, which should be
+   able to hold as many characters needed for *ch* to be lower cased, and
+   return the number of characters stored. Passing a ``NULL`` buffer returns
+   the buffer size needed. If at some point a buffer overflow is detected,
+   an :exc:`ValueError` is raised and ``-1`` is returned.
+
+   .. versionadded:: next
+
+
+.. c:function:: Py_ssize_t PyUnicode_ToUpper(Py_UCS4 ch, Py_UCS4 *buffer, int size)
+
+   Convert *ch* to upper case, store result in *buffer*, which should be
+   able to hold as many characters needed for *ch* to be upper cased, and
+   return the number of characters stored. Passing a ``NULL`` buffer returns
+   the buffer size needed. If at some point a buffer overflow is detected,
+   an :exc:`ValueError` is raised and ``-1`` is returned.
+
+   .. versionadded:: next
+
+
+.. c:function:: Py_ssize_t PyUnicode_ToTitle(Py_UCS4 ch, Py_UCS4 *buffer, int size)
+
+   Convert *ch* to title case, store result in *buffer*, which should be
+   able to hold as many characters needed for *ch* to be title cased, and
+   return the number of characters stored. Passing a ``NULL`` buffer returns
+   the buffer size needed. If at some point a buffer overflow is detected,
+   an :exc:`ValueError` is raised and ``-1`` is returned.
+
+   .. versionadded:: next
+
+
+.. c:function:: Py_ssize_t PyUnicode_ToFolded(Py_UCS4 ch, Py_UCS4 *buffer, int size)
+
+   Foldcase *ch*, store result in *buffer*, which should be
+   able to hold as many characters needed for *ch* to be foldcased, and
+   return the number of characters stored. Passing a ``NULL`` buffer returns
+   the buffer size needed. If at some point a buffer overflow is detected,
+   an :exc:`ValueError` is raised and ``-1`` is returned.
+
+   .. versionadded:: next
+
+
+
 These APIs can be used to work with surrogates:
 
 .. c:function:: int Py_UNICODE_IS_SURROGATE(Py_UCS4 ch)

Include/cpython/unicodeobject.h

@@ -733,6 +733,31 @@ PyAPI_FUNC(int) _PyUnicode_IsAlpha(
     Py_UCS4 ch       /* Unicode character */
     );
 
+PyAPI_FUNC(int) PyUnicode_ToLower(
+    Py_UCS4 ch,     /* Unicode character */
+    Py_UCS4 *res,   /* Output buffer */
+    int size        /* Buffer size */
+    );
+
+PyAPI_FUNC(int) PyUnicode_ToUpper(
+    Py_UCS4 ch,     /* Unicode character */
+    Py_UCS4 *res,   /* Output buffer */
+    int size        /* Buffer size */
+    );
+
+PyAPI_FUNC(int) PyUnicode_ToTitle(
+    Py_UCS4 ch,     /* Unicode character */
+    Py_UCS4 *res,   /* Output buffer */
+    int size        /* Buffer size */
+    );
+
+PyAPI_FUNC(int) PyUnicode_ToFolded(
+    Py_UCS4 ch,     /* Unicode character */
+    Py_UCS4 *res,   /* Output buffer */
+    int size        /* Buffer size */
+    );
+
+
 // Helper array used by Py_UNICODE_ISSPACE().
 PyAPI_DATA(const unsigned char) _Py_ascii_whitespace[];
 

Include/internal/pycore_unicodeobject.h

@@ -15,10 +15,6 @@ extern "C" {
 
 extern int _PyUnicode_IsXidStart(Py_UCS4 ch);
 extern int _PyUnicode_IsXidContinue(Py_UCS4 ch);
-extern int _PyUnicode_ToLowerFull(Py_UCS4 ch, Py_UCS4 *res);
-extern int _PyUnicode_ToTitleFull(Py_UCS4 ch, Py_UCS4 *res);
-extern int _PyUnicode_ToUpperFull(Py_UCS4 ch, Py_UCS4 *res);
-extern int _PyUnicode_ToFoldedFull(Py_UCS4 ch, Py_UCS4 *res);
 extern int _PyUnicode_IsCaseIgnorable(Py_UCS4 ch);
 extern int _PyUnicode_IsCased(Py_UCS4 ch);
 

Misc/NEWS.d/next/C_API/2025-07-01-14-56-41.gh-issue-76535.9cwObj.rst

@@ -0,0 +1 @@
+Make :c:func:`PyUnicode_ToLower`, :c:func:`PyUnicode_ToUpper`, :c:func:`PyUnicode_ToTitle` and :c:func:`PyUnicode_ToFolded` public.

Objects/unicodectype.c

@@ -198,67 +198,114 @@ Py_UCS4 _PyUnicode_ToLowercase(Py_UCS4 ch)
     return ch + ctype->lower;
 }
 
-int _PyUnicode_ToLowerFull(Py_UCS4 ch, Py_UCS4 *res)
+int PyUnicode_ToLower(Py_UCS4 ch, Py_UCS4 *res, int size)
 {
     const _PyUnicode_TypeRecord *ctype = gettyperecord(ch);
 
     if (ctype->flags & EXTENDED_CASE_MASK) {
         int index = ctype->lower & 0xFFFF;
         int n = ctype->lower >> 24;
         int i;
-        for (i = 0; i < n; i++)
-            res[i] = _PyUnicode_ExtendedCase[index + i];
+        for (i = 0; i < n; i++) {
+            if (res != NULL) {
+                if (i >= size) {
+                    PyErr_SetString(PyExc_ValueError, "output buffer is too small");
+                    return -1;
+                }
+                res[i] = _PyUnicode_ExtendedCase[index + i];
+            }
+        }
         return n;
     }
-    res[0] = ch + ctype->lower;
+
+    if (res != NULL) {
+        if (0 >= size) {
+            PyErr_SetString(PyExc_ValueError, "output buffer is too small");
+            return -1;
+        }
+        res[0] = ch + ctype->lower;
+    }
     return 1;
 }
 
-int _PyUnicode_ToTitleFull(Py_UCS4 ch, Py_UCS4 *res)
+int PyUnicode_ToTitle(Py_UCS4 ch, Py_UCS4 *res, int size)
 {
     const _PyUnicode_TypeRecord *ctype = gettyperecord(ch);
 
     if (ctype->flags & EXTENDED_CASE_MASK) {
         int index = ctype->title & 0xFFFF;
         int n = ctype->title >> 24;
         int i;
-        for (i = 0; i < n; i++)
-            res[i] = _PyUnicode_ExtendedCase[index + i];
+        for (i = 0; i < n; i++) {
+            if (res != NULL) {
+                if (i >= size) {
+                    PyErr_SetString(PyExc_ValueError, "output buffer is too small");
+                    return -1;
+                }
+                res[i] = _PyUnicode_ExtendedCase[index + i];
+            }
+        }
         return n;
     }
-    res[0] = ch + ctype->title;
+    if (res != NULL) {
+        if (0 >= size) {
+            PyErr_SetString(PyExc_ValueError, "output buffer is too small");
+            return -1;
+        }
+        res[0] = ch + ctype->title;
+    }
     return 1;
 }
 
-int _PyUnicode_ToUpperFull(Py_UCS4 ch, Py_UCS4 *res)
+int PyUnicode_ToUpper(Py_UCS4 ch, Py_UCS4 *res, int size)
 {
     const _PyUnicode_TypeRecord *ctype = gettyperecord(ch);
 
     if (ctype->flags & EXTENDED_CASE_MASK) {
         int index = ctype->upper & 0xFFFF;
         int n = ctype->upper >> 24;
         int i;
-        for (i = 0; i < n; i++)
-            res[i] = _PyUnicode_ExtendedCase[index + i];
+        for (i = 0; i < n; i++) {
+            if (res != NULL) {
+                if (i >= size) {
+                    PyErr_SetString(PyExc_ValueError, "output buffer is too small");
+                    return -1;
+                }
+                res[i] = _PyUnicode_ExtendedCase[index + i];
+            }
+        }
         return n;
     }
-    res[0] = ch + ctype->upper;
+    if (res != NULL) {
+        if (0 >= size) {
+            PyErr_SetString(PyExc_ValueError, "output buffer is too small");
+            return -1;
+        }
+        res[0] = ch + ctype->upper;
+    }
     return 1;
 }
 
-int _PyUnicode_ToFoldedFull(Py_UCS4 ch, Py_UCS4 *res)
+int PyUnicode_ToFolded(Py_UCS4 ch, Py_UCS4 *res, int size)
 {
     const _PyUnicode_TypeRecord *ctype = gettyperecord(ch);
 
     if (ctype->flags & EXTENDED_CASE_MASK && (ctype->lower >> 20) & 7) {
         int index = (ctype->lower & 0xFFFF) + (ctype->lower >> 24);
         int n = (ctype->lower >> 20) & 7;
         int i;
-        for (i = 0; i < n; i++)
-            res[i] = _PyUnicode_ExtendedCase[index + i];
+        for (i = 0; i < n; i++) {
+            if (res != NULL) {
+                if (i >= size) {
+                    PyErr_SetString(PyExc_ValueError, "output buffer is too small");
+                    return -1;
+                }
+                res[i] = _PyUnicode_ExtendedCase[index + i];
+            }
+        }
         return n;
     }
-    return _PyUnicode_ToLowerFull(ch, res);
+    return PyUnicode_ToLower(ch, res, size);
 }
 
 int _PyUnicode_IsCased(Py_UCS4 ch)

Objects/unicodeobject.c

@@ -10039,14 +10039,14 @@ handle_capital_sigma(int kind, const void *data, Py_ssize_t length, Py_ssize_t i
 
 static int
 lower_ucs4(int kind, const void *data, Py_ssize_t length, Py_ssize_t i,
-           Py_UCS4 c, Py_UCS4 *mapped)
+           Py_UCS4 c, Py_UCS4 *mapped, int mapped_size)
 {
     /* Obscure special case. */
     if (c == 0x3A3) {
         mapped[0] = handle_capital_sigma(kind, data, length, i);
         return 1;
     }
-    return _PyUnicode_ToLowerFull(c, mapped);
+    return PyUnicode_ToLower(c, mapped, mapped_size);
 }
 
 static Py_ssize_t
@@ -10057,14 +10057,16 @@ do_capitalize(int kind, const void *data, Py_ssize_t length, Py_UCS4 *res, Py_UC
     Py_UCS4 c, mapped[3];
 
     c = PyUnicode_READ(kind, data, 0);
-    n_res = _PyUnicode_ToTitleFull(c, mapped);
+    n_res = PyUnicode_ToTitle(c, mapped, Py_ARRAY_LENGTH(mapped));
+    assert(n_res >= 1);
     for (j = 0; j < n_res; j++) {
         *maxchar = Py_MAX(*maxchar, mapped[j]);
         res[k++] = mapped[j];
     }
     for (i = 1; i < length; i++) {
         c = PyUnicode_READ(kind, data, i);
-        n_res = lower_ucs4(kind, data, length, i, c, mapped);
+        n_res = lower_ucs4(kind, data, length, i, c, mapped, Py_ARRAY_LENGTH(mapped));
+        assert(n_res >= 1);
         for (j = 0; j < n_res; j++) {
             *maxchar = Py_MAX(*maxchar, mapped[j]);
             res[k++] = mapped[j];
@@ -10081,15 +10083,16 @@ do_swapcase(int kind, const void *data, Py_ssize_t length, Py_UCS4 *res, Py_UCS4
         Py_UCS4 c = PyUnicode_READ(kind, data, i), mapped[3];
         int n_res, j;
         if (Py_UNICODE_ISUPPER(c)) {
-            n_res = lower_ucs4(kind, data, length, i, c, mapped);
+            n_res = lower_ucs4(kind, data, length, i, c, mapped, Py_ARRAY_LENGTH(mapped));
         }
         else if (Py_UNICODE_ISLOWER(c)) {
-            n_res = _PyUnicode_ToUpperFull(c, mapped);
+            n_res = PyUnicode_ToUpper(c, mapped, Py_ARRAY_LENGTH(mapped));
         }
         else {
             n_res = 1;
             mapped[0] = c;
         }
+        assert(n_res >= 1);
         for (j = 0; j < n_res; j++) {
             *maxchar = Py_MAX(*maxchar, mapped[j]);
             res[k++] = mapped[j];
@@ -10108,9 +10111,10 @@ do_upper_or_lower(int kind, const void *data, Py_ssize_t length, Py_UCS4 *res,
         Py_UCS4 c = PyUnicode_READ(kind, data, i), mapped[3];
         int n_res, j;
         if (lower)
-            n_res = lower_ucs4(kind, data, length, i, c, mapped);
+            n_res = lower_ucs4(kind, data, length, i, c, mapped, Py_ARRAY_LENGTH(mapped));
         else
-            n_res = _PyUnicode_ToUpperFull(c, mapped);
+            n_res = PyUnicode_ToUpper(c, mapped, Py_ARRAY_LENGTH(mapped));
+        assert(n_res >= 1);
         for (j = 0; j < n_res; j++) {
             *maxchar = Py_MAX(*maxchar, mapped[j]);
             res[k++] = mapped[j];
@@ -10139,7 +10143,8 @@ do_casefold(int kind, const void *data, Py_ssize_t length, Py_UCS4 *res, Py_UCS4
     for (i = 0; i < length; i++) {
         Py_UCS4 c = PyUnicode_READ(kind, data, i);
         Py_UCS4 mapped[3];
-        int j, n_res = _PyUnicode_ToFoldedFull(c, mapped);
+        int j, n_res = PyUnicode_ToFolded(c, mapped, Py_ARRAY_LENGTH(mapped));
+        assert(n_res >= 1);
         for (j = 0; j < n_res; j++) {
             *maxchar = Py_MAX(*maxchar, mapped[j]);
             res[k++] = mapped[j];
@@ -10161,10 +10166,10 @@ do_title(int kind, const void *data, Py_ssize_t length, Py_UCS4 *res, Py_UCS4 *m
         int n_res, j;
 
         if (previous_is_cased)
-            n_res = lower_ucs4(kind, data, length, i, c, mapped);
+            n_res = lower_ucs4(kind, data, length, i, c, mapped, Py_ARRAY_LENGTH(mapped));
         else
-            n_res = _PyUnicode_ToTitleFull(c, mapped);
-
+            n_res = PyUnicode_ToTitle(c, mapped, Py_ARRAY_LENGTH(mapped));
+        assert(n_res >= 1);
         for (j = 0; j < n_res; j++) {
             *maxchar = Py_MAX(*maxchar, mapped[j]);
             res[k++] = mapped[j];