From 424044d97617e9f1bd0b4c42967e384bd52efa33 Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Mon, 8 Aug 2022 22:27:03 -0500 Subject: [PATCH 1/3] Misc improvements to the bisect docs: * Clarify the differences from tools like bsearch() in C. * Document that ``__lt__`` is called instead of ``__eq__``. * Refer to the partitions as "slices" instead of "halves". * Make the invariants more readable with a better variable name. * Eliminate redundant text in bisect_right(), noting only the differences from bisect_left(). --- Doc/library/bisect.rst | 37 ++++++++++++++++++------------------- 1 file changed, 18 insertions(+), 19 deletions(-) diff --git a/Doc/library/bisect.rst b/Doc/library/bisect.rst index 513675d3685a52..c180d110dbc7da 100644 --- a/Doc/library/bisect.rst +++ b/Doc/library/bisect.rst @@ -13,10 +13,16 @@ This module provides support for maintaining a list in sorted order without having to sort the list after each insertion. For long lists of items with -expensive comparison operations, this can be an improvement over the more common -approach. The module is called :mod:`bisect` because it uses a basic bisection -algorithm to do its work. The source code may be most useful as a working -example of the algorithm (the boundary conditions are already right!). +expensive comparison operations, this can be an improvement over +linear searches or frequent resorting. + +The module is called :mod:`bisect` because it uses a basic bisection +algorithm to do its work. Unlike other bisection tools that search for a +specific value, the functions in this module are designed to locate can +insertion point. Accordingly, the functions never call an :meth:`__eq__` +method to determine whether a value has been found. Instead, the functions +only call the :meth:`__lt__` method and return an insertion point between +values in an array. The following functions are provided: @@ -30,16 +36,16 @@ The following functions are provided: any existing entries. The return value is suitable for use as the first parameter to ``list.insert()`` assuming that *a* is already sorted. - The returned insertion point *i* partitions the array *a* into two halves so - that ``all(val < x for val in a[lo : i])`` for the left side and - ``all(val >= x for val in a[i : hi])`` for the right side. + The returned insertion point *i* partitions the array *a* into two slices + so that ``all(elem < x for elem in a[lo : i])`` for the left side and + ``all(elem >= x for elem in a[i : hi])`` for the right side. *key* specifies a :term:`key function` of one argument that is used to extract a comparison key from each element in the array. To support searching complex records, the key function is not applied to the *x* value. - If *key* is ``None``, the elements are compared directly with no - intervening function call. + If *key* is ``None``, the elements are compared directly and + no key function is called. .. versionchanged:: 3.10 Added the *key* parameter. @@ -51,16 +57,9 @@ The following functions are provided: Similar to :func:`bisect_left`, but returns an insertion point which comes after (to the right of) any existing entries of *x* in *a*. - The returned insertion point *i* partitions the array *a* into two halves so - that ``all(val <= x for val in a[lo : i])`` for the left side and - ``all(val > x for val in a[i : hi])`` for the right side. - - *key* specifies a :term:`key function` of one argument that is used to - extract a comparison key from each element in the array. To support - searching complex records, the key function is not applied to the *x* value. - - If *key* is ``None``, the elements are compared directly with no - intervening function call. + The returned insertion point *i* partitions the array *a* into two slices + so that ``all(elem <= x for elem in a[lo : i])`` for the left side and + ``all(elem > x for elem in a[i : hi])`` for the right side. .. versionchanged:: 3.10 Added the *key* parameter. From a45e91f207113fe44079aa0b0ff56c8971c07837 Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Mon, 8 Aug 2022 22:57:00 -0500 Subject: [PATCH 2/3] More touchups --- Doc/library/bisect.rst | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/Doc/library/bisect.rst b/Doc/library/bisect.rst index c180d110dbc7da..cdd8ae09b4acc2 100644 --- a/Doc/library/bisect.rst +++ b/Doc/library/bisect.rst @@ -18,11 +18,11 @@ linear searches or frequent resorting. The module is called :mod:`bisect` because it uses a basic bisection algorithm to do its work. Unlike other bisection tools that search for a -specific value, the functions in this module are designed to locate can +specific value, the functions in this module are designed to locate an insertion point. Accordingly, the functions never call an :meth:`__eq__` -method to determine whether a value has been found. Instead, the functions -only call the :meth:`__lt__` method and return an insertion point between -values in an array. +method to determine whether a value has been found. Instead, the +functions only call the :meth:`__lt__` method and will return an insertion +point between values in an array. The following functions are provided: @@ -36,9 +36,10 @@ The following functions are provided: any existing entries. The return value is suitable for use as the first parameter to ``list.insert()`` assuming that *a* is already sorted. - The returned insertion point *i* partitions the array *a* into two slices - so that ``all(elem < x for elem in a[lo : i])`` for the left side and - ``all(elem >= x for elem in a[i : hi])`` for the right side. + The returned insertion point *i* partitions the array *a* into two + slices such that ``all(elem < x for elem in a[lo : i])`` is true for the + left slice and ``all(elem >= x for elem in a[i : hi])`` is true for the + right slice. *key* specifies a :term:`key function` of one argument that is used to extract a comparison key from each element in the array. To support @@ -58,8 +59,8 @@ The following functions are provided: after (to the right of) any existing entries of *x* in *a*. The returned insertion point *i* partitions the array *a* into two slices - so that ``all(elem <= x for elem in a[lo : i])`` for the left side and - ``all(elem > x for elem in a[i : hi])`` for the right side. + such that ``all(elem <= x for elem in a[lo : i])`` is true for the left slice and + ``all(elem > x for elem in a[i : hi])`` is true for the right slice. .. versionchanged:: 3.10 Added the *key* parameter. From 90109c9d0d2d6913dfa0d81ab47b6e3cfc943bed Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Mon, 8 Aug 2022 23:05:26 -0500 Subject: [PATCH 3/3] Change *i* to *ip* --- Doc/library/bisect.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Doc/library/bisect.rst b/Doc/library/bisect.rst index cdd8ae09b4acc2..76045ea511a5e7 100644 --- a/Doc/library/bisect.rst +++ b/Doc/library/bisect.rst @@ -36,9 +36,9 @@ The following functions are provided: any existing entries. The return value is suitable for use as the first parameter to ``list.insert()`` assuming that *a* is already sorted. - The returned insertion point *i* partitions the array *a* into two - slices such that ``all(elem < x for elem in a[lo : i])`` is true for the - left slice and ``all(elem >= x for elem in a[i : hi])`` is true for the + The returned insertion point *ip* partitions the array *a* into two + slices such that ``all(elem < x for elem in a[lo : ip])`` is true for the + left slice and ``all(elem >= x for elem in a[ip : hi])`` is true for the right slice. *key* specifies a :term:`key function` of one argument that is used to @@ -58,9 +58,9 @@ The following functions are provided: Similar to :func:`bisect_left`, but returns an insertion point which comes after (to the right of) any existing entries of *x* in *a*. - The returned insertion point *i* partitions the array *a* into two slices - such that ``all(elem <= x for elem in a[lo : i])`` is true for the left slice and - ``all(elem > x for elem in a[i : hi])`` is true for the right slice. + The returned insertion point *ip* partitions the array *a* into two slices + such that ``all(elem <= x for elem in a[lo : ip])`` is true for the left slice and + ``all(elem > x for elem in a[ip : hi])`` is true for the right slice. .. versionchanged:: 3.10 Added the *key* parameter.