Clarify explicitly that BTree{Map,Set} are ordered.

[umanwizard]

One of the main reasons one would want to use a BTree{Map,Set} rather than a Hash{Map,Set} is because they maintain their keys in sorted order; but this was never explicitly stated in the top-level docs (it was only indirectly alluded to there, and stated explicitly in the docs for iter, values, etc.)

This PR states the ordering guarantee more prominently.

[rust-highfive]

r? @dtolnay

(rust-highfive has picked a reviewer for you, use r? to override)

[joshtriplett]

@bors r+

[bors]

📌 Commit 9057a6d has been approved by joshtriplett

[dtolnay]

I don't find it clear what "stored in order" means for a data structure like this. They're stored in a tree structure which is not contiguous in memory. In practice it's easy to have greater elements (according to Ord) stored at lower addresses.

I would prefer this documentation not to say anything about how the data is stored. It can say what guarantees are made by the iterator, but it's the iterator's job to bridge between how the stuff is stored (which is a private detail) and how they're sequenced when accessed by the user of the data structure.

Performance characteristics (Big O?) are also fine to document. That should hopefully substitute for some of the desire to document "how it's stored".

[dtolnay]

@bors r-

[joshtriplett]

@dtolnay That seems like a reasonable distinction to make. The visible behavior is more important than a handwave about internal storage semantics.

[umanwizard]

@dtolnay what would you think of language like "Entries are arranged in such a way that they may be efficiently iterated over in key order" (which doesn't say anything concrete about the physical layout)

[dtolnay]

Don't you think it's enough to say that iteration produces the entries in key order? Why does how they are arranged need to play a role in a user-facing guarantee?

"Efficiently"—I would be on board with providing the guarantee more precisely than this. If n is the number of entries, is it O(1) worst case per next? Is it O(1) amortized time? Is it O(log n)?

[umanwizard]

Don't you think it's enough to say that iteration produces the entries in key order? Why does how they are arranged need to play a role in a user-facing guarantee?

I thought it was fine to say something about the physical arrangement, since almost that entire doc comment is about the specific data structure used to implement this type, and the properties that that data structure has.

However, I don't feel very strongly about it, so I will defer to whatever you prefer; indeed, it's fine if we simply mention that iteration happens in key order (plus a big-O description)

[dtolnay]

I thought it was fine to say something about the physical arrangement, since almost that entire doc comment is about the specific data structure used to implement this type, and the properties that that data structure has.

Good call, I hadn't actually read the rest of this documentation section outside of the + lines in your PR. Rereading it now, I think the difference between it and what you'd suggested in #92706 (comment) is that the existing documentation is saying something useful about the physical arrangement, whereas "Entries are arranged in such a way that they may be efficiently iterated over in key order" is saying the equivalent of "Entries are arranged, and iterating them in key order is efficient" where the statement "Entries are arranged" does not meaningfully contribute any information.

[dtolnay]

Thanks!

[dtolnay]

@bors r+ rollup

[bors]

📌 Commit ad6408d has been approved by dtolnay