"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* specifies a *key function* of one argument that is used to
   extract a comparison key from each element in the array.  To
   support searching complex records, the key function is not applied
   to the *x* value.

   If *key* is "None", the elements are compared directly with no
   intervening function call.

   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), *, key=None)

   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* specifies a *key function* of one argument that is used to
   extract a comparison key from each element in the array.  To
   support searching complex records, the key function is not applied
   to the *x* value.

   If *key* is "None", the elements are compared directly with no
   intervening function call.

   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.

   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.

   To support inserting records in a table, the *key* function (if
   any) is applied to *x* for the search step but not for the
   insertion step.

   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), *, key=None)

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

   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.

   To support inserting records in a table, the *key* function (if
   any) is applied to *x* for the search step but not for the
   insertion step.

   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 is a high performance module that uses *bisect*
    to managed sorted collections of data.

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

The "bisect()" and "insort()" functions also work with lists of
tuples.  The *key* argument can serve to extract the field used for
ordering records in a table:

   >>> from collections import namedtuple
   >>> from operator import attrgetter
   >>> from bisect import bisect, insort
   >>> from pprint import pprint

   >>> Movie = namedtuple('Movie', ('name', 'released', 'director'))

   >>> movies = [
   ...     Movie('Jaws', 1975, 'Speilberg'),
   ...     Movie('Titanic', 1997, 'Cameron'),
   ...     Movie('The Birds', 1963, 'Hitchcock'),
   ...     Movie('Aliens', 1986, 'Scott')
   ... ]

   >>> # Find the first movie released after 1960
   >>> by_year = attrgetter('released')
   >>> movies.sort(key=by_year)
   >>> movies[bisect(movies, 1960, key=by_year)]
   Movie(name='The Birds', released=1963, director='Hitchcock')

   >>> # Insert a movie while maintaining sort order
   >>> romance = Movie('Love Story', 1970, 'Hiller')
   >>> insort(movies, romance, key=by_year)
   >>> pprint(movies)
   [Movie(name='The Birds', released=1963, director='Hitchcock'),
    Movie(name='Love Story', released=1970, director='Hiller'),
    Movie(name='Jaws', released=1975, director='Speilberg'),
    Movie(name='Aliens', released=1986, director='Scott'),
    Movie(name='Titanic', released=1997, director='Cameron')]

If the key function is expensive, it is possible to avoid repeated
function calls by searching 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)
