什么时候在方法中使用 self、&self 和 &mut self？

Question

What is the difference between a method taking self and a method taking &self or even &mut self ?

Eg

impl SomeStruct {
    fn example1(self) { }
    fn example2(&self) { }
    fn example3(&mut self) { }
}

Say I want to implement a method that pretty prints the struct to stdout, should I take &self ? I guess self also works? I'm not sure when to use what.

Answer 1

From the example in the book (just split onto three separate paragraphs and marked to maybe make it clearer):

&self : We've chosen &self here for the same reason we used &Rectangle in the function version: we don't want to take ownership, and we just want to read the data in the struct, not write to it.

&mut self : If we wanted to change the instance that we've called the method on as part of what the method does, we'd use &mut self as the first parameter.

self : Having a method that takes ownership of the instance by using just self as the first parameter is rare; this technique is usually used when the method transforms self into something else and you want to prevent the caller from using the original instance after the transformation.

Or in other words: the difference is exactly the same as SomeStruct , &SomeStruct , and &mut SomeStruct .

Say I want to implement a method that pretty prints the struct to stdout, should I take &self ? I guess self also works?

As you can see, this is exactly a case for &self . If you use self (or &mut self ) the method will likely still compile, but it can only be used in more restricted situations.

Answer 2

The other answer is good, but not complete. So, here's more info about self , &self and &mut self .

Summary table

	Short for	Equivalent to	Takes ownership?	When to use?	Example
self	self: Self	a: A	Yes	The code that calls this method should not able to reuse the object on which you call the method.	Invalidate an object because maybe you transform it into another . Drop an object. Immutable data structures?
&self	self: &Self	a: &A	No - immutably borrows	For reading self or its fields.	For printing something or compute a value based on multiple values of other copyable fields.
&mut self	self: &mut Self	a: &mut A	No - mutable borrows	For reading or writing self and its fields.	A function that updates the internal state of a data structure.
mut self	mut self: Sel	mut a: A	Yes	If you want to change what self points to. Not useful because it takes ownership.

More notes

• Self is an alias for the type that the impl block is for.
• The rules of ownership and borrowing apply to self as they apply to any other parameter (see eg this answer )
• Examples of when to use which here and here
• Examples of when we should take ownership here , although the answers don't provide code examples but just point to the docs
• self is not just used as the first parameter of a method, but can also be used to reference the current module (more details here )
• If you define a variable like this let foo = Foo::new() (ie you cannot mutate foo ) and then you attempt to call a method that requires a mutable reference (ie the first parameter is &mut self ), you'll get a compilation error, so you would need to change let foo to let mut foo . A complete example here
• More info also here