# `bisect` — Algoritmo de bisseção de vetor

Código-fonte: Lib/bisect.py

Este módulo fornece suporte para manter uma lista em ordem de classificação sem ter que classificar a lista após cada inserção. Para longas listas de itens com operações de comparação custosas, isso pode ser uma melhoria em relação à abordagem mais comum. O módulo é denominado `bisect` porque usa um algoritmo de bisseção básico para fazer seu trabalho. O código-fonte pode ser mais útil como um exemplo funcional de algoritmo (as condições fronteiriças já estão certas!).

As seguintes funções são fornecidas:

`bisect.``bisect_left`(a, x, lo=0, hi=len(a))

  Localiza o ponto de inserção de x em a para manter a ordem de classificação. Os parâmetros lo e hi podem ser usados para especificar um subconjunto da lista que deve ser considerado; por padrão, toda a lista é usada. Se x já estiver presente em a, o ponto de inserção estará antes (à esquerda) de qualquer entrada existente. O valor de retorno é adequado para uso como o primeiro parâmetro para `list.insert()` supondo que a já esteja ordenado.

  O ponto de inserção retornado i particiona o vetor a em duas metades de modo que `all(val < x for val in a[lo:i])` para o lado esquerdo e `all(val >= x for val in a[i:hi])` para o lado direito.

`bisect.``bisect_right`(a, x, lo=0, hi=len(a))
`bisect.``bisect`(a, x, lo=0, hi=len(a))

  Semelhante a `bisect_left()`, mas retorna um ponto de inserção que vem depois (à direita de) qualquer entrada existente de x em a.

  O ponto de inserção retornado i particiona o vetor a em duas metades de modo que `all(val <= x for val in a[lo:i])` para o lado esquerdo e `all(val > x for val in a[i:hi])` para o lado direito.

`bisect.``insort_left`(a, x, lo=0, hi=len(a))

  Insere x em a na ordem de classificação. Isso é equivalente a `a.insert(bisect.bisect_left(a, x, lo, hi), x)` supondo que a já esteja ordenado. Lembre-se de que a pesquisa O(log n) é dominada pela lenta etapa de inserção O(n).

`bisect.``insort_right`(a, x, lo=0, hi=len(a))
`bisect.``insort`(a, x, lo=0, hi=len(a))

  Semelhante a `insort_left()`, mas inserindo x em a após qualquer entrada existente de x.

Ver também

Receita de SortedCollection que usa bisect para construir uma classe de coleção completa com métodos de pesquisa diretos e suporte para uma função chave. As chaves são pré-calculadas para economizar em chamadas desnecessárias para a função chave durante as pesquisas.

## Buscando em listas ordenadas

As funções `bisect()` acima são úteis para encontrar pontos de inserção, mas podem ser complicadas ou difíceis de usar para tarefas comuns de pesquisa. As cinco funções a seguir mostram como transformá-las nas pesquisas padrão 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

## Outros exemplos

A função `bisect()` pode ser útil para pesquisas em tabelas numéricas. Este exemplo usa `bisect()` para pesquisar uma nota em letra para uma pontuação de exame (digamos) com base em um conjunto de pontos de interrupção numéricos ordenados: 90 e acima é um “A”, 80 a 89 é um “B” e por aí vai:

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

Ao contrário da função `sorted()`, não faz sentido que as funções `bisect()` tenham argumentos key ou reversed porque isso levaria a um design ineficiente (chamadas sucessivas para funções bisect não “lembrariam” de todas as pesquisas de chave anteriores).

Em vez disso, é melhor pesquisar uma lista de chaves pré-computadas para encontrar o índice do registro em questão:

    >>> data = [('red', 5), ('blue', 1), ('yellow', 8), ('black', 0)]
    >>> data.sort(key=lambda r: r[1])
    >>> keys = [r[1] for r in data]         # precomputed 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)