Documentation about PyUnicode_AsWideChar() function

[qqwqqw689]

In file _winapi.c

We can see code:

size = PyUnicode_AsWideChar(key, NULL, 0);

Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *wstr, Py_ssize_t size)

But the doc say "Copies the Unicode Object contents into the wchar_t buffer w. At most size wchar_t characters are copied.".I think we miss the situation when size is 0.

Linked PRs

• gh-113437: Update documentation about PyUnicode_AsWideChar() function #113455
• [3.12] gh-113437: Update documentation about PyUnicode_AsWideChar() function (GH-113455) #115407
• [3.11] gh-113437: Update documentation about PyUnicode_AsWideChar() function (GH-113455) #115408

[erlend-aasland]

If size is 0, nothing is copied. I don't see any problems with that scenario and the docs.

[qqwqqw689]

For the codes in _winapi.c:

size = PyUnicode_AsWideChar(key, NULL, 0);
assert(size > 1);
if (totalsize > PY_SSIZE_T_MAX - size) {
      PyErr_SetString(PyExc_OverflowError, "environment too long");
      goto error;

If nothing is copied, the return size will 0.(In doc , it says "Return the number of wchar_t characters copied or -1 in case of an error.".)
Then,

assert(size > 1);

will always be wrong.

[qqwqqw689]

I find the definition of PyUnicode_AsWideChar():

Py_ssize_t
PyUnicode_AsWideChar(PyObject *unicode,
                     wchar_t *w,
                     Py_ssize_t size)
{
    Py_ssize_t res;

    if (unicode == NULL) {
        PyErr_BadInternalCall();
        return -1;
    }
    if (!PyUnicode_Check(unicode)) {
        PyErr_BadArgument();
        return -1;
    }

    res = unicode_get_widechar_size(unicode);
    if (w == NULL) {
        return res + 1;
    }

    if (size > res) {
        size = res + 1;
    }
    else {
        res = size;
    }
    unicode_copy_as_widechar(unicode, w, size);

#ifdef HAVE_NON_UNICODE_WCHAR_T_REPRESENTATION
    /* Oracle Solaris uses non-Unicode internal wchar_t form for
       non-Unicode locales and hence needs conversion first. */
    if (_Py_LocaleUsesNonUnicodeWchar()) {
        if (_Py_EncodeNonUnicodeWchar_InPlace(w, size) < 0) {
            return -1;
        }
    }
#endif

    return res;
}

If w is NULL, it will return res + 1 even size is 0.

[ronaldoussoren]

If w is NULL, it will return res + 1 even size is 0.

That's the part that's missing from the documentation: PyUnicode_AsWideChar returns the size the buffer needs to be when called with a NULL buffer.

Can you create a PR for this?

[qqwqqw689]

Yes