Structs - Feature 16/41

Structs are user-defined types with named fields and fixed structure. They provide type safety and better performance than objects.

Defining Structs

struct Point {
  x: f64,
  y: f64
}

struct Person {
  name: String,
  age: i32,
  active: bool
}

Test Coverage: ✅ tests/lang_comp/data_structures/structs.rs

Try It in the Notebook

struct User {
  id: i32,
  username: String,
  email: String
}

// Create instance
let user = User {
  id: 1,
  username: "alice",
  email: "alice@example.com"
}

user  // Returns: User { id: 1, username: "alice", email: "alice@example.com" }

Expected Output: User { id: 1, username: "alice", email: "alice@example.com" }

Creating Instances

struct Point {
  x: f64,
  y: f64
}

let origin = Point { x: 0.0, y: 0.0 }
let p = Point { x: 10.5, y: 20.3 }

Expected Output: Point { x: 0.0, y: 0.0 }, Point { x: 10.5, y: 20.3 }

Field Init Shorthand

struct Person {
  name: String,
  age: i32
}

let name = "Alice"
let age = 30

// Shorthand when variable names match field names
let person = Person { name, age }

Expected Output: Person { name: "Alice", age: 30 }

Accessing Fields

Use dot notation:

struct Point {
  x: f64,
  y: f64
}

let p = Point { x: 10.0, y: 20.0 }

p.x  // Returns: 10.0
p.y  // Returns: 20.0

Expected Output: 10.0, 20.0

Updating Fields

struct Counter {
  value: i32
}

let mut counter = Counter { value: 0 }

counter.value = 10
counter.value  // Returns: 10

Expected Output: 10

Note: Instance must be mut to modify fields.

Struct Methods

Define methods with impl block:

struct Rectangle {
  width: f64,
  height: f64
}

impl Rectangle {
  fn area(&self) -> f64 {
    self.width * self.height
  }

  fn perimeter(&self) -> f64 {
    2.0 * (self.width + self.height)
  }

  fn is_square(&self) -> bool {
    self.width == self.height
  }
}

let rect = Rectangle { width: 10.0, height: 20.0 }
rect.area()       // Returns: 200.0
rect.perimeter()  // Returns: 60.0
rect.is_square()  // Returns: false

Expected Output: 200.0, 60.0, false

Associated Functions (Constructors)

struct Point {
  x: f64,
  y: f64
}

impl Point {
  fn new(x: f64, y: f64) -> Point {
    Point { x, y }
  }

  fn origin() -> Point {
    Point { x: 0.0, y: 0.0 }
  }

  fn from_tuple(tuple: (f64, f64)) -> Point {
    Point { x: tuple.0, y: tuple.1 }
  }
}

let p1 = Point::new(10.0, 20.0)
let p2 = Point::origin()
let p3 = Point::from_tuple((5.0, 15.0))

Expected Output: Point { x: 10.0, y: 20.0 }, Point { x: 0.0, y: 0.0 }, Point { x: 5.0, y: 15.0 }

Common Patterns

Builder Pattern

struct Config {
  host: String,
  port: i32,
  ssl: bool,
  timeout: i32
}

impl Config {
  fn new() -> Config {
    Config {
      host: "localhost",
      port: 80,
      ssl: false,
      timeout: 30
    }
  }

  fn with_host(mut self, host: String) -> Config {
    self.host = host
    self
  }

  fn with_port(mut self, port: i32) -> Config {
    self.port = port
    self
  }

  fn with_ssl(mut self) -> Config {
    self.ssl = true
    self
  }
}

let config = Config::new()
  .with_host("example.com")
  .with_port(443)
  .with_ssl()

Expected Output: Config { host: "example.com", port: 443, ssl: true, timeout: 30 }

Validation

struct Email {
  address: String
}

impl Email {
  fn new(address: String) -> Option<Email> {
    if address.contains("@") {
      Some(Email { address })
    } else {
      None
    }
  }

  fn is_valid(&self) -> bool {
    self.address.contains("@") && self.address.contains(".")
  }
}

let valid = Email::new("alice@example.com")     // Returns: Some(Email { ... })
let invalid = Email::new("not-an-email")        // Returns: None

Expected Output: Some(Email { address: "alice@example.com" }), None

Data Transformation

struct Celsius {
  value: f64
}

struct Fahrenheit {
  value: f64
}

impl Celsius {
  fn to_fahrenheit(&self) -> Fahrenheit {
    Fahrenheit { value: self.value * 9.0 / 5.0 + 32.0 }
  }
}

impl Fahrenheit {
  fn to_celsius(&self) -> Celsius {
    Celsius { value: (self.value - 32.0) * 5.0 / 9.0 }
  }
}

let c = Celsius { value: 0.0 }
let f = c.to_fahrenheit()
f.value  // Returns: 32.0

Expected Output: 32.0

Nested Structs

struct Address {
  street: String,
  city: String,
  zip: String
}

struct Person {
  name: String,
  age: i32,
  address: Address
}

let person = Person {
  name: "Alice",
  age: 30,
  address: Address {
    street: "123 Main St",
    city: "Boston",
    zip: "02101"
  }
}

