Methods and associated functions

Why methods?

A struct holds data. Methods add behaviour that belongs with that data. Instead of a loose function area(rect: &Rect), you write rect.area(). The code is easier to find, and editors can list everything a type can do when you type a dot.

#[derive(Debug)]
struct Rect {
    width: u32,
    height: u32,
}

impl Rect {
    fn area(&self) -> u32 {
        self.width * self.height
    }

    fn can_hold(&self, other: &Rect) -> bool {
        self.width > other.width && self.height > other.height
    }
}

fn main() {
    let room = Rect { width: 12, height: 10 };
    let bed = Rect { width: 6, height: 7 };
    println!("{} {}", room.area(), room.can_hold(&bed));   // 120 true
}

A method is still an ordinary function underneath. room.area() is exactly the same as Rect::area(&room). The dot form is simply easier to read and lets you chain calls, like text.trim().to_uppercase().

The three kinds of self

struct Wallet {
    balance: u64,
}

impl Wallet {
    fn balance(&self) -> u64 {
        self.balance
    }
    fn add(&mut self, amount: u64) {
        self.balance += amount;
    }
    fn close(self) -> u64 {
        println!("closing");
        self.balance          // the Wallet is consumed
    }
}

You do not write &w or &mut w when calling. Rust does automatic referencing: w.add(100) is turned into Wallet::add(&mut w, 100) for you. But w itself must still be declared mut to call a &mut self method.

Associated functions and new

A function inside impl without a self parameter is an associated function. It belongs to the type, not to one instance, and you call it with two colons: Type::function(). You have already used one: String::from. By convention, a constructor function called new creates an instance. Self (capital S) is a short name for the type the impl is for.

impl Wallet {
    fn new() -> Self {
        Self { balance: 0 }
    }
    fn with_balance(amount: u64) -> Self {
        Self { balance: amount }
    }
}

fn main() {
    let mut w = Wallet::new();
    w.add(500);
    let w2 = Wallet::with_balance(1000);
    println!("{} {}", w.balance(), w2.balance());   // 500 1000
    let last = w.close();
    // w.balance();   // error: w was moved by close(self)
    println!("{last}");
}

Several impl blocks

A type may have many impl blocks, even in different files of the same crate. This is useful for grouping related methods. You will also write impl blocks to implement traits (module 7).

Common mistakes

• Forgetting self: fn area() -> u32 inside impl is an associated function, so rect.area() fails. Add &self.
• Calling a &mut self method on a non-mut variable: "cannot borrow as mutable". Use let mut.
• Using self by value by accident and then losing the instance. Use &self unless you mean to consume it.
• Calling an associated function with a dot (w.new()). Use Wallet::new().