Some type guarantees in docs are not precise enough.
Motivating examples or use cases
The lack of precision can be misleading and introduces unnecessary complexity, like Pin::map_unchecked
This function is unsafe. You must guarantee that the data you return will not move so long as the argument value does not move (for example, because it is one of the fields of that value), and also that you do not move out of the argument you receive to the interior function.
There's no way to do so, I'm pretty sure this is just a copy-paste from Pin::map_unchecked_mut
Another worth noting example is String::reserve (and other types based on Vec):
Panics if the new capacity overflows usize.
The more accurate would be informing that it panics if exceeds [isize::MAX] bytes.
Solution sketch
Update documentation of:
Pin::map_unchecked
String::reserve, String::reserve_exact
Saturating
Precise information about what I'm proposing to change can be found in the related open PR #129822
Alternatives
Leaving the docs as they are now.
Moving Vec's related docs about panicing when exceeding usize into some other place, so it doesn't have to be changed in every related type.
Proposal
Problem statement
Some type guarantees in docs are not precise enough.
Motivating examples or use cases
The lack of precision can be misleading and introduces unnecessary complexity, like Pin::map_unchecked
There's no way to do so, I'm pretty sure this is just a copy-paste from Pin::map_unchecked_mut
Another worth noting example is String::reserve (and other types based on Vec):
The more accurate would be informing that it panics if exceeds [
isize::MAX] bytes.Solution sketch
Update documentation of:
Precise information about what I'm proposing to change can be found in the related open PR #129822
Alternatives
Links and related work
PR #129822 - docs changes proposal forum discussion about Pin::map_unchecked forum discussion - Is Saturating guaranteed to have the same layout and ABI as T?