Docs - type guarantees update

[WiktorPrzetacznik]

Content:

• Pin::map_unchecked | Safety section update
• String::reserve, String::reserve_exact | Panic section update
• Saturating | Introduce Layout section
• Fix typos

Questions:

1. This proposes to update String reserve methods docs:

   Panics if the new capacity overflows [usize].

   ->

   Panics if the new capacity exceeds [isize::MAX] bytes.

   There are a few other types that are based on Vec and offer similar reserve API (like BinaryHeap).
   Should they be updated, too?

ACP: rust-lang/libs-team#482 [not required]

[rustbot]

r? @cuviper

rustbot has assigned @cuviper.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[cuviper]

Have these guarantees been discussed and approved somewhere? The String change is fine IMO, since that is a fundamental limitation of heap allocations (and object sizes in general), and we already state that in Vec docs. Saturating layout is probably fine -- it's transparent, but libs-api should sign off on guaranteeing that. I'm not sure about Pin stuff.

[WiktorPrzetacznik]

@cupiver
Here's my discussion about Pin -> https://internals.rust-lang.org/t/why-am-i-not-allowed-to-move-arg-in-pin-map-unchecked/19664/2?u=wiktor

About Saturating - I provoked some discussion on that topic - let's wait for more thoughts on this.
I'll ping you when something happens here.

[cuviper]

@rustbot author

I'll ping you when something happens here.

You can use @rustbot ready for that.

[alex-semenyuk]

@WiktorPrzetacznik
From wg-triage. Do you have any updates on this PR?

[WiktorPrzetacznik]

@alex-semenyuk
Unfortunately not at all, suffering from lack of time, I have some more free time in upcoming days though, so I'm planning on opening an ACP asking about those changes - if there's a better way to get official response from t-libs let me know.

[Amanieu]

r? libs-api

[the8472]

We discussed this during today's libs-API meeting, it looks like there previously was no guarantee for the Saturating layout, so this would constitute an API change and will need an FCP.

Pin is subtle, so we weren't sure on the spot if this constitutes a new guarantee or a clarification, so we'd like input from a Pin expert on that.

[bors]

☔ The latest upstream changes (presumably #149682) made this pull request unmergeable. Please resolve the merge conflicts.

[reddevilmidzy]

@rustbot author

[rustbot]

Reminder, once the PR becomes ready for a review, use @rustbot ready.

[WiktorPrzetacznik]

Ok, but what do I do with it? Saturating needs FCP, pin is stuck in oblivion. Are you OK with the other changes?