Doc/lib/libbisect.tex

   1 \section{\module{bisect} ---
   2          Array bisection algorithm}
   3
   4 \declaremodule{standard}{bisect}
   5 \modulesynopsis{Array bisection algorithms for binary searching.}
   6 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
   7 % LaTeX produced by Fred L. Drake, Jr. <fdrake@acm.org>, with an
   8 % example based on the PyModules FAQ entry by Aaron Watters
   9 % <arw@pythonpros.com>.
  10
  11
  12 This module provides support for maintaining a list in sorted order
  13 without having to sort the list after each insertion.  For long lists
  14 of items with expensive comparison operations, this can be an
  15 improvement over the more common approach.  The module is called
  16 \module{bisect} because it uses a basic bisection algorithm to do its
  17 work.  The source code may be most useful as a working example of the
  18 algorithm (i.e., the boundary conditions are already right!).
  19
  20 The following functions are provided:
  21
  22 \begin{funcdesc}{bisect_left}{list, item\optional{, lo\optional{, hi}}}
  23   Locate the proper insertion point for \var{item} in \var{list} to
  24   maintain sorted order.  The parameters \var{lo} and \var{hi} may be
  25   used to specify a subset of the list which should be considered; by
  26   default the entire list is used.  If \var{item} is already present
  27   in \var{list}, the insertion point will be before (to the left of)
  28   any existing entries.  The return value is suitable for use as the
  29   first parameter to \code{\var{list}.insert()}.  This assumes that
  30   \var{list} is already sorted.
  31 \versionadded{2.1}
  32 \end{funcdesc}
  33
  34 \begin{funcdesc}{bisect_right}{list, item\optional{, lo\optional{, hi}}}
  35   Similar to \function{bisect_left()}, but returns an insertion point
  36   which comes after (to the right of) any existing entries of
  37   \var{item} in \var{list}.
  38 \versionadded{2.1}
  39 \end{funcdesc}
  40
  41 \begin{funcdesc}{bisect}{\unspecified}
  42   Alias for \function{bisect_right()}.
  43 \end{funcdesc}
  44
  45 \begin{funcdesc}{insort_left}{list, item\optional{, lo\optional{, hi}}}
  46   Insert \var{item} in \var{list} in sorted order.  This is equivalent
  47   to \code{\var{list}.insert(bisect.bisect_left(\var{list}, \var{item},
  48   \var{lo}, \var{hi}), \var{item})}.  This assumes that \var{list} is
  49   already sorted.
  50 \versionadded{2.1}
  51 \end{funcdesc}
  52
  53 \begin{funcdesc}{insort_right}{list, item\optional{, lo\optional{, hi}}}
  54   Similar to \function{insort_left()}, but inserting \var{item} in
  55   \var{list} after any existing entries of \var{item}.
  56 \versionadded{2.1}
  57 \end{funcdesc}
  58
  59 \begin{funcdesc}{insort}{\unspecified}
  60   Alias for \function{insort_right()}.
  61 \end{funcdesc}
  62
  63
  64 \subsection{Example}
  65 \nodename{bisect-example}
  66
  67 The \function{bisect()} function is generally useful for categorizing
  68 numeric data.  This example uses \function{bisect()} to look up a
  69 letter grade for an exam total (say) based on a set of ordered numeric
  70 breakpoints: 85 and up is an `A', 75..84 is a `B', etc.
  71
  72 \begin{verbatim}
  73 >>> grades = "FEDCBA"
  74 >>> breakpoints = [30, 44, 66, 75, 85]
  75 >>> from bisect import bisect
  76 >>> def grade(total):
  77 ...           return grades[bisect(breakpoints, total)]
  78 ...
  79 >>> grade(66)
  80 'C'
  81 >>> map(grade, [33, 99, 77, 44, 12, 88])
  82 ['E', 'A', 'B', 'D', 'F', 'A']
  83 \end{verbatim}