Add PyUnicode_EqualToUTF8() function

Author: vstinner

docs/api.rst

@@ -129,6 +129,12 @@ Python 3.12
 
    Not available on PyPy.
 
+.. c:function:: int PyUnicode_EqualToUTF8(PyObject *unicode, const char *str)
+
+   See `PyUnicode_EqualToUTF8() documentation <https://docs.python.org/dev/c-api/unicode.html#c.PyUnicode_EqualToUTF8>`__.
+
+   Not available on PyPy.
+
 
 Python 3.11
 -----------

docs/changelog.rst

@@ -1,6 +1,7 @@
 Changelog
 =========
 
+* 2023-10-04: Add ``PyUnicode_EqualToUTF8()`` function.
 * 2023-10-03: Add functions:
 
   * ``PyObject_VisitManagedDict()``

pythoncapi_compat.h

@@ -939,6 +939,62 @@ PyThreadState_GetUnchecked(void)
 }
 #endif
 
+// gh-110289 added PyUnicode_EqualToUTF8() to Python 3.13.0a1
+#if PY_VERSION_HEX < 0x030D00A1
+static inline int
+PyUnicode_EqualToUTF8(PyObject *unicode, const char *str)
+{
+    Py_ssize_t len;
+    const void *utf8;
+    // Python 3.3.0a1 added PyUnicode_AsUTF8AndSize()
+#if PY_VERSION_HEX >= 0x030300A1
+    if (PyUnicode_IS_ASCII(unicode)) {
+        utf8 = PyUnicode_DATA(unicode);
+        len = PyUnicode_GET_LENGTH(unicode);
+    }
+    else {
+        utf8 = PyUnicode_AsUTF8AndSize(unicode, &len);
+        if (utf8 == NULL) {
+            // Memory allocation failure. The API cannot report error,
+            // so clear the exception and return 0.
+            PyErr_Clear();
+            return 0;
+        }
+    }
+
+    if ((size_t)len != strlen(str)) {
+        return 0;
+    }
+    return (memcmp(utf8, str, (size_t)len) == 0);
+#else
+    int res;
+    PyObject *bytes = PyUnicode_AsUTF8String(unicode);
+    if (bytes == NULL) {
+        // Memory allocation failure. The API cannot report error,
+        // so clear the exception and return 0.
+        PyErr_Clear();
+        return 0;
+    }
+
+#if PY_VERSION_HEX >= 0x03000000
+    len = PyBytes_GET_SIZE(bytes);
+    utf8 = PyBytes_AS_STRING(bytes);
+#else
+    len = PyString_GET_SIZE(bytes);
+    utf8 = PyString_AS_STRING(bytes);
+#endif
+    if ((size_t)len != strlen(str)) {
+        Py_DECREF(bytes);
+        return 0;
+    }
+
+    res = (memcmp(utf8, str, (size_t)len) == 0);
+    Py_DECREF(bytes);
+    return res;
+#endif
+}
+#endif
+
 
 #ifdef __cplusplus
 }

tests/test_pythoncapi_compat_cext.c

@@ -1361,6 +1361,22 @@ test_managed_dict(PyObject *Py_UNUSED(module), PyObject *Py_UNUSED(args))
 #endif  // PY_VERSION_HEX >= 0x030B00A3
 
 
+static PyObject *
+test_unicode(PyObject *Py_UNUSED(module), PyObject *Py_UNUSED(args))
+{
+    PyObject *abc = PyUnicode_FromString("abc");
+    if (abc == NULL) {
+        return NULL;
+    }
+
+    assert(PyUnicode_EqualToUTF8(abc, "abc") == 1);
+    assert(PyUnicode_EqualToUTF8(abc, "Python") == 0);
+
+    Py_DECREF(abc);
+    Py_RETURN_NONE;
+}
+
+
 static struct PyMethodDef methods[] = {
     {"test_object", test_object, METH_NOARGS, _Py_NULL},
     {"test_py_is", test_py_is, METH_NOARGS, _Py_NULL},
@@ -1390,6 +1406,7 @@ static struct PyMethodDef methods[] = {
 #ifdef TEST_MANAGED_DICT
     {"test_managed_dict", test_managed_dict, METH_NOARGS, _Py_NULL},
 #endif
+    {"test_unicode", test_unicode, METH_NOARGS, _Py_NULL},
     {_Py_NULL, _Py_NULL, 0, _Py_NULL}
 };