Messages in this thread | | | Date | Tue, 22 Aug 2023 09:31:48 +0000 | Subject | Re: [PATCH v1] rust: add improved version of `ForeignOwnable::borrow_mut` | From | Alice Ryhl <> |
| |
Andreas Hindborg <nmi@metaspace.dk> writes: >> + /// Borrows a foreign-owned object mutably. >> + /// >> + /// This method provides a way to access a foreign-owned value from Rust mutably. It provides >> + /// you with exactly the same abilities as an `&mut Self` when the value is Rust-owned, except >> + /// that this method does not let you swap the foreign-owned object for another. (That is, it >> + /// does not let you change the address of the void pointer that the foreign code is storing.) > > How about this: > > "For a smart pointer P<T> this method provides mutable access to T if > &mut P<T> would allow mutable access to T. Otherwise it provides > immutable access to T." > > The point is that the method provides access to the pointee, not the > smart pointer itself. In fact it is perfectly fine to do a mem::swawp() > for the pointee in the case of Box and depending on interpretation the > sentence "does not let you swap the foreign-owned object for another" is > confusing.
Yeah, I agree that the phrasing is somewhat confusing.
How about this:
/// This method provides a way to access a foreign-owned value from Rust mutably. It provides /// you with exactly the same abilities as an `&mut Self` when the value is Rust-owned, except /// that the address of the object must not be changed. /// /// Note that for types like [`Arc`], an `&mut Arc<T>` only gives you immutable access to the /// inner value, so this method also only provides immutable access in that case. /// /// In the case of `Box<T>`, this method gives you the ability to modify the inner `T`, but it /// does not let you change the box itself. That is, you cannot change which allocation the box /// points at.
Alice
| |