127. Structs and impl

A particle with a fixed shape

Here is the particle from chapter 3, in TypeScript:

interface Particle {
  x: number; y: number;
  vx: number; vy: number;
}
const p: Particle =
  { x: 0, y: 0, vx: 3, vy: 4 };

The interface is only a promise to the type checker. At run time p is an ordinary object, and the engine has to discover its shape for itself (the shapes of chapter 63). Rust has no ordinary objects. You declare the shape first, and every value is built from it.

Structs

struct Particle {
    x: f64,
    y: f64,
    vx: f64,
    vy: f64,
}

let mut p = Particle {
    x: 0.0, y: 0.0, vx: 3.0, vy: 4.0,
};
p.x += p.vx;

You must give every field, and their types are checked. Fields are read and written with a dot, as in TypeScript. Mutability belongs to the binding: let mut p makes all of p changeable, and you can’t mark just one field as mutable^[1].

When a variable has the same name as a field, you can write it once. Particle { x, y, vx: 0.0, vy: 0.0 } means x: x, y: y. That is field init shorthand.

A struct moves like a String does. let q = p; moves the particle into q, and p can’t be used afterwards (chapter 124). Chapter 131 shows how to make small structs copy instead.

Methods live in impl

A TypeScript class (chapter 7) puts fields and methods in one block. Rust splits them. The struct holds the data, and an impl block attaches functions to the type:

impl Particle {
    fn new(vx: f64, vy: f64) -> Self {
        Particle { x: 0.0, y: 0.0, vx, vy }
    }

    fn speed(&self) -> f64 {
        let v2 = self.vx * self.vx
            + self.vy * self.vy;
        v2.sqrt()
    }

    fn step(&mut self, dt: f64) {
        self.x += self.vx * dt;
        self.y += self.vy * dt;
    }
}

new has no self. It is an associated function, called on the type: Particle::new(3.0, 4.0). There is no new keyword in Rust, and new is just the usual name for a function that builds a value. Inside the impl, Self is another name for Particle.

speed and step are methods: their first parameter is self, the value the method was called on. You call them with a dot, p.speed().

Three kinds of self

JavaScript’s this is whatever object you called the method on, and the method can do anything to it. Rust’s self is a parameter like any other, so its type says exactly what the method may do.

let mut p = Particle::new(3.0, 4.0);
let s = p.speed();
p.step(1.0);
p.step(1.0);
let q = p.stopped();
p.speed(); // ✗ p was moved

• &self borrows the value to read it. Most methods are like this.
• &mut self borrows it to change it. The caller needs let mut.
• self takes ownership. The value moves into the method, and the caller can’t use it afterwards. It is rare, and used when a method turns the value into something else^[1].

You don’t write the borrow at the call. p.step(1.0) means Particle::step(&mut p, 1.0). Rust looks at the receiver type and adds the & or &mut for you^[1]. That makes the borrowing rules from chapter 125 apply to every method call. Forget the mut (real rustc 1.97 output, trimmed):

error[E0596]: cannot borrow `p` as
  mutable, as it is not declared as
  mutable

Use p after p.stopped() and the error even explains why:

note: `Particle::stopped` takes
  ownership of the receiver `self`,
  which moves `p`

struct Particle {
    x: f64,
    y: f64,
    vx: f64,
    vy: f64,
}

impl Particle {
    fn new(vx: f64, vy: f64) -> Self {
        Particle {
            x: 0.0,
            y: 0.0,
            vx,
            vy,
        }
    }

    fn speed(&self) -> f64 {
        let v2 = self.vx * self.vx
            + self.vy * self.vy;
        v2.sqrt()
    }

    fn step(&mut self, dt: f64) {
        self.x += self.vx * dt;
        self.y += self.vy * dt;
    }

    fn stopped(mut self) -> Self {
        self.vx = 0.0;
        self.vy = 0.0;
        self
    }
}

fn main() {
    let mut p = Particle::new(3.0, 4.0);
    println!("speed {}", p.speed());
    p.step(1.0);
    p.step(1.0);
    println!("at {} {}", p.x, p.y);
    let q = p.stopped();
    println!("speed {}", q.speed());
}

fn push(&mut self, value: Value)
fn pop(&mut self) -> Value
fn peek(&self, distance: usize)
    -> Value

Your turn

struct Stack {
    slots: [f64; 8],
    top: usize,
}

impl Stack {
    fn new() -> Self {
        Stack {
            slots: [0.0; 8],
            top: 0,
        }
    }

    fn push(&mut self, v: f64) {
        todo!()
    }

    fn pop(&mut self) -> f64 {
        todo!()
    }

    fn peek(&self, d: usize) -> f64 {
        todo!()
    }

    fn len(&self) -> usize {
        self.top
    }
}

struct Span {
    start: usize,
    end: usize,
}

impl Span {
    fn len(&self) -> usize {
        0
    }

    fn join(self, b: Span) -> Span {
        self
    }
}

What you learned

• A struct is a named record with typed fields. Build it with every field, read with a dot, and change it through a mut binding.
• An impl block attaches functions to a type. Methods take self; associated functions like new don’t, and are called with Type::.
• The self receiver says how a method uses the value: &self reads, &mut self changes, self consumes. Calls borrow automatically.
• An array of structs stores the structs inline, back to back.

Next: enums and match, Rust’s own discriminated unions, and the match over opcodes at the heart of the Rust VM.