gh-141004: Document PyOS_mystr(n)icmp

[StanFromIreland]

• Issue: Document the entire C API #141004

---

📚 Documentation preview 📚: https://cpython-previews--141760.org.readthedocs.build/

[encukou]

These are aliases of PyOS_stricmp/PyOS_strnicmp, except on Windows (where the my-less variants are aliases of stricmp/strnicmp -- I assume that's because we know they work on that platform).
Could you document them in c-api/conversion?

Ideally also mention that they only ignore case of ASCII characters, and aren't affected by locale.

[vstinner]

LGTM

[encukou]

I'll review next week, please wait

[encukou]

"my" functions are always defined on all platforms, but PyOS_stricmp() and PyOS_strnicmp() can be aliases or not. You got it backwards, no?

I'd be careful here. This is how the code works, but we don't want to document implementation details.

These functions are quite old. They come from an age when if something was undocumented (on purpose), it was meant to be internal. IOW, the my variants were meant as implementation details of the documented functions.

But, nowadays, I think the my variants are better -- they work the same on
all platforms, and they're not C/C++-only macros.

---

These functions can fail -- with buffer overruns, if the strings are not
properly terminated. Typically that'll give bad results or a crash.
IMO it's better to omit the “This function cannot fail.” note, rather than give
the full details.

---

Consider

• grouping similar functions together, and
• not repeating the docs in aliases

Here's my attempt:

.. c:function:: int PyOS_mystricmp(const char *str1, const char *str2)
                int PyOS_mystrnicmp(const char *str1, const char *str2, Py_ssize_t size)

   Case insensitive comparison of strings. These functions work almost
   identically to :c:func:`!strcmp` and :c:func:`!strncmp` (respectively),
   except that they ignore the case of ASCII characters.

   Return ``0`` if the strings are equal, a negative value if *str1* sorts
   lexicographically before *str2*, or a positive value if it sorts after.

   In the *s1* or *s2* arguments, a NUL byte marks the end of the string.
   For :c:func:`!PyOS_strnicmp`, the *size* argument gives the maximum size
   of the string, as if NUL was present at the index given by *size*.

   These functions do not use the locale.

.. c:function:: int PyOS_stricmp(const char *s1, const char *s2)
                int PyOS_strnicmp(const char *s1, const char *s2, Py_ssize_t  size)

   Case insensitive comparison of strings.

   On Windows, these are aliases of :c:func:`!stricmp` and :c:func:`!strnicmp`,
   respectively.

   On other platforms, they are aliases of:c:func:`PyOS_mystricmp` and
   :c:func:`PyOS_mystrnicmp`, respectively.

(It's funny that stricmp/strnicmp are deprecated on Windows but not in POSIX... anyway that's not for a docs PR to untangle.)

[StanFromIreland]

I applied with some little changes.

[miss-islington-app]

Thanks @StanFromIreland for the PR, and @vstinner for merging it 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖

[bedevere-app]

GH-141947 is a backport of this pull request to the 3.14 branch.

[miss-islington-app]

Thanks @StanFromIreland for the PR, and @vstinner for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13.
🐍🍒⛏🤖

[bedevere-app]

GH-141948 is a backport of this pull request to the 3.13 branch.

[vstinner]

Merged, thanks.