"bisect" --- 配列二分法アルゴリズム
***********************************

**ソースコード:** Lib/bisect.py

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

このモジュールは、挿入の度にリストをソートすることなく、リストをソート
された順序に保つことをサポートします。大量の比較操作を伴うような、アイ
テムがたくさんあるリストでは、より一般的なアプローチに比べて、パフォー
マンスが向上します。動作に基本的な二分法アルゴリズムを使っているので、
"bisect" と呼ばれています。ソースコードはこのアルゴリズムの実例として
一番役に立つかもしれません (境界条件はすでに正しいです!)。

次の関数が用意されています:

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

   ソートされた順序を保ったまま *x* を *a* に挿入できる点を探し当てま
   す。リストの中から検索する部分集合を指定するには、パラメータの *lo*
   と *hi* を使います。デフォルトでは、リスト全体が使われます。*x* が
   すでに *a* に含まれている場合、挿入点は既存のどのエントリーよりも前
   (左)になります。戻り値は、"list.insert()" の第一引数として使うのに
   適しています。*a* はすでにソートされているものとします。

   返された挿入点 *i* は、配列 *a* を二つに分け、"all(val < x for val
   in a[lo : i])" が左側に、"all(val >= x for val in a[i : hi])" が右
   側になるようにします。

   *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.

   バージョン 3.10 で変更: *key* パラメータが追加されました。

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

   "bisect_left()" と似ていますが、 *a* に含まれる *x* のうち、どのエ
   ントリーよりも後ろ(右)にくるような挿入点を返します。

   返された挿入点 *i* は、配列 *a* を二つに分け、"all(val <= x for val
   in a[lo : i])" が左側に、"all(val > x for val in a[i : hi])" が右側
   になるようにします。

   *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.

   バージョン 3.10 で変更: *key* パラメータが追加されました。

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

   *x* を *a* にソート順で挿入します。

   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.

   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.

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

   バージョン 3.10 で変更: *key* パラメータが追加されました。

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

   "insort_left()" と似ていますが、 *a* に含まれる *x* のうち、どのエ
   ントリーよりも後ろに *x* を挿入します。

   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.

   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.

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

   バージョン 3.10 で変更: *key* パラメータが追加されました。


パフォーマンスに関するメモ
==========================

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

参考:

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

  * bisect を利用して、直接の探索ができ、キー関数をサポートする、完全
    な機能を持つコレクションクラスを組み立てる SortedCollection recipe
    。キーは、探索中に不必要な呼び出しをさせないために、予め計算してお
    きます。


ソート済みリストの探索
======================

上記の "bisect()" 関数群は挿入点を探索するのには便利ですが、普通の探索
タスクに使うのはトリッキーだったり不器用だったりします。以下の 5 関数
は、これらをどのように標準の探索やソート済みリストに変換するかを説明し
ます:

   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


使用例
======

"bisect()" 関数は数値テーブルの探索に役に立ちます。この例では、
"bisect()" を使って、(たとえば)順序のついた数値の区切り点の集合に基づ
いて、試験の成績の等級を表す文字を調べます。区切り点は 90 以上は 'A'、
80 から 89 は 'B'、などです:

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