Skip to content

GH-104145: Use fully-qualified cross reference types for the bisect module #104172

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AlexWaygood merged 4 commits into from
May 8, 2023
Merged

GH-104145: Use fully-qualified cross reference types for the bisect module #104172

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e446348
Use 'refspecific' cross reference type for the bisect function
AA-Turner May 4, 2023
e3ff8e9
Alter target
AA-Turner May 4, 2023
7fd3523
Use fully-qualified version of the py:func role
AA-Turner May 4, 2023
93027f4
Minimise ``git diff``
AA-Turner May 8, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Minimise git diff
  • Loading branch information
@AA-Turner
AA-Turner committed May 8, 2023
commit 93027f4c0de4c98d39edd0013d16891cf5447500
38 changes: 19 additions & 19 deletions Doc/library/bisect.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,8 @@ method to determine whether a value has been found. Instead, the
functions only call the :meth:`__lt__` method and will return an insertion
point between values in an array.

.. _bisect functions:

The following functions are provided:


Expand Down Expand Up @@ -55,8 +57,8 @@ The following functions are provided:
.. function:: bisect_right(a, x, lo=0, hi=len(a), *, key=None)
bisect(a, x, lo=0, hi=len(a), *, key=None)

Similar to :py:func:`~bisect.bisect_left`, but returns an insertion point
which comes after (to the right of) any existing entries of *x* in *a*.
Similar to :py:func:`~bisect.bisect_left`, but returns an insertion point which comes
after (to the right of) any existing entries of *x* in *a*.

The returned insertion point *ip* partitions the array *a* into two slices
such that ``all(elem <= x for elem in a[lo : ip])`` is true for the left slice and
Expand All @@ -70,8 +72,7 @@ The following functions are provided:

Insert *x* in *a* in sorted order.

This function first runs :py:func:`~bisect.bisect_left` to locate an
insertion point.
This function first runs :py:func:`~bisect.bisect_left` to locate an insertion point.
Next, it runs the :meth:`insert` method on *a* to insert *x* at the
appropriate position to maintain sort order.

Expand All @@ -88,11 +89,10 @@ The following functions are provided:
.. function:: insort_right(a, x, lo=0, hi=len(a), *, key=None)
insort(a, x, lo=0, hi=len(a), *, key=None)

Similar to :py:func:`~bisect.insort_left`, but inserting *x* in *a* afte
any existing entries of *x*.
Similar to :py:func:`~bisect.insort_left`, but inserting *x* in *a* after any existing
entries of *x*.

This function first runs :py:func:`~bisect.bisect_right` to locate an
insertion point.
This function first runs :py:func:`~bisect.bisect_right` to locate an insertion point.
Next, it runs the :meth:`insert` method on *a* to insert *x* at the
appropriate position to maintain sort order.

Expand Down Expand Up @@ -142,10 +142,10 @@ thoughts in mind:
Searching Sorted Lists
----------------------

The above :py:mod:`bisect functions <bisect>` are useful for finding insertion
points but can be tricky or awkward to use for common searching tasks. The
following five functions show how to transform them into the standard lookups
for sorted lists::
The above `bisect functions`_ are useful for finding insertion points but
can be tricky or awkward to use for common searching tasks. The following five
functions show how to transform them into the standard lookups for sorted
lists::

def index(a, x):
'Locate the leftmost value exactly equal to x'
Expand Down Expand Up @@ -188,10 +188,10 @@ Examples

.. _bisect-example:

The :py:func:`~bisect.bisect` function can be useful for numeric table lookups.
This example uses :py:func:`~bisect.bisect` to look up a letter grade for
an exam score (say) based on a set of ordered numeric breakpoints:
90 and up is an 'A', 80 to 89 is a 'B', and so on::
The :py:func:`~bisect.bisect` function can be useful for numeric table lookups. This
example uses :py:func:`~bisect.bisect` to look up a letter grade for an exam score (say)
based on a set of ordered numeric breakpoints: 90 and up is an 'A', 80 to 89 is
a 'B', and so on::

>>> def grade(score, breakpoints=[60, 70, 80, 90], grades='FDCBA'):
... i = bisect(breakpoints, score)
Expand All @@ -200,9 +200,9 @@ an exam score (say) based on a set of ordered numeric breakpoints:
>>> [grade(score) for score in [33, 99, 77, 70, 89, 90, 100]]
['F', 'A', 'C', 'C', 'B', 'A', 'A']

The :py:func:`~bisect.bisect` and :py:func:`~bisect.insort` functions also work
with lists of tuples. The *key* argument can serve to extract the field used
for ordering records in a table::
The :py:func:`~bisect.bisect` and :py:func:`~bisect.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
Expand Down