[mypyc] Document optimized bytes ops and additional str ops (#18242)

JukkaL · web-flow · commit 5082a221f33e · 2024-12-04T13:52:02.000Z
The docs were somewhat out of date.
diff --git a/mypyc/doc/bytes_operations.rst b/mypyc/doc/bytes_operations.rst
@@ -0,0 +1,46 @@
+.. _bytes-ops:
+
+Native bytes operations
+========================
+
+These ``bytes`` operations have fast, optimized implementations. Other
+bytes operations use generic implementations that are often slower.
+
+Construction
+------------
+
+* Bytes literal
+* ``bytes(x: list)``
+
+Operators
+---------
+
+* Concatenation (``b1 + b2``)
+* Indexing (``b[n]``)
+* Slicing (``b[n:m]``, ``b[n:]``, ``b[:m]``)
+* Comparisons (``==``, ``!=``)
+
+.. _bytes-methods:
+
+Methods
+-------
+
+* ``b.decode()``
+* ``b.decode(encoding: str)``
+* ``b.decode(encoding: str, errors: str)``
+* ``b.join(x: Iterable)``
+
+.. note::
+
+    :ref:`str.encode() <str-methods>` is also optimized.
+
+Formatting
+----------
+
+A subset of % formatting operations are optimized (``b"..." % (...)``).
+
+Functions
+---------
+
+* ``len(b: bytes)``
+* ``ord(b: bytes)``
diff --git a/mypyc/doc/index.rst b/mypyc/doc/index.rst
@@ -36,6 +36,7 @@ generate fast code.
    bool_operations
    float_operations
    str_operations
+   bytes_operations
    list_operations
    dict_operations
    set_operations
diff --git a/mypyc/doc/str_operations.rst b/mypyc/doc/str_operations.rst
@@ -22,9 +22,14 @@ Operators
 * Comparisons (``==``, ``!=``)
 * Augmented assignment (``s1 += s2``)
 
+.. _str-methods:
+
 Methods
 -------
 
+* ``s.encode()``
+* ``s.encode(encoding: str)``
+* ``s.encode(encoding: str, errors: str)``
 * ``s1.endswith(s2: str)``
 * ``s.join(x: Iterable)``
 * ``s.replace(old: str, new: str)``
@@ -34,8 +39,21 @@ Methods
 * ``s.split(sep: str, maxsplit: int)``
 * ``s1.startswith(s2: str)``
 
+.. note::
+
+    :ref:`bytes.decode() <bytes-methods>` is also optimized.
+
+Formatting
+----------
+
+A subset of these common string formatting expressions are optimized:
+
+* F-strings
+* ``"...".format(...)``
+* ``"..." % (...)``
+
 Functions
 ---------
 
- * ``len(s: str)``
- * ``ord(s: str)``
+* ``len(s: str)``
+* ``ord(s: str)``
