Skip to content

gh-113664: Update big O notation in bisect.rst to be consistently mono-spaced #113673

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.

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

Closed

Conversation

jnichols0
Copy link

@jnichols0 jnichols0 commented Jan 3, 2024

Update bisect.rst with consistent mono-spacing of big O e.g. O(n)


📚 Documentation preview 📚: https://cpython-previews--113673.org.readthedocs.build/

@jnichols0 jnichols0 requested a review from rhettinger as a code owner January 3, 2024 05:34
@ghost
Copy link

ghost commented Jan 3, 2024

All commit authors signed the Contributor License Agreement.
CLA signed

Copy link

@thesayfulla thesayfulla left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@hugovk
Copy link
Member

hugovk commented Jan 3, 2024

Searching, I see 19 examples in plain text:

❯ rg " O\(" -t rst
glossary.rst
745:      elements is O(1).

reference/datamodel.rst
1844:      dict insertion, O(n\ :sup:`2`) complexity.  See

using/cmdline.rst
372:   case performance of a dict construction, O(n\ :sup:`2`) complexity.  See

faq/design.rst
454:constant time -- O(1), in Big-O notation -- to retrieve a key.

whatsnew/2.3.rst
1199:  the O(n\*n) required for the grade-school multiplication algorithm.  (Original
1311:  O(lg n).  (See https://xlinux.nist.gov/dads//HTML/priorityque.html for more

whatsnew/3.3.rst
177:  is now possible to reverse a memoryview in O(1) by using a negative step.

whatsnew/2.7.rst
285:remains O(1).

library/bisect.rst
82:   Keep in mind that the ``O(log n)`` search is dominated by the slow O(n)
102:   Keep in mind that the ``O(log n)`` search is dominated by the slow O(n)

library/heapq.rst
273:items in the tree. By iterating over all items, you get an O(n log n) sort.

library/collections.rst
461:    same O(1) performance in either direction.
464:    fast fixed-length operations and incur O(n) memory movement costs for
588:the first element.  Indexed access is O(1) at both ends but slows to O(n) in

library/select.rst
188:O(highest file descriptor) and :c:func:`!poll` is O(number of file
189:descriptors), ``/dev/poll`` is O(active file descriptors).
384:linearly scanned again. :c:func:`!select` is O(highest file descriptor), while
385::c:func:`!poll` is O(number of file descriptors).

library/contextvars.rst
134:   The function has an O(1) complexity, i.e. works equally fast for

And only three in code formatting:

❯ rg "\`O\(" -t rst
library/bisect.rst
82:   Keep in mind that the ``O(log n)`` search is dominated by the slow O(n)
102:   Keep in mind that the ``O(log n)`` search is dominated by the slow O(n)
118:* The *insort()* functions are ``O(n)`` because the logarithmic search step

Looking at other sources, Wikipedia uses italics, or actually maths notation:

As do these Stanford and MIT pages.

@nedbat
Copy link
Member

nedbat commented Jan 3, 2024

I agree that the formatting should be consistent, but there's no reason to use monospaced. That implies that it is code, but "O(N)" is not code, and importantly, could easily be confused for code. We should be leaning away from formatting that implies it is code.

@hugovk
Copy link
Member

hugovk commented Jan 3, 2024

I agree with Ned, either plain text or italics.

(Sphinx has maths notation, but it might not work well with epub/PDF etc.)

@serhiy-storchaka
Copy link
Member

What if use more "mathematical" formatting?
*O*(*n*) -- O(n)
*O*(*n*:sup:`2`) -- O(n²)
*O*(log *n*) -- O(log n)

Or even directly use :math::
:math:`O(n)` -- $O(n)$
:math:`O(n^2)` -- $O(n^2)$
:math:`O(\log{n})` -- $O(\log{n})$

@encukou
Copy link
Member

encukou commented Jan 3, 2024

IMO, *O*(*n*) is the best choice. As far as I know, it's proper math notation.
:math: goes further but uses a different font, which is visually jarring.

@jnichols0
Copy link
Author

How about we apply this PR to attain consistency for this specific page and then create a new issue to update all the docs to consistently use a proper font and styling?

@hugovk
Copy link
Member

hugovk commented Jan 4, 2024

We might as well do them all at once, rather than a first PR (with backports) that is then undone. We prefer to avoid churn.

I'm also fine with *O*(*n*) -- O(n)

@serhiy-storchaka
Copy link
Member

It is better to do all changes at once. I created #113695 for this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
awaiting merge docs Documentation in the Doc dir skip news
Projects
None yet
Development

Successfully merging this pull request may close these issues.

8 participants