"bisect" — Algorithme de bissection de listes
*********************************************

**Code source :** Lib/bisect.py

======================================================================

Ce module fournit des outils pour maintenir une liste triée sans avoir
à la trier à chaque insertion. Il pourrait être plus rapide que
l'approche classique pour de longues listes d'éléments dont les
opérations de comparaison sont lourdes. Le module se nomme "bisect"
car il utilise une approche simple par bissection. Si vous voulez un
exemple de cet algorithme, le mieux est d'aller lire le code source de
ce module (les conditions sur les limites y étant justes !).

Les fonctions suivantes sont fournies :

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

   Trouve le point d'insertion de *x* dans *a* permettant de conserver
   l'ordre. Les paramètres *lo* et *hi* permettent de limiter les
   emplacements à vérifier dans la liste, par défaut toute la liste
   est utilisée. Si *x* est déjà présent dans *a*, le point
   d'insertion proposé sera avant (à gauche) de l'entrée existante. Si
   *a* est déjà triée, la valeur renvoyée peut directement être
   utilisée comme premier paramètre de "list.insert()".

   Le point d'insertion renvoyé, *i*, coupe la liste *a* en deux
   moitiés telles que, pour la moitié de gauche : "all(val < x for val
   in a[lo:i])", et pour la partie de droite : "all(val >= x for val
   in a[i:hi])".

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

   Semblable à "bisect_left()", mais renvoie un point d'insertion
   après (à droite) d'une potentielle entrée existante valant *x* dans
   *a*.

   Le point d'insertion renvoyé, *i*, coupe la liste *a* en deux
   moitiés telles que, pour la moitié de gauche : "all(val <= x for
   val in a[lo:i])" et pour la moitié de droite : "all(val > x for val
   in a[i:hi])".

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

   Insère *x* dans *a* en conservant le tri.  C'est l'équivalent de
   "a.insert(bisect.bisect_left(a, x, lo, hi), x)", tant que *a* est
   déjà triée. Gardez en tête que bien que la recherche ne coûte que
   O(log n), l'insertion coûte O(n).

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

   Similaire à "insort_left()", mais en insérant *x* dans *a* après
   une potentielle entrée existante égale à *x*.

Voir aussi:

  SortedCollection recipe utilise le module *bisect* pour construire
  une classe collection exposant des méthodes de recherches naturelles
  et gérant une fonction clef.  Les clefs sont pré-calculées pour
  économiser des appels inutiles à la fonction clef durant les
  recherches.


Chercher dans des listes triées
===============================

Les fonctions "bisect()" ci-dessus sont utiles pour insérer des
éléments, mais peuvent être étranges et peu naturelles à utiliser pour
rechercher des éléments. Les cinq fonctions suivantes montrent comment
les transformer en recherche plus classique pour les listes triées :

   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


Autres Exemples
===============

La fonction "bisect()" peut être utile pour des recherches dans des
tableaux de nombres. Cet exemple utilise "bisect()" pour rechercher la
note (sous forme de lettre) correspondant à un note sous forme de
points, en se basant sur une échelle prédéfinie : plus de 90 vaut 'A',
de 80 à 89 vaut 'B', etc… :

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

Contrairement à la fonction "sorted()", ça n'aurait pas de sens pour
la fonction "bisect()" d'avoir un paramètre *key* ou *reversed*, qui
conduiraient à une utilisation inefficace (des appels successifs à la
fonction *bisect* n'auraient aucun moyen de se "souvenir" des
recherches de clef précédentes).

Il est préférable d'utiliser une liste de clefs pré-calculée pour
chercher l'index de l'enregistrement en question :

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