Add a page detailing the time complexity of operations on built-in types

[StanFromIreland]

Inspired by @nedbat's post on Discourse:

One page in the wiki that I think should be in the docs is Time Complexity. It seems like important information about CPython and should be documented.

The page's location isn't ideal, but we don't have a better place for it currently. We discussed this at the last Docs Community meeting, but didn't come up with a better place to put it, and creating new top level sections is in my opinion, out of scope (as we'd need to move other pages as well). If it's desired we can do it in a future PR.

I spend a while considering how to best present time complexity here, avoiding complexity ;-) The wiki pages splits it into amortised, worst, best and averages cases (each type had a selection of those), but I think that it would be too confusing for readers. As such I give the average case, and put the details in the prose/footnotes.

The numbers are, hopefully, correct, as I don't think I missed any quirks (at least I don't know of any ;-). But I'd appreciate a review from the experts here, maybe Serhiy or Tim could please take a peek?

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #34055579 | 📁 Comparing a893080 against main (bfd774d)

  🔍 Preview build  

73 files changed · + 1 added · ± 72 modified

+ Added

• library/time-complexity.html

± Modified

• glossary.html
• index.html
• license.html
• c-api/arg.html
• c-api/capsule.html
• c-api/exceptions.html
• c-api/frame.html
• c-api/init_config.html
• c-api/intro.html
• c-api/stable.html
• and 62 more...

[picnixz]

Iteration is, AFAICT, always O(n) so we can group that under a common table. Likewise, getting the length of a sized object is O(1).

I think it's better to keep pythonic exmaples as well. "d[key]" is mucher better than "get item" IMO.

When I read "the non-mtating operations below", it also rings "the opertaions below are all non-mutating". Instead, I suggest to add some * if the opertaion is mutating and explain that at the beginning of the document.

[StanFromIreland]

Iteration is, AFAICT, always O(n) so we can group that under a common table. Likewise, getting the length of a sized object is O(1).

While it would make the tables shorter, it's not so straightforward unfortunately. There are subtle differences, see footnote six. I also think that reference pages are scanned, not read linearly. As such, I'd prefer to keep them where they are.

[eendebakpt]

I am +0.5 in this. I like to the idea, but it will take time to maintain and it is not clear to me where to draw the line when more additions are requested (e.g. memory complexity, alternatives, more detailed descriptions, more references).

[picnixz]

FTR the Qt help pages once had a page for complexty of operations of their STL containers, so it might be worth reading them if you need precedents in other languages. I do not know if those pages still exist as they were available for Qt5 dirdctly in the Qt Creator IDE.

[picnixz]

I found back the link: https://doc.qt.io/qt-6/containers.html#algorithmic-complexity

[StanFromIreland]

Thanks Pieter, Bénédikt and Hugo for the reviews ❤️ !

[nedbat]

@StanFromIreland I really appreciate the work you've put into this, and the bravery of taking it on! My comments are minor. I'm looking forward to this getting merged.

Do we already have a clear idea of what to do with the other data structures in the stdlib? This page directs people to deques, but doesn't include them (I know, because they are not a built-in).

[nedbat]

One last fix, then it's good from my side.

[StanFromIreland]

@dg-pb maybe this is something you'd be interested in reviewing? :-)

[dg-pb]

Substring search: might be worth mentioning that reverse search operations have O(n^2) worst case as two-way is not implemented. I suppose you added me here after seeing my last issue where I just inquired whether solution would be desirable: #155716

So str.rfind / str.rindex / str.rsplit / str.rpartition are all O(n^2) worst, except for single char and whitespace cases.

Apart from this, LGTM. Thank you for this work - I know I will enjoy visiting this page.

[StanFromIreland]

I suppose you added me here after seeing my last issue where I just inquired whether solution would be desirable: #155716

Yep! I also came across that while writing this page :-)

So str.rfind / str.rindex / str.rsplit / str.rpartition are all O(n^2) worst, except for single char and whitespace cases.

See footnote 10, although I ended up with O(nk) worst case.

[dg-pb]

Seen it: "A naive substring search would need O(nk) comparisons in the worst case, where k is the length of the substring searched for, but CPython uses search algorithms with a linear worst case for forward searches."

Yes, it does (maybe?) encode this information. However, this can be misinterpreted:

1. "with a linear worst case for forward searches" assures forward search.
2. "A naive substring search would need O(nk) comparisons in the worst case" - "would" suggests that in some other world this would be needed, but here we avoid it.
3. Thus still leaves reader with open question - "So what happens in reverse search?"

I think this is important and personally, I would add another line in the table -- this is not "by-the-way", this is a real risk. It doesn't seem to cause many issues due to infrequent usage, but I think being in-your-face-explicit about this would be an honest thing to do.

[StanFromIreland]

I see, that's reasonable, I've sent 4d223f1.

[nedbat]

rpartition and rsplit are mentioned in this footnote, but partition and split aren't mentioned anywhere.