Safety note in Pin::map_unchecked says:
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.
Why? The only problem I could potentially see about it is something like this:
- Create a
T using some (shared) reference to RefCell.
But that doesn't seem to be the case, because the documentation clearly says about moving argument that I receive to the interior function (so moving from within the closure - before I create a
Pin<&T>). Does the description make assumption I may have created
Pin<&T> before? I think the documentation here is at least unclear.
The highlighted sentence doesn’t make too much sense for
map_unchecked. It looks to me like the documentation was copy-pasted from
map_unchecked_mut, where the “You must guarantee that […] you do not move out of the argument you receive to the interior function.” provision makes a lot more sense. For
map_unchecked though, the
&T argument to the mapped function doesn’t provide anything above what
Pin<&T> already gave us, as
Pin<&T> -> &T is safe via dereferencing or
get_ref, anyways - so the unsafe part is merely about the return
&U being wrapped into
Regarding your comment / example with
RefCell, I cannot quite follow that. Note however that
RefCell cannot soundly do structural pinning anyways, since a
Pin<&RefCell<T>> allows mutable (non-pinned) access to the contained value via
get_ref (which gives us the
borrow_mut (which then gives
&mut T), anyways.
The RefCell example was brought by another user trying to explain (I believe) the highlithed sentence on users forum here.
Btw. What's the most "clean" way to propose such a small documentation change? Wouldn't PR be an "overkill" for this?