diff options
| -rw-r--r-- | Doc/lib/libbisect.tex | 53 |
1 files changed, 40 insertions, 13 deletions
diff --git a/Doc/lib/libbisect.tex b/Doc/lib/libbisect.tex index 555e3a7..2b27b9f 100644 --- a/Doc/lib/libbisect.tex +++ b/Doc/lib/libbisect.tex @@ -19,18 +19,45 @@ algorithm (i.e., the boundary conditions are already right!). The following functions are provided: -\begin{funcdesc}{bisect}{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. The -return value is suitable for use as the first parameter to -\code{\var{list}.insert()}. +\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}{insort}{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(\var{list}, \var{item}, -\var{lo}, \var{hi}), \var{item})}. +\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()} for backward compatibility. +\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()} for backward compatibility. \end{funcdesc} @@ -38,16 +65,16 @@ to \code{\var{list}.insert(bisect.bisect(\var{list}, \var{item}, \nodename{bisect-example} The \function{bisect()} function is generally useful for categorizing -numeric data. This example uses \function{bisect()} to look up a +numeric data. This example uses \function{bisect_right()} 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 +>>> from bisect import bisect_right >>> def grade(total): -... return grades[bisect(breakpoints, total)] +... return grades[bisect_right(breakpoints, total)] ... >>> grade(66) 'C' |