Basic macros

Four macros you already used, now explained

You already wrote println! in almost every example in this course, and every exercise checked your solution with assert_eq!, without ever explaining what they are or why they carry !. This lesson closes that gap, and along the way closes out module 1 entirely: vec! delivers on the promise “Variables, mutability and types” made about showing a collection that can actually grow.

println!, format!, vec!, and assert! are macros, not functions: that is why they carry !. A macro expands at compile time, so it can accept a variable number of arguments and check your format string before the program even runs.

You will go through four stations, one per macro: println!, format!, vec!, and the assert! family.

CALL · println!macro, not function: note the !
MACRO · Display vs Debug{scores:?} prints the array
RESULT · printed output3 apples · [1, 2, 3]

01 / 04{} · {:?} · {NAME}

{} uses Display; {:?} uses Debug

{} uses the Display trait, meant for human reading; {:?} uses Debug, meant for debugging, and it is the only one that works with collections like arrays. Inside the braces you can write a variable name directly, like {count}.

lib.rsCompiles↗

fn main() {
    let count = 3;
    println!("{count} apples");

    let scores = [1, 2, 3];
    println!("{scores:?}");
}

Result

format! builds a String instead of printing

format! accepts the same syntax as println!, but instead of printing, it returns a String. println! internally uses the same formatting machinery; the only difference is the destination: screen or variable.

lib.rsCompiles↗

/// `format!` uses the same syntax as `println!` but returns a `String`
/// instead of printing it.
#[must_use]
pub fn greeting(name: &str) -> String {
    format!("Hello, {name}!")
}

// Playground entry point for this example.
fn main() {
    println!("{}", greeting("Ferris"));
}

Result

vec! creates a Vec, unlike a fixed-size array

An array has a fixed size: you cannot add elements to it after creating it. vec! creates a Vec, a collection that lives on the heap and can grow or shrink at runtime with .push(), .pop(), and more.

vec! creates a collection of variable size; an array literal does not.

lib.rsCompiles↗

/// `vec!` creates a Vec, a growable collection; unlike an array, its
/// length is not fixed at compile time.
#[must_use]
pub fn grow_scores() -> Vec<i32> {
    let mut scores = vec![10, 20, 30];
    scores.push(40);
    scores
}

// Playground entry point for this example.
fn main() {
    println!("{:?}", grow_scores());
}

Result

assert! and assert_eq! require Debug to explain themselves

You already used assert_eq! without knowing it: every exercise in this course checks your solution with exactly this macro. assert! checks a condition; assert_eq! and assert_ne! compare two values, and if the check fails, the panic message prints them with Debug.

lib.rsCompiles↗

/// `assert!`, `assert_eq!`, and `assert_ne!` panic with a formatted
/// message when the condition is false; here every check passes silently.
///
/// # Panics
///
/// Panics if any of the three checks fails.
#[must_use]
pub fn checks_pass() -> bool {
    let scores = [10, 20, 30];
    assert!(scores[0] < scores[1]);
    assert_eq!(scores.len(), 3);
    assert_ne!(scores[0], scores[1]);
    true
}

// Playground entry point for this example.
fn main() {
    println!("{}", checks_pass());
}

Result

That is why assert_eq! requires the type to implement Debug: without it, there is no way to show the value that failed.

lib.rsDoes not compile↗

#[derive(PartialEq)]
struct Point(i32, i32);

fn main() {
    let a = Point(1, 2);
    let b = Point(1, 2);
    assert_eq!(a, b); // ERROR: Point doesn't implement Debug
}

Result

The compiler says (E0277)

`Point` doesn't implement `Debug`. assert_eq! needs Debug on both sides to be able to explain a failure.

error[E0277]: `Point` doesn't implement `Debug`
--> src/main.rs:7:5
|
7 |     assert_eq!(a, b);
|     ^^^^^^^^^^^^^^^^ the trait `Debug` is not implemented for `Point`
|
= note: add `#[derive(Debug)]` to `Point` or manually `impl Debug for Point`
help: consider annotating `Point` with `#[derive(Debug)]`
|
2 + #[derive(Debug)]
3 | struct Point(i32, i32);
|

.forge-journey { height: auto !important; } .forge-journey__viewport { position: static !important; height: auto !important; display: block !important; } .forge-journey__stage { min-height: auto; overflow: visible; } .forge-journey__fallback { position: static !important; width: auto !important; height: auto !important; margin: 0 !important; clip: auto !important; overflow: visible !important; } .forge-journey__fallback-chapter[hidden] { display: block !important; margin-bottom: 2rem; } .forge-journey__panel { min-height: auto !important; } .forge-journey__chapter { position: static !important; opacity: 1 !important; visibility: visible !important; transform: none !important; border-bottom: 1px solid rgba(255,255,255,.12); } .forge-journey__panel-header, .forge-journey__controls { display: none !important; }

Objective

Complete build_report so it returns a String in the format "scores: [a, b, c], total: sum", using vec!, a for loop to sum, and format!.

Implement

Replace `todo!` with `vec![a, b, c]`, a `for` loop that sums, and `format!` with `{scores:?}` and `{sum}`.

Group the three values in a Vec, sum them with a for loop, and format the result with format!.

pub fn build_report(a: i32, b: i32, c: i32) -> String {
    todo!("build a Vec with vec![a, b, c], sum it with a for loop, and format the result")
}

Check

Run the visible cases and use the diagnostic to correct the code.

Visible tests

produces the exact text for both positive and negative values

Compiler—

Modify the code before running the tests.

Help

View progressive hints or compare with the solution.

Commented solutionSolution↗

/// Builds a report string from three scores using vec! and format!.
#[must_use]
pub fn build_report(a: i32, b: i32, c: i32) -> String {
    let scores = vec![a, b, c];
    let mut sum = 0;

    for score in &scores {
        sum += score;
    }

    format!("scores: {scores:?}, total: {sum}")
}

// Playground entry point for this example.
fn main() {
    println!("{}", build_report(10, 20, 30));
}

Result

Summary

println!, format!, vec!, and assert! are macros, not functions: that is why they carry !.
{} uses Display (human reading); {:?} uses Debug (debugging), and it is the only one that works with collections.
format! builds a String with the same syntax as println!, without printing anything.
vec! creates a Vec of variable size; unlike an array, it supports .push() and .pop().
assert!, assert_eq!, and assert_ne! panic with a formatted message when the check fails.
assert_eq!/assert_ne! require the type to implement Debug, to be able to print both sides if they fail.

Sources

The Rust Programming Languagech08-01 · Klabnik, Nichols, Krycho y la comunidad de Rust
Rust by Examplehello/print
Comprehensive Rustbasic-syntax/println · Geisler y colaboradores (Google)

Four macros you already used, now explained

Build a report with vec! and format!.

Implement

Build the report

Check

Help

Summary

Sources