mirror of https://github.com/python/cpython
Clean-up bisect docs.
* Document the post conditions for bisect_left() and bisect_right(). * Fix the grades example to use more obvious breakpoints and to use a list comprehension instead of map() which returns an iterator in Py3.x. * Improve and expand the examples of searching sorted lists. * Issue 4356 -- move up reference to the SortedCollection recipe.
This commit is contained in:
Raymond Hettinger
parent
49203dc9f2
commit
20933e08b1
|
|
@ -4,6 +4,7 @@
|
|||
.. module:: bisect
|
||||
:synopsis: Array bisection algorithms for binary searching.
|
||||
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
|
||||
.. sectionauthor:: Raymond Hettinger <python at rcn.com>
|
||||
.. example based on the PyModules FAQ entry by Aaron Watters <arw@pythonpros.com>
|
||||
|
||||
This module provides support for maintaining a list in sorted order without
|
||||
|
|
@ -18,13 +19,16 @@ The following functions are provided:
|
|||
|
||||
.. function:: bisect_left(a, x, lo=0, hi=len(a))
|
||||
|
||||
Locate the proper insertion point for *x* in *a* to maintain sorted order.
|
||||
Locate the insertion point for *x* in *a* to maintain sorted order.
|
||||
The parameters *lo* and *hi* may be used to specify a subset of the list
|
||||
which should be considered; by default the entire list is used. If *x* is
|
||||
already present in *a*, the insertion point will be before (to the left of)
|
||||
any existing entries. The return value is suitable for use as the first
|
||||
parameter to ``list.insert()``. This assumes that *a* is already sorted.
|
||||
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.
|
||||
|
||||
.. function:: bisect_right(a, x, lo=0, hi=len(a))
|
||||
bisect(a, x, lo=0, hi=len(a))
|
||||
|
|
@ -32,16 +36,16 @@ 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.
|
||||
|
||||
.. function:: insort_left(a, x, lo=0, hi=len(a))
|
||||
|
||||
Insert *x* in *a* in sorted order. This is equivalent to
|
||||
``a.insert(bisect.bisect_left(a, x, lo, hi), x)``. This assumes that *a* is
|
||||
already sorted.
|
||||
|
||||
Also note that while the fast search step is O(log n), the slower insertion
|
||||
step is O(n), so the overall operation is slow.
|
||||
|
||||
``a.insert(bisect.bisect_left(a, x, lo, hi), x)`` assuming that *a* is
|
||||
already sorted. Keep in mind that the O(log n) search is dominated by
|
||||
the slow O(n) insertion step.
|
||||
|
||||
.. function:: insort_right(a, x, lo=0, hi=len(a))
|
||||
insort(a, x, lo=0, hi=len(a))
|
||||
|
|
@ -49,71 +53,75 @@ The following functions are provided:
|
|||
Similar to :func:`insort_left`, but inserting *x* in *a* after any existing
|
||||
entries of *x*.
|
||||
|
||||
Also note that while the fast search step is O(log n), the slower insertion
|
||||
step is O(n), so the overall operation is slow.
|
||||
.. seealso::
|
||||
|
||||
`SortedCollection recipe
|
||||
<http://code.activestate.com/recipes/577197-sortedcollection/>`_ that uses
|
||||
bisect to build a full-featured collection class with straight-forward search
|
||||
methods and support for a key-function. The keys are precomputed to save
|
||||
unnecessary calls to the key function during searches.
|
||||
|
||||
|
||||
Searching Sorted Lists
|
||||
----------------------
|
||||
|
||||
The above :func:`bisect` functions are useful for finding insertion points, but
|
||||
can be tricky or awkward to use for common searching tasks. The following three
|
||||
The above :func:`bisect` functions are useful for finding insertion points but
|
||||
can be tricky or awkward to use for common searching tasks. The following five
|
||||
functions show how to transform them into the standard lookups for sorted
|
||||
lists::
|
||||
|
||||
def find(a, key):
|
||||
'''Find leftmost item exact equal to the key.
|
||||
Raise ValueError if no such item exists.
|
||||
def index(a, x):
|
||||
'Locate the leftmost value exactly equal to x'
|
||||
i = bisect_left(a, x)
|
||||
if i != len(a) and a[i] == x:
|
||||
return i
|
||||
raise ValueError
|
||||
|
||||
'''
|
||||
i = bisect_left(a, key)
|
||||
if i < len(a) and a[i] == key:
|
||||
def find_lt(a, x):
|
||||
'Find rightmost value less than x'
|
||||
i = bisect_left(a, x)
|
||||
if i:
|
||||
return a[i-1]
|
||||
raise ValueError
|
||||
|
||||
def find_le(a, x):
|
||||
'Find rightmost value less than or equal to x'
|
||||
i = bisect_right(a, x)
|
||||
if i:
|
||||
return a[i-1]
|
||||
raise ValueError
|
||||
|
||||
def find_gt(a, x):
|
||||
'Find leftmost value greater than x'
|
||||
i = bisect_right(a, x)
|
||||
if i != len(a):
|
||||
return a[i]
|
||||
raise ValueError('No item found with key equal to: %r' % (key,))
|
||||
raise ValueError
|
||||
|
||||
def find_le(a, key):
|
||||
'''Find largest item less-than or equal to key.
|
||||
Raise ValueError if no such item exists.
|
||||
If multiple keys are equal, return the leftmost.
|
||||
|
||||
'''
|
||||
i = bisect_left(a, key)
|
||||
if i < len(a) and a[i] == key:
|
||||
def find_ge(a, x):
|
||||
'Find leftmost item greater than or equal to x'
|
||||
i = bisect_left(a, x)
|
||||
if i != len(a):
|
||||
return a[i]
|
||||
if i == 0:
|
||||
raise ValueError('No item found with key at or below: %r' % (key,))
|
||||
return a[i-1]
|
||||
raise ValueError
|
||||
|
||||
def find_ge(a, key):
|
||||
'''Find smallest item greater-than or equal to key.
|
||||
Raise ValueError if no such item exists.
|
||||
If multiple keys are equal, return the leftmost.
|
||||
|
||||
'''
|
||||
i = bisect_left(a, key)
|
||||
if i == len(a):
|
||||
raise ValueError('No item found with key at or above: %r' % (key,))
|
||||
return a[i]
|
||||
|
||||
Other Examples
|
||||
--------------
|
||||
|
||||
.. _bisect-example:
|
||||
|
||||
The :func:`bisect` function is generally useful for categorizing numeric data.
|
||||
This example uses :func:`bisect` to look up a letter grade for an exam total
|
||||
(say) based on a set of ordered numeric breakpoints: 85 and up is an 'A', 75..84
|
||||
is a 'B', etc.
|
||||
The :func:`bisect` function can be useful for numeric table lookups. This
|
||||
example uses :func:`bisect` to look up a letter grade for an exam score (say)
|
||||
based on a set of ordered numeric breakpoints: 90 and up is an 'A', 80 to 89 is
|
||||
a 'B', and so on::
|
||||
|
||||
>>> grades = "FEDCBA"
|
||||
>>> breakpoints = [30, 44, 66, 75, 85]
|
||||
>>> from bisect import bisect
|
||||
>>> def grade(total):
|
||||
... return grades[bisect(breakpoints, total)]
|
||||
>>> def grade(score, breakpoints=[60, 70, 80, 90], grades='FDCBA'):
|
||||
... i = bisect(breakpoints, score)
|
||||
... return grades[i]
|
||||
...
|
||||
>>> grade(66)
|
||||
'C'
|
||||
>>> map(grade, [33, 99, 77, 44, 12, 88])
|
||||
['E', 'A', 'B', 'D', 'F', 'A']
|
||||
>>> [grade(score) for score in [33, 99, 77, 70, 89, 90, 100]]
|
||||
['F', 'A', 'C', 'C', 'B', 'A', 'A']
|
||||
|
||||
Unlike the :func:`sorted` function, it does not make sense for the :func:`bisect`
|
||||
functions to have *key* or *reversed* arguments because that would lead to an
|
||||
|
|
@ -135,9 +143,3 @@ of the record in question::
|
|||
>>> data[bisect_left(keys, 8)]
|
||||
('yellow', 8)
|
||||
|
||||
.. seealso::
|
||||
|
||||
`SortedCollection recipe
|
||||
<http://code.activestate.com/recipes/577197-sortedcollection/>`_ that
|
||||
encapsulates precomputed keys, allowing straight-forward insertion and
|
||||
searching using a *key* function.
|
||||
|
|
|
|||
Loading…
Reference in New Issue