mirror of
https://github.com/python/cpython.git
synced 2025-10-31 02:15:10 +00:00
91f2f26d75
translation more difficult, as well as reading the English more difficult for non-native speakers.
83 lines
3 KiB
TeX
83 lines
3 KiB
TeX
\section{\module{bisect} ---
|
|
Array bisection algorithm}
|
|
|
|
\declaremodule{standard}{bisect}
|
|
\modulesynopsis{Array bisection algorithms for binary searching.}
|
|
\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
|
|
% LaTeX produced by Fred L. Drake, Jr. <fdrake@acm.org>, with an
|
|
% example based on the PyModules FAQ entry by Aaron Watters
|
|
% <arw@pythonpros.com>.
|
|
|
|
|
|
This module provides support for maintaining a list in sorted order
|
|
without having to sort the list after each insertion. For long lists
|
|
of items with expensive comparison operations, this can be an
|
|
improvement over the more common approach. The module is called
|
|
\module{bisect} because it uses a basic bisection algorithm to do its
|
|
work. The source code may be most useful as a working example of the
|
|
algorithm (the boundary conditions are already right!).
|
|
|
|
The following functions are provided:
|
|
|
|
\begin{funcdesc}{bisect_left}{list, item\optional{, lo\optional{, hi}}}
|
|
Locate the proper insertion point for \var{item} in \var{list} to
|
|
maintain sorted order. The parameters \var{lo} and \var{hi} may be
|
|
used to specify a subset of the list which should be considered; by
|
|
default the entire list is used. If \var{item} is already present
|
|
in \var{list}, the insertion point will be before (to the left of)
|
|
any existing entries. The return value is suitable for use as the
|
|
first parameter to \code{\var{list}.insert()}. This assumes that
|
|
\var{list} is already sorted.
|
|
\versionadded{2.1}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{bisect_right}{list, item\optional{, lo\optional{, hi}}}
|
|
Similar to \function{bisect_left()}, but returns an insertion point
|
|
which comes after (to the right of) any existing entries of
|
|
\var{item} in \var{list}.
|
|
\versionadded{2.1}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{bisect}{\unspecified}
|
|
Alias for \function{bisect_right()}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{insort_left}{list, item\optional{, lo\optional{, hi}}}
|
|
Insert \var{item} in \var{list} in sorted order. This is equivalent
|
|
to \code{\var{list}.insert(bisect.bisect_left(\var{list}, \var{item},
|
|
\var{lo}, \var{hi}), \var{item})}. This assumes that \var{list} is
|
|
already sorted.
|
|
\versionadded{2.1}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{insort_right}{list, item\optional{, lo\optional{, hi}}}
|
|
Similar to \function{insort_left()}, but inserting \var{item} in
|
|
\var{list} after any existing entries of \var{item}.
|
|
\versionadded{2.1}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{insort}{\unspecified}
|
|
Alias for \function{insort_right()}.
|
|
\end{funcdesc}
|
|
|
|
|
|
\subsection{Example}
|
|
\nodename{bisect-example}
|
|
|
|
The \function{bisect()} function is generally useful for categorizing
|
|
numeric data. This example uses \function{bisect()} to look up a
|
|
letter grade for an exam total (say) based on a set of ordered numeric
|
|
breakpoints: 85 and up is an `A', 75..84 is a `B', etc.
|
|
|
|
\begin{verbatim}
|
|
>>> grades = "FEDCBA"
|
|
>>> breakpoints = [30, 44, 66, 75, 85]
|
|
>>> from bisect import bisect
|
|
>>> def grade(total):
|
|
... return grades[bisect(breakpoints, total)]
|
|
...
|
|
>>> grade(66)
|
|
'C'
|
|
>>> map(grade, [33, 99, 77, 44, 12, 88])
|
|
['E', 'A', 'B', 'D', 'F', 'A']
|
|
\end{verbatim}
|