[mypyc] Document recent additions to librt.strings, such as ispace (#21696)

Document `is*` functions, `toupper` and `tolower`.

Author: JukkaL

mypyc/doc/librt_strings.rst

@@ -15,7 +15,7 @@ Thread safety
 ``BytesWriter`` and ``StringWriter`` objects are unsafe to access from another
 thread if they are concurrently modified (on free-threaded Python builds). They are optimized
 for maximal performance, and they aren't fully synchronized. Read-only access from multiple
-threads is safe.
+threads is safe, as always.
 
 BytesWriter
 ^^^^^^^^^^^
@@ -101,6 +101,9 @@ StringWriter
 Functions
 ---------
 
+Reading and writing binary data
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 The ``write_*`` and ``read_*`` functions allow interpreting bytes as packed binary
 data. They can be used as (much) more efficient but lower-level alternatives to the
 stdlib :mod:`struct` module in compiled code.
@@ -210,3 +213,60 @@ This example writes two binary values and reads them afterwards::
 
    Read a 64-bit floating-point value starting at the given index as a big-endian binary value
    (8 bytes).
+
+Code point classification
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+These functions classify a single Unicode code point, passed as an ``i32`` integer. They are
+faster alternatives to calling the corresponding :py:class:`str` methods on a one-character
+string in compiled code. A code point is often obtained via ``ord(s[i])``, which is a
+fast operation in compiled code when ``s`` has type :py:class:`str`.
+
+Each function agrees with the matching :py:class:`str` method applied to the one-character
+string ``chr(c)``. Out-of-range inputs (negative values, or values past the maximum Unicode
+code point ``0x10FFFF``) return ``False``.
+
+.. function:: isspace(c: i32, /) -> bool
+
+   Return whether the code point is whitespace. Equivalent to ``chr(c).isspace()``.
+
+.. function:: isalpha(c: i32, /) -> bool
+
+   Return whether the code point is alphabetic. Equivalent to ``chr(c).isalpha()``.
+
+.. function:: isdigit(c: i32, /) -> bool
+
+   Return whether the code point is a digit. Equivalent to ``chr(c).isdigit()``.
+
+.. function:: isalnum(c: i32, /) -> bool
+
+   Return whether the code point is alphanumeric. Equivalent to ``chr(c).isalnum()``.
+
+.. function:: isidentifier(c: i32, /) -> bool
+
+   Return whether the code point is valid as the first character of a Python identifier.
+   Equivalent to ``chr(c).isidentifier()``.
+
+Code point case conversion
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+These functions convert the case of a single Unicode code point, passed as an ``i32`` integer,
+and return the converted code point as an ``i32``. They are faster alternatives to
+:py:meth:`str.upper` / :py:meth:`str.lower` on a one-character string in compiled code.
+
+For the rare code points whose Unicode uppercase or lowercase form has multiple code points
+(e.g. U+00DF ``ß`` has the upper case form ``"SS"``, and U+FB01 ``fi`` maps to ``"FI"``), the
+input is returned unchanged, so the signature can stay ``i32 -> i32``. Use :py:meth:`str.upper`
+/ :py:meth:`str.lower` when full Unicode case conversion matters, or implement the logic to
+handle the special cases explicitly. Out-of-range inputs (negative values, or values past the
+maximum Unicode code point ``0x10FFFF``) are returned unchanged.
+
+.. function:: toupper(c: i32, /) -> i32
+
+   Return the uppercase of the code point, or the input unchanged if the uppercase does not
+   consist of exactly one code point.
+
+.. function:: tolower(c: i32, /) -> i32
+
+   Return the lowercase of the code point, or the input unchanged if the lowercase does not
+   consist of exactly one code point.