Matching the shape of a value

Every arm of a match starts with a pattern: a description of a shape that a value may or may not have. "/help" is a pattern that fits exactly one piece of text. Command::Say(text) is a pattern that fits any Say and gives its contents a name. Rust checks the arms from top to bottom and runs the first one whose pattern fits.

The bar | joins patterns with "or": "/help" | "/h" fits either word. Both lead to the same code, so the answer is written once and the two words can never drift apart.

A pattern can also be a range. 1..=9 fits any number from 1 to 9, both ends included (the = is what includes the 9). It works for numbers and for single characters, such as 'a'..='z' (single quotes hold exactly one character; double quotes hold text).

When the shape is not enough, add a guard: if and a question after the pattern. n if n >= 100 fits any number, names it n, and then only counts as a fit when the question is true. If the guard says no, Rust moves on to the next arm as if this one had not fitted at all.

A pattern can be shaped like a struct, a pair or a variant, and then it does more than check: it takes the value apart and gives each piece its own name. This works in a let too, not only in a match. Watch what happens to the keys when a Message is taken apart.

Taking apart is moving, by the rules of chapter 4: each field's key goes to its new name. When you only want to look, take apart a borrow instead, as Chatterbox does with &last: then the names inside are borrows and the original stays whole. Taking a pair apart is the same idea: let (major, minor) = VERSION; gives the two numbers of lesson 2.6 a name each.

Two marks say "I do not need this part". _ skips exactly one piece and binds nothing, so nothing moves: Command::Say(_) fits any Say without touching its text. .. skips all the rest: Message { author, .. } takes only the author.

if let and while let

Sometimes only one shape matters. if let Some(text) = &last { … } else { … } is a match with one interesting arm: run the block if the value fits, with text named inside; otherwise run the else. while let is the same question asked again and again, and the loop stops the first time the value does not fit. Here it peels a sentence apart one word at a time:

$ cargo run
peeled off: rust
peeled off: is
last word: fun, 3 words

You met E0004 in lessons 3.2 and 5.3: a match has to cover every value. Patterns that look inside a value make that check sharper, because covering a variant now means covering every shape inside it too. Here Say carries an Option, and only one of its two shapes has an arm:

error[E0004]: non-exhaustive patterns: `Command::Say(None)` not covered
  --> src/main.rs:7:11
   |
 7 |     match cmd {
   |           ^^^ pattern `Command::Say(None)` not covered
   |
note: `Command` defined here
  --> src/main.rs:1:6
   |
 1 | enum Command {
   |      ^^^^^^^
 2 |     Help,
 3 |     Say(Option<String>),
   |     --- not covered
   = note: the matched value is of type `Command`
help: ensure that all possible cases are being handled by adding a match arm with a wildcard pattern or an explicit pattern as shown
   |
 9 ~         Command::Say(Some(text)) => text,
10 ~         Command::Say(None) => todo!(),
   |

When Chatterbox gives a strange answer, the first question is "what did it think I typed?". That means printing a Command. But {} in println! only knows how to print things that have one obvious look for people, like text and numbers. A type you made has no such look until you write one, and asking for it is an error:

error[E0277]: `Command` doesn't implement `Debug`
 --> src/main.rs:8:22
  |
8 |     println!("{:?}", cmd);
  |               ----   ^^^ `Command` cannot be formatted using `{:?}` because it doesn't implement `Debug`
  |               |
  |               required by this formatting parameter
  |
  = help: the trait `Debug` is not implemented for `Command`
help: consider annotating `Command` with `#[derive(Debug)]`
  |
1 + #[derive(Debug)]
2 | enum Command {
  |

The {:?} asks for the debug form: a plain view of a value's shape, meant for the programmer. Command has none, so the compiler says it "doesn't implement Debug". You do not have to write that printing code by hand. Put #[derive(Debug)] on the line above the enum, and the compiler writes it for you: variant name, then whatever is inside, in brackets. The same works for structs. With it, that program prints Say(Some("hi")).

Here is the whole program after this lesson, new lines in green.

• In parse, two arms grow alternatives: "/help" | "/h" means help, and "/quit" | "/q" | "/exit" means quit. The help text lists them too: it now ends /quit (or /h, /q, /exit), after a new /debug <text>.
• Command gets #[derive(Debug)] and a new variant, Debug(Option<String>), built with arg and owned exactly like Say.
• In main, Command::Debug(Some(text)) parses text as if you had typed it, and prints the result with {:?}. So /debug /say hi shows Say(Some("hi")), and /debug hello shows Chat("hello"). (That first output will change in chapter 7, when parse learns to report errors: it becomes Ok(Say("hi")).) A bare /debug gets its own arm, so E0004 stays quiet.
• /again is now an if let Some(text) = &last with an else. It does exactly what the match did; the shape you care about simply comes first.

Sam
/h
/q
after the quit

Chatterbox v0.5
What should I call you?
Hi Sam! I'm Chatterbox. Ask me anything.
bot: commands: /help, /again, /history, /say <text>, /shout <text>, /debug <text>, /quit (or /h, /q, /exit)
bot: bye, Sam!
messages so far: 0

And here is /debug showing how two lines were understood. The quotes and brackets are the derived debug form, straight from the compiler's own printing code.

Sam
/debug /say hi
/debug hello
/quit

Chatterbox v0.5
What should I call you?
Hi Sam! I'm Chatterbox. Ask me anything.
bot: Say(Some("hi"))
bot: Chat("hello")
bot: bye, Sam!
messages so far: 0

Sources The Rust Book: the match control flow construct · The Rust Book: concise control flow with if let · The Rust Reference: patterns · Rust error index: E0004 · Rust standard library: the Debug trait