Add a page detailing the time complexity of operations on built-in types (#154363)

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
Co-authored-by: Pieter Eendebak <pieter.eendebak@gmail.com>
Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>
Co-authored-by: dgpb <3577712+dg-pb@users.noreply.github.com>

Author: 5 people

Doc/faq/design.rst

@@ -430,6 +430,8 @@ tuples, but not lists, can be used as keys. Note, however, that a tuple is
 only hashable if all of its elements are hashable.
 
 
+.. _how-are-lists-implemented:
+
 How are lists implemented in CPython?
 -------------------------------------
 
@@ -445,6 +447,10 @@ cleverness is applied to improve the performance of appending items repeatedly;
 when the array must be grown, some extra space is allocated so the next few
 times don't require an actual resize.
 
+See :ref:`time-complexity` for the costs of the various list operations.
+
+
+.. _how-are-dictionaries-implemented:
 
 How are dictionaries implemented in CPython?
 --------------------------------------------
@@ -462,6 +468,8 @@ internal array where the value will be stored.  Assuming that you're storing
 keys that all have different hash values, this means that dictionaries take
 constant time -- *O*\ (1), in Big-O notation -- to retrieve a key.
 
+See :ref:`time-complexity` for the costs of the various dictionary operations.
+
 
 Why must dictionary keys be immutable?
 --------------------------------------

Doc/faq/programming.rst

@@ -1136,7 +1136,7 @@ What is the most efficient way to concatenate many strings together?
 :class:`str` and :class:`bytes` objects are immutable, therefore concatenating
 many strings together is inefficient as each concatenation creates a new
 object.  In the general case, the total runtime cost is quadratic in the
-total string length.
+total string length.  See :ref:`time-complexity` for more information.
 
 To accumulate many :class:`str` objects, the recommended idiom is to place
 them into a list and call :meth:`str.join` at the end::

Doc/glossary.rst

@@ -942,7 +942,7 @@ Glossary
    list
       A built-in Python :term:`sequence`.  Despite its name it is more akin
       to an array in other languages than to a linked list since access to
-      elements is *O*\ (1).
+      elements is *O*\ (1).  See :ref:`time-complexity`.
 
    list comprehension
       A compact way to process all or part of the elements in a sequence and

Doc/library/index.rst

@@ -44,6 +44,7 @@ the `Python Package Index <https://pypi.org>`_.
    stdtypes.rst
    exceptions.rst
    threadsafety.rst
+   time-complexity.rst
 
    text.rst
    binary.rst

Doc/library/stdtypes.rst

@@ -999,6 +999,9 @@ The ``in`` and ``not in`` operations have the same priorities as the
 comparison operations. The ``+`` (concatenation) and ``*`` (repetition)
 operations have the same priority as the corresponding numeric operations. [3]_
 
+See :ref:`time-complexity` for the costs of the various sequence
+operations.
+
 .. index::
    triple: operations on; sequence; types
    pair: built-in function; len
@@ -1121,6 +1124,8 @@ Notes:
    "end" values (which end depends on the sign of *k*).  Note, *k* cannot be zero.
    If *k* is ``None``, it is treated like ``1``.
 
+.. _typesseq-repeated-concatenation:
+
 (6)
    Concatenating immutable sequences always results in a new object.  This
    means that building up a sequence by repeated concatenation will have a
@@ -5146,6 +5151,7 @@ computing mathematical operations such as intersection, union, difference, and
 symmetric difference.
 (For other containers see the built-in :class:`dict`, :class:`list`,
 and :class:`tuple` classes, and the :mod:`collections` module.)
+See :ref:`time-complexity` for the costs of the various set operations.
 
 Like other collections, sets support ``x in set``, ``len(set)``, and ``for x in
 set``.  Being an unordered collection, sets do not record element position or
@@ -5370,6 +5376,8 @@ There are currently two standard mapping types, the :dfn:`dictionary` and
 (For other containers see the built-in
 :class:`list`, :class:`set`, and :class:`tuple` classes, and the
 :mod:`collections` module.)
+See :ref:`time-complexity` for the costs of the various dictionary
+operations.
 
 A dictionary's keys are *almost* arbitrary values.  Values that are not
 :term:`hashable`, that is, values containing lists, dictionaries or other