When one match arm is too much
You are parsing a configuration file. The file might contain a database section. Inside that section, there might be a host string. You write a match statement to extract the host. The match requires you to handle the case where the database is missing. It also requires you to handle the case where the host is missing. You add two underscore arms to ignore those cases. The code is correct, but it is noisy. You are writing boilerplate to tell the compiler you don't care about the negative cases.
Rust offers a shortcut for this exact situation. if let lets you check for one specific pattern and run code only when it matches. while let repeats that check until the pattern fails. They cut the noise and keep your focus on the case that matters.
Targeted pattern matching
Pattern matching in Rust is exhaustive. A match expression must cover every possible variant of a type. This rule prevents logic errors where a new variant is added and forgotten. The rule is powerful. It also forces you to write code for cases you might want to ignore.
if let relaxes this requirement for a single case. It asks one question: does this value match this pattern? If the answer is yes, the code block runs with the bound variables. If the answer is no, the block is skipped entirely. There is no fallback. There is no requirement to handle the other variants.
Think of match as a switchboard operator who must route every call. if let is checking if a specific light is on. If the light is on, you flip a switch. If it is off, you walk away. You do not need to check every other light on the wall.
while let extends this idea to loops. It evaluates an expression, checks the pattern, and runs the block. It repeats this cycle until the pattern fails. When the pattern fails, the loop breaks. This makes while let ideal for consuming collections or repeating an action until a condition changes.
Minimal examples
Here is the basic syntax for both constructs.
fn main() {
// if let checks a single pattern and runs code if it matches.
// This is cleaner than match when you only care about one variant.
let maybe_port = Some(8080);
if let Some(port) = maybe_port {
println!("Server listening on port {port}");
}
// while let loops as long as the pattern matches.
// It breaks automatically when the pattern fails.
let mut stack = vec![1, 2, 3];
while let Some(top) = stack.pop() {
println!("Processing item {top}");
}
}
The if let block prints the port only if maybe_port is Some. If it were None, the print statement would never execute. The while let loop pops items from the vector one by one. When stack.pop() returns None, the pattern fails, and the loop terminates.
What happens under the hood
if let and while let are syntactic sugar. They do not introduce runtime overhead. The compiler desugars them into match expressions and loops.
An if let desugars to a match with two arms. The first arm handles the pattern you specified. The second arm is a wildcard that does nothing.
// This if let...
if let Some(port) = maybe_port {
println!("{port}");
}
// Desugars to this match...
match maybe_port {
Some(port) => {
println!("{port}");
}
_ => {}
}
The generated machine code is identical. The choice between if let and match is purely about readability and intent. if let signals to the reader that you are interested in exactly one case and are intentionally ignoring the rest.
Variables bound inside an if let block are scoped to that block. This is a safety feature. If the pattern fails, the variables never exist. The compiler prevents you from using them outside the block. This eliminates a whole class of bugs where code accidentally uses an uninitialized value.
fn main() {
let config = Some("localhost");
if let Some(host) = config {
// host is valid here.
println!("Connecting to {host}");
}
// host does not exist here.
// The compiler rejects this with E0425 (cannot find value).
// println!("{host}");
}
The scoping rule applies to while let as well. Variables bound in the loop body are fresh for each iteration. They do not leak out of the loop.
Realistic usage: drilling into config
A common pattern in Rust code is drilling down through nested optional structures. Configuration objects, JSON parsers, and AST traversals often contain layers of Option or Result. if let chains make this readable.
#[derive(Debug)]
struct Config {
database: Option<Database>,
}
#[derive(Debug)]
struct Database {
host: Option<String>,
port: Option<u16>,
}
fn print_connection_info(config: &Config) {
// Chain if let to drill down only when data exists.
// Each level checks for Some before proceeding.
if let Some(db) = &config.database {
if let Some(host) = &db.host {
// Port is optional. Use a default if missing.
let port = db.port.unwrap_or(5432);
println!("Connecting to {host}:{port}");
}
}
}
fn main() {
let cfg = Config {
database: Some(Database {
host: Some("db.example.com".to_string()),
port: None,
}),
};
print_connection_info(&cfg);
}
The nested if let structure mirrors the nested data structure. The code only reaches the print statement if both the database and the host exist. If either is missing, the chain short-circuits and the function returns silently.
Convention aside: Keep if let chains shallow. Two levels of nesting are usually fine. Three levels start to look like a pyramid. If you find yourself nesting deeper, consider refactoring the data structure or using a helper function to extract the value. Deep nesting hurts readability and makes error handling harder.
While let for streams and state
while let shines when processing streams of data or state machines where the termination condition is embedded in the data itself. Reading from a file, processing a queue, or iterating over a parser token stream are natural fits.
use std::io::{self, BufRead};
fn read_lines() {
let stdin = io::stdin();
let mut lines = stdin.lock().lines();
// lines.next() returns Option<Result<String, Error>>.
// We loop while we get Some(result).
// Inside, we handle the Result.
while let Some(result) = lines.next() {
match result {
Ok(line) => println!("Read: {line}"),
Err(e) => eprintln!("Error reading line: {e}"),
}
}
}
fn main() {
read_lines();
}
Here, while let handles the Option layer. The loop continues as long as lines.next() returns Some. When the stream ends, next() returns None, the pattern fails, and the loop breaks. The inner match handles the Result layer. This separation keeps the loop control logic distinct from the error handling logic.
You can also combine while let with Result directly if you want to stop on the first error.
fn process_until_error() {
let mut data = vec![Ok(1), Ok(2), Err("fail"), Ok(4)];
// Loop while the next item is Ok(value).
// Stops immediately when an Err is encountered.
while let Some(Ok(value)) = data.pop() {
println!("Processing {value}");
}
// The Err("fail") remains in the vector.
}
This pattern is useful for pipelines where a single error should halt processing. The loop breaks as soon as the pattern Ok(value) fails to match.
Convention aside: Reach for for loops when iterating over a collection. while let Some(item) = iterator.next() works, but for item in iterator is the idiomatic choice. Use while let when you are mutating the container, like popping from a Vec, or when the loop condition depends on complex state that a for loop cannot express.
Pitfalls and compiler warnings
if let and while let are safe, but they can hide logic errors if used carelessly.
Ignoring important cases
The biggest risk with if let is using it when you actually need to handle the non-matching case. if let swallows the negative case. If the None case represents an error that should propagate, if let is the wrong tool.
fn get_host(config: &Config) -> String {
// BAD: If host is None, this returns an empty string silently.
// The caller might crash later when trying to connect.
let mut host = String::new();
if let Some(db) = &config.database {
if let Some(h) = &db.host {
host = h.clone();
}
}
host
}
If the host is required, the function should fail fast. Use let-else or a match that returns an error. if let is for optional behavior, not for fallible extraction.
Refutable patterns on irrefutable values
If you use if let on a value that always matches the pattern, the compiler warns you. This is error code E0005. The compiler knows the check is redundant and suggests using a plain let.
fn main() {
let x = 5;
// Warning: E0005 refutable pattern in local binding.
// The compiler suggests: let Some(x) = Some(5);
// Or just: let x = 5;
if let Some(value) = Some(x) {
println!("{value}");
}
}
Trust this warning. If the pattern always matches, you are writing noise. Replace if let with let to remove the unnecessary check.
Infinite loops
while let loops until the pattern fails. If the expression never produces a non-matching value, the loop runs forever. This usually happens when the loop body does not change the state that drives the pattern.
fn main() {
let mut counter = 0;
// BAD: counter never changes. Some(counter) always matches.
// This loop runs forever.
while let Some(n) = Some(counter) {
println!("{n}");
}
}
Ensure the expression inside while let changes over time. Usually, this means consuming a collection, mutating a variable, or reading from an external source that eventually ends.
Decision matrix
Choose the right tool based on what you need to handle.
Use match when you need to handle every possible variant or return different values for different cases. Use match when the logic branches significantly based on the data shape. Use match when you need to extract values from multiple variants in a single expression.
Use if let when you care about exactly one variant and want to ignore the rest. Use if let when the non-matching case requires no action. Use if let for drilling into nested optional structures where you only proceed if data exists.
Use while let when you want to consume a collection or repeat an action until a condition fails. Use while let when the termination condition is embedded in the return value of the loop expression. Use while let for state machines where the next state determines whether to continue.
Use let-else when the pattern failing means the function should return early with an error. Use let-else for fallible extraction where the value is required for the rest of the function. Use let-else to avoid deep nesting when multiple required values must be extracted.
Use for loops when iterating over a collection without mutating the container. Use for when you want to process every item and do not need to control the iteration manually.