13
13
14
14
This module provides support for maintaining a list in sorted order without
15
15
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.
20
26
21
27
The following functions are provided:
22
28
@@ -30,16 +36,17 @@ The following functions are provided:
30
36
any existing entries. The return value is suitable for use as the first
31
37
parameter to ``list.insert() `` assuming that *a * is already sorted.
32
38
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.
36
43
37
44
*key * specifies a :term: `key function ` of one argument that is used to
38
45
extract a comparison key from each element in the array. To support
39
46
searching complex records, the key function is not applied to the *x * value.
40
47
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 .
43
50
44
51
.. versionchanged :: 3.10
45
52
Added the *key * parameter.
@@ -51,16 +58,9 @@ The following functions are provided:
51
58
Similar to :func: `bisect_left `, but returns an insertion point which comes
52
59
after (to the right of) any existing entries of *x * in *a *.
53
60
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.
64
64
65
65
.. versionchanged :: 3.10
66
66
Added the *key * parameter.
0 commit comments