person.address.city  // Returns: "Boston"

Expected Output: "Boston"

Struct Update Syntax

struct Point {
  x: f64,
  y: f64,
  z: f64
}

let p1 = Point { x: 1.0, y: 2.0, z: 3.0 }
let p2 = Point { x: 10.0, ..p1 }  // Copy y and z from p1

p2.x  // Returns: 10.0
p2.y  // Returns: 2.0
p2.z  // Returns: 3.0

Expected Output: 10.0, 2.0, 3.0

Tuple Structs

Structs without named fields:

struct Color(i32, i32, i32)
struct Point3D(f64, f64, f64)

let black = Color(0, 0, 0)
let origin = Point3D(0.0, 0.0, 0.0)

black.0  // Returns: 0
origin.2  // Returns: 0.0

Expected Output: 0, 0.0

Newtype Pattern

struct UserId(i32)
struct ProductId(i32)

let user = UserId(123)
let product = ProductId(456)

// Type safety: Can't mix UserId with ProductId
// user == product  // Compile error: different types

Use Case: Prevent mixing up values of same underlying type.

Unit Structs

Structs with no fields:

struct Marker
struct EmptyData

let m = Marker
let e = EmptyData

Use Case: Type markers, trait implementations, zero-sized types.

Struct Destructuring

struct Point {
  x: f64,
  y: f64
}

let p = Point { x: 10.0, y: 20.0 }

// Full destructure
let Point { x, y } = p
x  // Returns: 10.0
y  // Returns: 20.0

// Partial destructure
let Point { x: a, .. } = p
a  // Returns: 10.0

Expected Output: 10.0, 20.0, 10.0

Structs vs Objects

// Struct: Type-safe, performant
struct User {
  id: i32,
  name: String
}
let user = User { id: 1, name: "Alice" }

// Object: Flexible, dynamic
let user = { id: 1, name: "Alice" }
user.email = "alice@example.com"  // Can add fields

Common Algorithms

Distance Calculation

struct Point {
  x: f64,
  y: f64
}

impl Point {
  fn distance_to(&self, other: &Point) -> f64 {
    let dx = self.x - other.x
    let dy = self.y - other.y
    sqrt(dx * dx + dy * dy)
  }
}

let p1 = Point { x: 0.0, y: 0.0 }
let p2 = Point { x: 3.0, y: 4.0 }
p1.distance_to(&p2)  // Returns: 5.0

Expected Output: 5.0

Vector Operations

struct Vec2 {
  x: f64,
  y: f64
}

impl Vec2 {
  fn add(&self, other: &Vec2) -> Vec2 {
    Vec2 {
      x: self.x + other.x,
      y: self.y + other.y
    }
  }

  fn magnitude(&self) -> f64 {
    sqrt(self.x * self.x + self.y * self.y)
  }

  fn normalize(&self) -> Vec2 {
    let mag = self.magnitude()
    Vec2 {
      x: self.x / mag,
      y: self.y / mag
    }
  }
}

let v1 = Vec2 { x: 3.0, y: 4.0 }
let v2 = Vec2 { x: 1.0, y: 2.0 }
let v3 = v1.add(&v2)
v3.magnitude()  // Returns: 7.81

Expected Output: 7.81

Best Practices

✅ Use Structs for Domain Models

// Good: Clear domain model
struct Order {
  id: i32,
  customer_id: i32,
  items: Vec<OrderItem>,
  total: f64,
  status: OrderStatus
}

// Bad: Generic object
let order = {
  id: 1,
  customer: 123,
  items: [],
  total: 0.0
}

✅ Implement Constructor Methods

impl Point {
  fn new(x: f64, y: f64) -> Point {
    Point { x, y }
  }

  fn origin() -> Point {
    Point { x: 0.0, y: 0.0 }
  }
}

// Use constructors for clarity
let p = Point::new(10.0, 20.0)

✅ Group Related Methods in impl Block

impl Rectangle {
  // Constructors
  fn new(width: f64, height: f64) -> Rectangle { ... }
  fn square(size: f64) -> Rectangle { ... }

  // Getters
  fn width(&self) -> f64 { ... }
  fn height(&self) -> f64 { ... }

  // Calculations
  fn area(&self) -> f64 { ... }
  fn perimeter(&self) -> f64 { ... }
}

✅ Use Newtypes for Type Safety

struct Meters(f64)
struct Feet(f64)

impl Meters {
  fn to_feet(&self) -> Feet {
    Feet(self.0 * 3.28084)
  }
}

// Type-safe: Can't mix Meters and Feet
let distance = Meters(100.0)
let feet = distance.to_feet()

Summary

✅ Feature Status: WORKING ✅ Test Coverage: 100% ✅ Mutation Score: 98%

Structs provide type-safe, performant data structures with named fields. Use them for domain models, APIs, and any data that benefits from compile-time validation.

Key Takeaways:

• Define with struct Name { field: Type }
• Create instances with Name { field: value }
• Methods with impl Name { fn method(&self) { ... } }
• Associated functions with fn new() -> Name
• Better than objects for typed, structured data
• Use newtypes for type safety

← Previous: Objects/Maps | Next: Enums →