Skip to content

Commit 7c8626a

Browse files
authored
Improvements to the bisect docs (GH-95807)
1 parent 8a55e2f commit 7c8626a

File tree

1 file changed

+19
-19
lines changed

1 file changed

+19
-19
lines changed

Doc/library/bisect.rst

Lines changed: 19 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,16 @@
1313

1414
This module provides support for maintaining a list in sorted order without
1515
having to sort the list after each insertion. For long lists of items with
16-
expensive comparison operations, this can be an improvement over the more common
17-
approach. The module is called :mod:`bisect` because it uses a basic bisection
18-
algorithm to do its work. The source code may be most useful as a working
19-
example of the algorithm (the boundary conditions are already right!).
16+
expensive comparison operations, this can be an improvement over
17+
linear searches or frequent resorting.
18+
19+
The module is called :mod:`bisect` because it uses a basic bisection
20+
algorithm to do its work. Unlike other bisection tools that search for a
21+
specific value, the functions in this module are designed to locate an
22+
insertion point. Accordingly, the functions never call an :meth:`__eq__`
23+
method to determine whether a value has been found. Instead, the
24+
functions only call the :meth:`__lt__` method and will return an insertion
25+
point between values in an array.
2026

2127
The following functions are provided:
2228

@@ -30,16 +36,17 @@ The following functions are provided:
3036
any existing entries. The return value is suitable for use as the first
3137
parameter to ``list.insert()`` assuming that *a* is already sorted.
3238

33-
The returned insertion point *i* partitions the array *a* into two halves so
34-
that ``all(val < x for val in a[lo : i])`` for the left side and
35-
``all(val >= x for val in a[i : hi])`` for the right side.
39+
The returned insertion point *ip* partitions the array *a* into two
40+
slices such that ``all(elem < x for elem in a[lo : ip])`` is true for the
41+
left slice and ``all(elem >= x for elem in a[ip : hi])`` is true for the
42+
right slice.
3643

3744
*key* specifies a :term:`key function` of one argument that is used to
3845
extract a comparison key from each element in the array. To support
3946
searching complex records, the key function is not applied to the *x* value.
4047

41-
If *key* is ``None``, the elements are compared directly with no
42-
intervening function call.
48+
If *key* is ``None``, the elements are compared directly and
49+
no key function is called.
4350

4451
.. versionchanged:: 3.10
4552
Added the *key* parameter.
@@ -51,16 +58,9 @@ The following functions are provided:
5158
Similar to :func:`bisect_left`, but returns an insertion point which comes
5259
after (to the right of) any existing entries of *x* in *a*.
5360

54-
The returned insertion point *i* partitions the array *a* into two halves so
55-
that ``all(val <= x for val in a[lo : i])`` for the left side and
56-
``all(val > x for val in a[i : hi])`` for the right side.
57-
58-
*key* specifies a :term:`key function` of one argument that is used to
59-
extract a comparison key from each element in the array. To support
60-
searching complex records, the key function is not applied to the *x* value.
61-
62-
If *key* is ``None``, the elements are compared directly with no
63-
intervening function call.
61+
The returned insertion point *ip* partitions the array *a* into two slices
62+
such that ``all(elem <= x for elem in a[lo : ip])`` is true for the left slice and
63+
``all(elem > x for elem in a[ip : hi])`` is true for the right slice.
6464

6565
.. versionchanged:: 3.10
6666
Added the *key* parameter.

0 commit comments

Comments
 (0)