Code change:
Reading the current documentation about at it is not clear to me what the effect of is. I was supposing calling this function returns the value stored in the Option type and replaces it by an value. However, this seems not to be the case as the second assertion in the following example program passes fine: (You can run the program online at ). In addition, the current documentation says: Does this means the value contained in the is moved out or cloned or is a borrow taken? Also, is a type and I don't think that the function really returns a type, but a value of type . Therefore, should the quoted sentence maybe reworded towards something along the lines of: Please let me know what you think about these points. I am more than happy to provide a PR to improve the documentation, but I don't know all the answers to the questions I have raised above and I am also not sure if my claims are correct :/
moves the value out of the option if it is , or panics if it is . In your example, the call to performs an implicit copy of because is of type , and implements when implements (as does). This example will not compile, because does not implement : The error is: The documentation could be updated to mention moving, but this is implicit in the method's parameter, which is by-value.
thanks a lot for your explanation! Still, I don't think I grasped how the works completely yet. Here is an example: I understand that moving a value from a borrowed object is not possible and that's why the first attempt fails. However, I don't see why the second attempt works. In a sense, the new type after the call to can be written as with . In that case the call to as done in looks to me again as a move. But as is borrowed, I don't see why this move is different from the first move attempt in my code, which failed. Is there a special rule to the method, which makes the later case work but the first not or am I missing something on how the borrow/move rules in rust work?
Basically, in order to call , you need to have an owned . This is the case in your "ATTEMPT WORKS" code because goes from to . The code under "ATTEMPT FAILED" doesn't compile because is borrowed (), not because contains a borrowed value. For example, the following code does compile:
Thanks again The point that you need an owned makes sense to me and was something I was not that much aware about before :) What I don't see at this point is why in my example is not an owned already. As you can see in this code example: It seems that is of the owning type already. From reading your last comment it sounds to me that is supposed to be of type with here. But that is something I don't see yet :/ Any comments is highly appreciated! PS: I hope digging deeper on this issue is okay for you? From your comments so far I think I can fix the documentation but still I would love to have a good overall understanding how the interaction with really works :)
In that example, the type of is indeed , but it is not owned from the perspective of the compiler, because it is accessed through a reference ().
Ahh, I think now I get it - thanks a lot Are these the (hidden) steps the compiler is doing when executing ? The compiler knows that is of type The definition of is given by , which means for calling the , the must be a mutable borrow. As the is NOT a mutable borrow, the compiler takes an implicit mutable borrow like and uses the result as the argument when calling . The call to does type check and returns a fully owned type. Here I am using the term "fully owned" to differentiate to the case of the previous which is not owned due to the access through the reference of . Because the result of is now fully owned, the call to type checks. I've got to say: I love and be impressed what the rust compiler is doing underneath here (once you understand it :) )! thank you sooo much for these helpful and very educational comments!!!
So, given all this: is there anything actionable we can do to improve these docs? What would you suggest, ?
how do you feel about this: the description gave as sounds much better and is more precise compared to the current description of , which is . Therefore, I would love to exchange them. do you think there is value in adding a section about and how it works to the existing documentation?
I like it! would you like to submit a PR or should I take care of it? I'm not sure.
I don't think we need to add anything about , because there's nothing special about it. It just follows Rust's ownership and borrowing rules. However, 's documentation in general does need work, both convention-wise and content-wise.

Related discussion:
text: } } <del> /// Returns the inner `T` of a `Some(T)`. </del> <ins> /// Moves the value `v` out of the `Option<T>` if the content of the `Option<T>` is a `Some(v)`. </ins> /// /// # Panics ///