bisect — Algoritmo de bisección de arreglos

Código fuente: Lib/bisect.py


Este módulo brinda soporte para mantener una lista ordenada sin tener que reordenar la lista tras cada nueva inserción. Para listas largas de elementos que tienen operaciones de comparación costosas, será una mejora respecto a la estrategia más habitual. El módulo se llama bisect porque usa un algoritmo de bisección básico para lograr su objetivo. El código fuente puede ser útil como ejemplo del algoritmo en funcionamiento (¡las precondiciones ya están bien de antemano!).

Las siguientes funciones están disponibles:

bisect.bisect_left(a, x, lo=0, hi=len(a), *, key=None)

Ubicar el punto de inserción para x en a para mantener el ordenamiento. Los parámetros lo (inferior) y hi (superior) pueden utilizarse para especificar un subconjunto (subset) de la lista que debería considerarse. Por defecto, se utiliza la lista completa. Si x ya está presente en a, el punto de inserción será antes (a la izquierda de) cualquier elemento existente. El valor de retorno es adecuado para que se utilice como primer parámetro para list.insert(), suponiendo que a ya está ordenada.

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 key function of one argument that is used to extract a comparison key from each input element. The default value is None (compare the elements directly).

Distinto en la versión 3.10: Added the key parameter.

bisect.bisect_right(a, x, lo=0, hi=len(a), *, key=None)
bisect.bisect(a, x, lo=0, hi=len(a))

Similar a bisect_left(), pero retorna un punto de inserción que viene después (a la derecha de) cualquier entrada de x en 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 key function of one argument that is used to extract a comparison key from each input element. The default value is None (compare the elements directly).

Distinto en la versión 3.10: Added the key parameter.

bisect.insort_left(a, x, lo=0, hi=len(a), *, key=None)

Insert x in a in sorted order.

key specifies a key function of one argument that is used to extract a comparison key from each input element. The default value is None (compare the elements directly).

This function first runs bisect_left() to locate an insertion point. Next, it runs the insert() method on a to insert x at the appropriate position to maintain sort order.

Keep in mind that the O(log n) search is dominated by the slow O(n) insertion step.

Distinto en la versión 3.10: Added the key parameter.

bisect.insort_right(a, x, lo=0, hi=len(a), *, key=None)
bisect.insort(a, x, lo=0, hi=len(a))

Similar a insort_left(), pero inserta x en a después de cualquier entrada x existente.

key specifies a key function of one argument that is used to extract a comparison key from each input element. The default value is None (compare the elements directly).

This function first runs bisect_right() to locate an insertion point. Next, it runs the insert() method on a to insert x at the appropriate position to maintain sort order.

Keep in mind that the O(log n) search is dominated by the slow O(n) insertion step.

Distinto en la versión 3.10: Added the key parameter.

Performance Notes

When writing time sensitive code using bisect() and insort(), keep these thoughts in mind:

  • Bisection is effective for searching ranges of values. For locating specific values, dictionaries are more performant.

  • The insort() functions are O(n) because the logarithmic search step is dominated by the linear time insertion step.

  • The search functions are stateless and discard key function results after they are used. Consequently, if the search functions are used in a loop, the key function may be called again and again on the same array elements. If the key function isn’t fast, consider wrapping it with functools.cache() to avoid duplicate computations. Alternatively, consider searching an array of precomputed keys to locate the insertion point (as shown in the examples section below).

Ver también

  • Sorted Collections is a high performance module that uses bisect to managed sorted collections of data.

  • The SortedCollection recipe 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.

Búsqueda en listas ordenadas

Las funciones anteriores bisect() son útiles para encontrar puntos de inserción, pero pueden resultar difíciles o engorrosas para tareas de búsqueda habituales. Las cinco funciones que siguen muestran cómo convertirlas en búsquedas estándar para listas ordenadas:

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

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

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]
    raise ValueError

Examples

La función bisect() puede ser útil para búsquedas en tablas numéricas. Este ejemplo utiliza bisect() para buscar una calificación de un examen dada por una letra, basada en un conjunto de marcas numéricas ordenadas: 90 o más es una “A”, de 80 a 89 es una “B”, y así sucesivamente:

>>> def grade(score, breakpoints=[60, 70, 80, 90], grades='FDCBA'):
...     i = bisect(breakpoints, score)
...     return grades[i]
...
>>> [grade(score) for score in [33, 99, 77, 70, 89, 90, 100]]
['F', 'A', 'C', 'C', 'B', 'A', 'A']

One technique to avoid repeated calls to a key function is to search a list of precomputed keys to find the index of a record:

>>> data = [('red', 5), ('blue', 1), ('yellow', 8), ('black', 0)]
>>> data.sort(key=lambda r: r[1])       # Or use operator.itemgetter(1).
>>> keys = [r[1] for r in data]         # Precompute a list of keys.
>>> data[bisect_left(keys, 0)]
('black', 0)
>>> data[bisect_left(keys, 1)]
('blue', 1)
>>> data[bisect_left(keys, 5)]
('red', 5)
>>> data[bisect_left(keys, 8)]
('yellow', 8)