Nota

¡Ayúdanos a traducir la documentación oficial de Python al Español! Puedes encontrar más información en Como contribuir. Ayuda a acercar Python a más personas de habla hispana.

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.

El punto de inserción retornado i divide el arreglo a en dos mitades, de modo que all(val < x for val in a[lo : i]) para el lado izquierdo y all(val >= x for val in a[i : hi]) para el lado derecho.

key especifica un key function de un argumento que se utiliza para extraer una clave de comparación de cada elemento de entrada. El valor predeterminado es None (compare los elementos directamente).

Distinto en la versión 3.10: Se agregó el parámetro key.

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.

El punto de inserción retornado i divide el arreglo a en dos mitades, de modo que all(val <= x for val in a[lo : i]) para el lado izquierdo y all(val > x for val in a[i : hi]) para el lado derecho.

key especifica un key function de un argumento que se utiliza para extraer una clave de comparación de cada elemento de entrada. El valor predeterminado es None (compare los elementos directamente).

Distinto en la versión 3.10: Se agregó el parámetro key.

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

Inserte x en a en orden ordenado.

key especifica un key function de un argumento que se utiliza para extraer una clave de comparación de cada elemento de entrada. El valor predeterminado es None (compare los elementos directamente).

Esta función primero ejecuta bisect_left() para localizar un punto de inserción. A continuación, ejecuta el método insert() en a para insertar x en la posición adecuada para mantener el orden de clasificación.

Tenga en cuenta que la búsqueda O(log n) está dominada por el lento paso de inserción O (n).

Distinto en la versión 3.10: Se agregó el parámetro key.

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 especifica un key function de un argumento que se utiliza para extraer una clave de comparación de cada elemento de entrada. El valor predeterminado es None (compare los elementos directamente).

Esta función primero ejecuta bisect_right() para localizar un punto de inserción. A continuación, ejecuta el método insert() en a para insertar x en la posición adecuada para mantener el orden de clasificación.

Tenga en cuenta que la búsqueda O(log n) está dominada por el lento paso de inserción O (n).

Distinto en la versión 3.10: Se agregó el parámetro key.

Notas de rendimiento

Al escribir código sensible al tiempo usando bisect() y insort(), tenga en cuenta estos pensamientos:

  • La bisección es eficaz para buscar rangos de valores. Para localizar valores específicos, los diccionarios son más eficaces.

  • Las funciones insort() son O(n) porque el paso de búsqueda logarítmica está dominado por el paso de inserción de tiempo lineal.

  • Las funciones de búsqueda no tienen estado y descartan los resultados de las funciones clave después de su uso. En consecuencia, si las funciones de búsqueda se utilizan en un bucle, la función clave se puede llamar una y otra vez en los mismos elementos del arreglo. Si la función clave no es rápida, considere envolverla con functools.cache() para evitar cálculos duplicados. Alternativamente, considere buscar un arreglo de claves precalculadas para ubicar el punto de inserción (como se muestra en la sección de ejemplos a continuación).

Ver también

  • Sorted Collections es un módulo de alto rendimiento que utiliza bisect para gestionar colecciones de datos ordenadas.

  • El SortedCollection recipe usa bisect para construir una clase de colección con todas las funciones con métodos de búsqueda sencillos y soporte para una función clave. Las teclas se calculan previamente para ahorrar llamadas innecesarias a la función de la tecla durante las búsquedas.

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

Ejemplos

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']

Una técnica para evitar llamadas repetidas a una función de tecla es buscar en una lista de teclas precalculadas para encontrar el índice de un registro:

>>> 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)