=========
Methods
=========

---------
Methods
---------

Rust allows you to associate functions with your new types. You do this
with an :rust:`impl` block:

.. code:: rust

   #[derive(Debug)]
   struct CarRace {
       name: String,
       laps: Vec<i32>,
   }

   impl CarRace {
       // No receiver, a static method
       fn new(name: &str) -> Self {
           Self { name: String::from(name), laps: Vec::new() }
       }

       // Exclusive borrowed read-write access to self
       fn add_lap(&mut self, lap: i32) {
           self.laps.push(lap);
       }

       // Shared and read-only borrowed access to self
       fn print_laps(&self) {
           println!("Recorded {} laps for {}:", self.laps.len(), self.name);
           for (idx, lap) in self.laps.iter().enumerate() {
               println!("Lap {idx}: {lap} sec");
           }
       }

       // Exclusive ownership of self (covered later)
       fn finish(self) {
           let total: i32 = self.laps.iter().sum();
           println!("Race {} is finished, total lap time: {}", self.name, total);
       }
   }

   fn main() {
       let mut race = CarRace::new("Monaco Grand Prix");
       race.add_lap(70);
       race.add_lap(68);
       race.print_laps();
       race.add_lap(71);
       race.print_laps();
       race.finish();
       // race.add_lap(42);
   }

The :rust:`self` arguments specify the :dfn:`receiver` - the object the method
acts on. There are several common receivers for a method:

-  :rust:`&self`: borrows the object from the caller using a shared and
   immutable reference. The object can be used again afterwards.
-  :rust:`&mut self`: borrows the object from the caller using a unique and
   mutable reference. The object can be used again afterwards.
-  :rust:`self`: takes ownership of the object and moves it away from the
   caller. The method becomes the owner of the object. The object will
   be dropped (deallocated) when the method returns, unless its
   ownership is explicitly transmitted. Complete ownership does not
   automatically mean mutability.
-  :rust:`mut self`: same as above, but the method can mutate the object.
-  No receiver: this becomes a static method on the struct. Typically
   used to create constructors which are called :rust:`new` by convention.

---------
Details
---------

Key Points:

-  It can be helpful to introduce methods by comparing them to
   functions.

   -  Methods are called on an instance of a type (such as a struct or
      enum), the first parameter represents the instance as :rust:`self`.
   -  Developers may choose to use methods to take advantage of method
      receiver syntax and to help keep them more organized. By using
      methods we can keep all the implementation code in one predictable
      place.

-  Point out the use of the keyword :rust:`self`, a method receiver.

   -  Show that it is an abbreviated term for :rust:`self: Self` and perhaps
      show how the struct name could also be used.
   -  Explain that :rust:`Self` is a type alias for the type the :rust:`impl`
      block is in and can be used elsewhere in the block.
   -  Note how :rust:`self` is used like other structs and dot notation can
      be used to refer to individual fields.
   -  This might be a good time to demonstrate how the :rust:`&self` differs
      from :rust:`self` by trying to run :rust:`finish` twice.
   -  Beyond variants on :rust:`self`, there are also
     :url:`special wrapper types <https://doc.rust-lang.org/reference/special-types-and-traits.html>`
      allowed to be receiver types, such as :rust:`Box<Self>`.
