DEV Community: SomeB1oody

[Rust Guide] 13.5. Iterators - Definitions, the Iterator Trait, and the Next Method

SomeB1oody — Mon, 22 Jun 2026 03:24:58 +0000

13.5.0 Before We Begin

During its design, Rust drew inspiration from many languages, and functional programming had a particularly strong influence on Rust. Functional programming often includes passing functions as values to parameters, returning them from other functions, assigning them to variables for later execution, and so on.

In this chapter, we will discuss some Rust features that are similar to what many languages call functional features:

Closures
Iterators (this article)
Improving the I/O Project with Closures and Iterators
Performance of Closures and Iterators

If you find this helpful, please like, bookmark, and follow. To keep learning along, follow this series.

13.5.1 What Is an Iterator

To talk about iterators, we first need to talk about the iterator pattern. The iterator pattern allows you to perform a task on each element in a sequence, one by one. In that process, the iterator is responsible for:

Traversing each item
Determining when the sequence has finished iterating

Rust iterators are lazy: unless you call a method that consumes the iterator, the iterator itself does nothing. In other words, if you write an iterator in your code but never use it, it is as if it did nothing at all.

Take a look at an example:

fn main() {
    let v1 = vec![1, 2, 3];
    let v1_iter = v1.iter();
}

v1 is a Vector, and v1.iter() creates an iterator for v1 and assigns it to v1_iter. But v1_iter is not used yet, so the iterator can be considered to have no effect.

Now let’s use the iterator to traverse the values:

fn main() {
    let v1 = vec![1, 2, 3];
    let v1_iter = v1.iter();
    for val in v1_iter {
        println!("Got: {}", val);
    }
}

This is equivalent to using each element in the iterator once in a loop.

13.5.2 The `Iterator` Trait

All iterators implement the Iterator trait. This trait is defined in the standard library and looks roughly like this:

pub trait Iterator {
    type Item;

    fn next(&mut self) -> Option<Self::Item>;

    // methods with default implementations elided
}

Two new pieces of syntax appear here: type Item and Self::Item. These syntax forms define types associated with the trait, and we will talk about that in a later article. For now, all you need to know is that implementing the Iterator trait requires you to define an Item type, and that type is used as the return type of next (the iterator’s return type).

The Iterator trait requires only one method: next. Each time next is called, it returns one item from the iterator, that is, one element of the sequence. Because the return type is Option, the result is wrapped in the Some variant. When iteration ends, None is returned.

In actual use, you can call next directly on the iterator. Take a look at an example:

#[cfg(test)]
mod tests {
    #[test]
    fn iterator_demonstration() {
        let v1 = vec![1, 2, 3];

        let mut v1_iter = v1.iter();

        assert_eq!(v1_iter.next(), Some(&1));
        assert_eq!(v1_iter.next(), Some(&2));
        assert_eq!(v1_iter.next(), Some(&3));
        assert_eq!(v1_iter.next(), None);
    }
}

v1 is a Vector, and v1_iter is its iterator. Because the operations below are considered to change the iterator’s state, mut must be used to make it mutable.
assert_eq!(v1_iter.next(), Some(&1)); is the first call to next, so it returns the first element in the Vector, wrapped in Some, which is Some(&1). It is &1 because the iterator’s return value is an immutable reference wrapped by Option.
assert_eq!(v1_iter.next(), Some(&2)); is the second call to next, so it returns the second element in the Vector, wrapped in Some, which is Some(&2).
And so on...
Calling next on an iterator changes the iterator’s internal state that tracks its position in the sequence. In other words, each call consumes one element from the iterator. The for loop in the 13.5.1 example does not need mut because the for loop actually takes ownership of v1_iter.

13.5.3 Several Iteration Methods

The iter method we just used generates an iterator over immutable references, so the values obtained through next are actually immutable references to the elements in the Vector.

The into_iter method creates an iterator that takes ownership. In other words, as it iterates through the elements, it moves them into the new scope and takes ownership of them.

The iter_mut method uses mutable references when traversing values.

[Rust Guide] 13.4. Capturing the Environment With Closures

SomeB1oody — Mon, 22 Jun 2026 03:21:26 +0000

13.4.0 Before We Begin

In this chapter, we will discuss some Rust features that are similar to what many languages call functional features:

Closures (this article)
Iterators
Improving the I/O Project with Closures and Iterators
Performance of Closures and Iterators

If you find this helpful, please like, bookmark, and follow. To keep learning along, follow this series.

13.4.1 Closures Can Capture Their Environment

Closures have a capability that functions do not: a closure can access variables in the scope where it is defined.

Take a look at an example:

fn main() {
    let x = 4;
    let equal_to_x = |z| z == x;
    let y = 4;
    assert!(equal_to_x(y));
}

The closure part is:

let equal_to_x = |z| z == x;

Some people may find it hard to distinguish the roles of = and == here, so let’s rewrite it another way:

let equal_to_x = |z| {
    z == x;
}

In other words, the closure takes z as its parameter, compares it with x (which is 4, because x = 4 was defined above), and returns a boolean. If they are equal, the result is true; otherwise it is false.

Here the closure directly accesses the variable x in the same scope, which functions cannot do.

But this feature has a cost: it introduces memory overhead. In most cases we do not need a closure to capture its environment, and we do not want the extra overhead either. That is why functions are not allowed to capture variables from the environment, and defining and using a function never introduces this kind of overhead.

13.4.2 How Closures Capture Values From Their Environment

Closures capture values from the environment in three ways, just like functions receive parameters in three ways:

Taking ownership, whose trait is FnOnce because a closure cannot take and consume the same variable more than once, so it can only be called once.
Mutable borrowing, whose trait is FnMut
Immutable borrowing, whose trait is Fn

When a programmer creates a closure, Rust infers which trait should be used based on how the closure uses values from the environment:

All closures implement FnOnce, because every closure can be called at least once
Closures that do not move captured variables implement FnMut
Closures that do not need mutable access to captured variables implement Fn

In fact, these three have an inclusion relationship: every Fn also implements FnMut, and every FnMut also implements FnOnce.

13.4.3 The `move` Keyword

Using the move keyword before the parameter list forces a closure to take ownership of the environment values it uses. This is most useful when passing a closure to a new thread and moving data so that it belongs to that new thread.

Take a look at an example:

fn main() {
    let x = vec![1, 2, 3];
    let equal_to_x = move |z| z == x;
    println!("can't use x here {:?}", x);
    let y = vec![1, 2, 3];
    assert!(equal_to_x(y));
}

After using move, ownership of x moves into the closure, so x can no longer be used afterward.

13.4.4 Best Practice

When you specify one of the Fn trait bounds, start with Fn. Depending on what happens inside the closure, the compiler will tell you if FnOnce or FnMut is needed instead.

[Rust Guide] 13.3. Storing Closures With Generic Parameters and Fn Traits

SomeB1oody — Mon, 22 Jun 2026 03:13:20 +0000

13.3.0 Before We Begin

In this chapter, we will discuss some Rust features that are similar to what many languages call functional features:

Closures (this article)
Iterators
Improving the I/O Project with Closures and Iterators
Performance of Closures and Iterators

If you find this helpful, please like, bookmark, and follow. To keep learning along, follow this series.

13.3.1 Review

Do you remember the example from 13.1?

Build a program that generates a personalized workout plan based on factors such as a person's body metrics. The algorithm itself is not the point; the important part is that it takes a few seconds to run. Our goal is to avoid unnecessary waiting for the user. More specifically, we want to call the algorithm only when necessary, and only once.

At that time, we rewrote the code as:

use std::thread;  
use std::time::Duration;  

fn main() {  
    let simulated_user_specified_value = 10;  
    let simulated_random_number = 7;  

    generate_workout(  
        simulated_user_specified_value,  
        simulated_random_number,  
    );  
}  

fn generate_workout(intensity: u32, random_number: u32) {  
    let expensive_closure = |num| {  
        println!("calculating slowly...");  
        thread::sleep(Duration::from_secs(2));  
        num  
    };  
    if intensity < 25 {  
        println!("Today, do {} pushups!", expensive_closure(intensity));  
        println!("Next, do {} situps!", expensive_closure(intensity));
    } else {  
        if random_number == 3 {  
            println!("Take a break today! Remember to stay hydrated!");  
        } else {  
            println!("Today, run for {} minutes!", expensive_closure(intensity));  
        }  
    }  
}

But there is still a problem: this does not solve the repeated-closure-call problem. When intensity is less than 25, the closure is called twice.

One possible solution is to assign the closure’s value to a local variable and let that local variable be reused by the output statements. The problem with that approach is that it introduces some code duplication.

So a better solution here is: create a struct that holds the closure and its call result. In other words, after the closure is called for the first time, store the result inside the closure holder; if the closure needs to be called again later, just use the cached result. The effect is that the closure runs only when the result is needed, and the result can be cached.

This pattern is usually called memoization or lazy evaluation.

13.3.2 Having a Struct Hold a Closure

Based on the solution above, the current problem is how to make a struct hold a closure.

A struct definition needs to know the type of every field, so if you want to store a closure inside a struct, you must specify the closure’s type.

Each closure instance has its own unique anonymous type. Even if two closures have exactly the same signature, they are still two different types. So storing closures requires generics and trait bounds. The content on generics and trait bounds is covered in 10.4. Trait Pt.2, which is worth a look.

13.3.3 `Fn` Trait

The Fn trait is provided by the standard library. Every closure implements at least one of the following Fn traits:

Fn
FnMut
FnOnce

The differences among these three Fn traits will be covered in the next article. In this example, Fn is enough.

With that in mind, we can rewrite the example. First, create a struct:

struct Cache<T: Fn(u32) -> u32>  
{  
    calculation: T,  
    value: Option<u32>,  
}

This struct has a generic parameter T. Since it represents the closure type, its bound is the Fn trait (Fn is enough in this example), and because the parameter and return types are u32, we write Fn(u32) -> u32.
The field that stores the closure is calculation, and its type is T.
The cached value is stored in the value field. Its type is u32, but we do not yet know whether the value has been calculated and cached, so we wrap it in Option, which means Option<u32>.

First, write a constructor on the struct to create instances:

impl<T: Fn(u32) -> u32> Cache<T> {  
    fn new(calculation: T) -> Cache<T> {  
        Cache {  
            calculation,  
            value: None,  
        }  
    }  
}

This looks a little messy, so we can rewrite it with a where clause:

impl<T> Cache<T>   
where   
    T: Fn(u32) -> u32  
{  
    fn new(calculation: T) -> Cache<T> {  
        Cache {  
            calculation,  
            value: None,  
        }  
    }  
}

Then, make value return the cached value if it exists, or calculate it if it does not:

fn value(&mut self, arg: u32) -> u32 {  
    match self.value {  
        Some(v) => v,  
        None => {  
            let v = (self.calculation)(arg);  
            self.value = Some(v);  
            v  
        }  
    }  
}

If the instance’s value field already has a value, return it. Otherwise calculate the value, store it in the value field, and return it.

Once that is done, we should update generate_workout to use the Cache struct:

fn generate_workout(intensity: u32, random_number: u32) {  
    let mut expensive_closure = Cache::new(|num|{  
        println!("calculating slowly...");  
        thread::sleep(Duration::from_secs(2));  
        num  
    });  
    if intensity < 25 {  
        println!("Today, do {} pushups!", expensive_closure.value(intensity));  
        println!("Next, do {} situps!", expensive_closure.value(intensity));  
    } else {  
        if random_number == 3 {  
            println!("Take a break today! Remember to stay hydrated!");  
        } else {  
            println!("Today, run for {} minutes!", expensive_closure.value(intensity));  
        }  
    }  
}

expensive_closure is created as an instance of Cache, and we pass the closure into new. We add mut to expensive_closure because later calls may change the value stored in the value field.
All later uses of the result go through the value method.

13.3.4 Limitations of the Cache Implementation

The Cache field here is a cache, used to store a value, but this implementation has limitations.

Here is the Cache definition and its methods:

struct Cache<T: Fn(u32) -> u32>  
{  
    calculation: T,  
    value: Option<u32>,  
}  

impl<T> Cache<T>   
where   
    T: Fn(u32) -> u32  
{  
    fn new(calculation: T) -> Cache<T> {  
        Cache {  
            calculation,  
            value: None,  
        }  
    }  

    fn value(&mut self, arg: u32) -> u32 {  
        match self.value {  
            Some(v) => v,  
            None => {  
                let v = (self.calculation)(arg);  
                self.value = Some(v);  
                v  
            }  
        }  
    }  
}

The value method always ends up with the same value: if the value field has no value, it calculates one and stores it in the field. After that, any later use of value gets the originally calculated value, no matter what argument is passed in.

That may sound a little vague, so let’s look at an example:

fn call_with_different_values(){
    let mut c = Cache::new(|a| a);
    let v1 = c.value(1);
    let v2 = c.value(2);
}

c is an instance of Cache, and a closure is passed in.
In the line let v1 = c.value(1);, the original value field in c is empty. At that point, passing in 1 makes the value field become Some(1) (value is an Option type).
In the line let v2 = c.value(2);, because the value field already has a value, it directly takes the 1 stored in value and assigns it to v2, even though the argument to value in this line is different from the previous one.

If you do not want that behavior, you should use a HashMap instead of a single value, using the HashMap key as the args passed to the value method, and the value as the result of executing the closure. For example:

struct ForFun<T: Fn(u32) -> u32>  
{  
    calculation: T,  
    value: HashMap<u32, Option<u32>>,  
}  

impl<T> ForFun<T>  
where  
    T: Fn(u32) -> u32  
{  
    fn new(calculation: T) -> ForFun<T> {  
        ForFun {  
            calculation,  
            value: HashMap::new(),  
        }  
    }  

    fn value(&mut self, arg: u32) -> u32 {  
        match self.value.get(&arg) {  
            Some(v) => v.unwrap(),  
            None => {  
                let v = (self.calculation)(arg);  
                self.value.insert(arg, Some(v));  
                v  
            }  
        }  
    }  
}

This cache example can only accept the same parameter type and return type. If you want the closure’s parameter type and return type to be different, you can introduce two or more generic parameters. For example:

struct ForFun<T, R>  
where  
    T: Fn(u32) -> R,  
{  
    calculation: T,  
    value: Option<R>,  
}

[Rust Guide] 13.2. Closure Type Inference and Annotations

SomeB1oody — Mon, 22 Jun 2026 02:55:58 +0000

13.2.0 Before We Begin

In this chapter, we will discuss some Rust features that are similar to what many languages call functional features:

Closures (this article)
Iterators
Improving the I/O Project with Closures and Iterators
Performance of Closures and Iterators

If you find this helpful, please like, bookmark, and follow. To keep learning along, follow this series.

13.2.1 Type Inference for Closures

Unlike functions defined with fn, closures do not require explicit type annotations for parameters or return values.

Functions must be explicit because they are part of a public interface exposed to users, and a clearly defined interface helps everyone agree on the parameter and return types.

Closures are not used as exposed interfaces. They are usually stored in variables, they do not need names when used, and they are not exposed to users of our codebase. Therefore, closures do not require explicit type annotations for parameters and return values.

Closures are also usually short and work only in a narrow context, so the compiler can often infer the types. Of course, you can still write the annotations manually if you want to.

Take a look at an example:
This is the version using a function definition:

fn simulated_expensive_calculation(intensity: u32) -> u32 {  
    println!("calculating slowly...");  
    thread::sleep(Duration::from_secs(2));  
    intensity  
}

This is the version using a closure:

let expensive_closure = |num:u32| -> u32 {  
    println!("calculating slowly...");  
    thread::sleep(Duration::from_secs(2));  
    num  
};

Explicit annotations are used here because there is no surrounding context for Rust to infer the types. If there is context, then they are not needed:

fn generate_workout(intensity: u32, random_number: u32) {  
    let expensive_closure = |num| {  
        println!("calculating slowly...");  
        thread::sleep(Duration::from_secs(2));  
        num  
    };  
    if intensity < 25 {  
        println!("Today, do {} pushups!", expensive_closure(intensity));  
        println!("Next, do {} situps!", expensive_closure(intensity));  
    } else {  
        if random_number == 3 {  
            println!("Take a break today! Remember to stay hydrated!");  
        } else {  
            println!("Today, run for {} minutes!", expensive_closure(intensity));  
        }  
    }  
}

The parameter num does not need an explicit type annotation because the argument passed in the later call is intensity, whose type is u32, so Rust infers that num is also u32.

13.2.2 Syntax for Function and Closure Definitions

Here are four examples:

 fn add_one_v1   (x: u32) -> u32 { x + 1 }
let add_one_v2 = |x: u32| -> u32 { x + 1 };
let add_one_v3 = |x|             { x + 1 };
let add_one_v4 = |x|               x + 1  ;

The first is a function definition, with a function name, parameter names and types, and a return type
The second is a closure definition, with parameter and return types. This closure looks very similar to a function definition.
The third is also a closure, but its parameter and return types are not annotated, so the compiler has to infer them.
The fourth closure differs from the third in that it does not use curly braces {}. Because it contains only one expression, the braces can be omitted.

13.2.3 Type Inference for Closures

A closure’s definition will ultimately infer only one specific concrete type for its parameters and return value.

Take a look at an example:

    let example_closure = |x| x;

    let s = example_closure(String::from("hello"));
    let n = example_closure(5);

Output:

$ cargo run
   Compiling closure-example v0.1.0 (file:///projects/closure-example)
error[E0308]: mismatched types
 --> src/main.rs:5:29
  |
5 |     let n = example_closure(5);
  |             --------------- ^- help: try using a conversion method: `.to_string()`
  |             |               |
  |             |               expected `String`, found integer
  |             arguments to this function are incorrect
  |
note: expected because the closure was earlier called with an argument of type `String`
 --> src/main.rs:4:29
  |
4 |     let s = example_closure(String::from("hello"));
  |             --------------- ^^^^^^^^^^^^^^^^^^^^^ expected because this argument is of type `String`
  |             |
  |             in this closure call
note: closure parameter defined here
 --> src/main.rs:2:28
  |
2 |     let example_closure = |x| x;
  |                            ^

For more information about this error, try `rustc --explain E0308`.
error: could not compile `closure-example` (bin "closure-example") due to 1 previous error

When the compiler sees the first call to the closure, it determines that both the input and output values are String, so it locks in String as the parameter and return type for this closure. That is why a later call with an integer causes an error.

[Rust Guide] 13.1. What Is a Closure and How to Use Closures

SomeB1oody — Mon, 22 Jun 2026 02:49:14 +0000

13.1.0 Before We Begin

In this chapter, we will discuss some Rust features that are similar to what many languages call functional features:

Closures (this article)
Iterators
Improving the I/O Project with Closures and Iterators
Performance of Closures and Iterators

If you find this helpful, please like, bookmark, and follow. To keep learning along, follow this series.

13.1.1 What Is a Closure

In one sentence: a closure is an anonymous function that can capture values from its surrounding environment.

A closure has four characteristics:

A closure is an anonymous function
This anonymous function can be stored in a variable, passed as an argument to another function, or returned from another function
You can create a closure in one place and call it in another place to do the work
A closure can capture values from the scope in which it is defined

13.1.2 An Example of a Closure

To better demonstrate what closures can do, here is an example:

Build a program that generates a personalized workout plan based on factors such as a person's body metrics. The algorithm itself is not the point; the important part is that it takes a few seconds to run. Our goal is to avoid unnecessary waiting for the user. More specifically, we want to call the algorithm only when necessary, and only once.

Take a look at the code:

use std::thread;  
use std::time::Duration;  

fn main() {  
    let simulated_user_specified_value = 10;  
    let simulated_random_number = 7;  

    generate_workout(  
        simulated_user_specified_value,  
        simulated_random_number,  
    );  
}  

fn simulated_expensive_calculation(intensity: u32) -> u32 {  
    println!("calculating slowly...");  
    thread::sleep(Duration::from_secs(2));  
    intensity  
}  

fn generate_workout(intensity: u32, random_number: u32) {  
    if intensity < 25 {  
        println!("Today, do {} pushups!", simulated_expensive_calculation(intensity));  
        println!("Next, do {} situps!", simulated_expensive_calculation(intensity));  
    } else {  
        if random_number == 3 {  
            println!("Take a break today! Remember to stay hydrated!");  
        } else {  
            println!("Today, run for {} minutes!", simulated_expensive_calculation(intensity));  
        }  
    }  
}

The simulated_expensive_calculation function simulates that expensive algorithm, and thread::sleep simulates the time required for the algorithm to finish. Since this is only a demo, the function simply returns the intensity parameter, which represents the user's requested intensity.
generate_workout has two parameters: intensity, which represents the user's requested workout intensity, and random_number, which represents a random number. The logic is: if intensity is less than 25, print Today, do {} pushups! and Next, do {} situps!. The problem is that both lines call the relatively expensive simulated_expensive_calculation. If intensity is greater than or equal to 25 and the random number is 3, print Take a break today! Remember to stay hydrated! and do not call the expensive function. If the random number is not 3, print Today, run for {} minutes!, which does call simulated_expensive_calculation.

This function is correct as written, but it is too slow. Our goal is to avoid unnecessary waiting for the user. More specifically, we want to call the algorithm only when necessary, and only once.

First, look at the case in generate_workout where intensity is less than 25:

if intensity < 25 {  
        println!("Today, do {} pushups!", simulated_expensive_calculation(intensity));  
        println!("Next, do {} situps!", simulated_expensive_calculation(intensity));

This prints Today, do {} pushups! and Next, do {} situps!. The problem is that both lines call the slow simulated_expensive_calculation. In fact, we only need to calculate the result once and reuse it in both outputs.

Let’s optimize this part. We only need to run the calculation once, store the result in a variable, and use that variable in the output, which avoids calling simulated_expensive_calculation twice:

fn generate_workout(intensity: u32, random_number: u32) {  
    let expensive_result = simulated_expensive_calculation(intensity);  
    if intensity < 25 {  
        println!("Today, do {} pushups!", expensive_result);  
        println!("Next, do {} situps!", expensive_result);  
    } else {  
        if random_number == 3 {  
            println!("Take a break today! Remember to stay hydrated!");  
        } else {  
            println!("Today, run for {} minutes!", expensive_result);  
        }  
    }  
}

Here I also replaced the intensity > 25 and random_number != 3 case with the variable expensive_result that stores the calculation result.

But this creates another problem:

if random_number == 3 {  
    println!("Take a break today! Remember to stay hydrated!");  
}

Here we do not need to call the expensive function, but because

let expensive_result = simulated_expensive_calculation(intensity);

is executed at the start of the function, the calculation still runs even when the random number is 3. That is an unnecessary call.

This is where closures come in. Let’s rewrite this code with a closure:

fn generate_workout(intensity: u32, random_number: u32) {  
    let expensive_closure = |num| {  
        println!("calculating slowly...");  
        thread::sleep(Duration::from_secs(2));  
        num  
    };  
    if intensity < 25 {  
        println!("Today, do {} pushups!", expensive_closure(intensity));  
        println!("Next, do {} situps!", expensive_closure(intensity));  
    } else {  
        if random_number == 3 {  
            println!("Take a break today! Remember to stay hydrated!");  
        } else {  
            println!("Today, run for {} minutes!", expensive_closure(intensity));  
        }  
    }  
}

The closure is this part:

let expensive_closure = |num| {  
    println!("calculating slowly...");  
    thread::sleep(Duration::from_secs(2));  
    num  
};

The closure is assigned to the variable expensive_closure.
The closure needs parameters, and parameters are placed between the two pipe symbols ||. Here there is only one parameter, num, so we write |num|. If there are two parameters, separate them with a comma, such as |num1, num2|. If no parameters are needed, just write ||.
The parameter num does not need an explicit type annotation because the argument passed in the later call is intensity, whose type is u32, so Rust infers that num is also u32.
The closure body is written inside {}, just like any other function. Here we want this closure to do the same work as the expensive calculation function, so the body can be the same. At that point, the simulated_expensive_calculation function can be removed.
This closure definition only defines a function; it does not execute it. A function only runs when it sees (), such as expensive_closure(intensity).

With this version, when intensity is greater than 25 and random_number is not 3, the expensive calculation will not be called, so there is no unnecessary work. However, this still does not solve the problem of repeated closure calls. We will address that in the next article.

[Rust Guide]12.8. Writing Error Messages to Standard Error

SomeB1oody — Sat, 23 May 2026 22:19:13 +0000

12.8.0 Before We Begin

Chapter 12 builds a sample project: a command-line program. The program is grep (Global Regular Expression Print), a tool for global regular-expression searching and output. Its function is to search for specified text in a specified file.

This project is divided into these steps:

Receiving command-line arguments
Reading files
Refactoring: improving modules and error handling
Using TDD (test-driven development) to develop library functionality
Using environment variables
Writing error messages to standard error instead of standard output (this article)

If you find this helpful, please like, bookmark, and follow. To keep learning along, follow this series.

12.8.1 Review

Here is all the code written up to the previous article.

lib.rs:

use std::error::Error;
use std::fs;

pub struct Config {
    pub query: String,
    pub filename: String,
    pub case_sensitive: bool,
}

impl Config {
    pub fn new(args: &[String]) -> Result<Config, &'static str> {
        if args.len() < 3 {
            return Err("Not enough arguments");
        }
        let query = args[1].clone();
        let filename = args[2].clone();
        let case_sensitive = std::env::var("IGNORE_CASE").is_err();
        Ok(Config {
            query,
            filename,
            case_sensitive,
        })
    }
}

pub fn run(config: Config) -> Result<(), Box<dyn Error>> {
    let contents = fs::read_to_string(config.filename)?;
    let results = if config.case_sensitive {
        search(&config.query, &contents)
    } else {
        search_case_insensitive(&config.query, &contents)
    };
    for line in results {
        println!("{}", line);
    }
    Ok(())
}

pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {
    let mut results = Vec::new();
    for line in contents.lines() {
        if line.contains(query) {
            results.push(line);
        }
    }
    results
}

pub fn search_case_insensitive<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {
    let mut results = Vec::new();
    let query = query.to_lowercase();
    for line in contents.lines() {
        if line.to_lowercase().contains(&query) {
            results.push(line);
        }
    }
    results
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn case_sensitive() {
        let query = "duct";
        let contents = "\
Rust:
safe, fast, productive.
Pick three.
Duct tape.";

        assert_eq!(vec!["safe, fast, productive."], search(query, contents));
    }

    #[test]
    fn case_insensitive() {
        let query = "rUsT";
        let contents = "\
Rust:
safe, fast, productive.
Pick three.
Trust me.";

        assert_eq!(
            vec!["Rust:", "Trust me."],
            search_case_insensitive(query, contents)
        );
    }
}

main.rs:

use std::env;
use std::process;
use minigrep::Config;

fn main() {
    let args: Vec<String> = env::args().collect();
    let config = Config::new(&args).unwrap_or_else(|err| {
        println!("Problem parsing arguments: {}", err);
        process::exit(1);
    });
    if let Err(e) = minigrep::run(config) {
        println!("Application error: {}", e);
        process::exit(1);
    }
}

12.8.2 Standard Output vs. Standard Error

The current code prints all information, including error messages, to the terminal. Most terminals provide two output streams: standard output (stdout) and standard error (stderr).

General information should go to standard output, while error messages should go to standard error. The advantage of this separation is that normal output can be redirected into a file while error messages still appear on the screen.

The println! macro can only print to standard output. The eprintln! macro can print to standard error.

Using the current code, run this command in the terminal:

cargo run > output.txt

This redirects output to output.txt, but the command does not include any arguments, so the program should error. Because the error messages are also written to standard output, they end up in output.txt.

A better approach is to print error messages to standard error, which keeps standard output clean and separate from errors.

12.8.3 Modifying the Code

Changing the code so that error messages go to standard error is quite simple. We only need to change all error printing from println! to eprintln!. Because all error handling is in main.rs, we only need a small change there, and lib.rs does not need to be modified at all:

use std::env;
use std::process;
use minigrep::Config;

fn main() {
    let args: Vec<String> = env::args().collect();
    let config = Config::new(&args).unwrap_or_else(|err| {
        eprintln!("Problem parsing arguments: {}", err);
        process::exit(1);
    });
    if let Err(e) = minigrep::run(config) {
        eprintln!("Application error: {}", e);
        process::exit(1);
    }
}

Now run the previous command again. It still has no arguments, so the program errors, but this time it will not put the error message into output.txt; instead, it will print directly in the terminal:

$ cargo run > output.txt
Problem parsing arguments: not enough arguments

Then try a normal run with arguments:

$ cargo run -- to poem.txt > output.txt

The output is redirected to output.txt. Open it:

Are you nobody, too?
How dreary to be somebody!

That is the result we want: errors are printed directly in the terminal, while normal output is redirected into the file.

[Rust Guide] 12.7. Using Environment Variables

SomeB1oody — Sat, 23 May 2026 22:18:24 +0000

12.7.0 Before We Begin

This project is divided into these steps:

Receiving command-line arguments
Reading files
Refactoring: improving modules and error handling
Using TDD (test-driven development) to develop library functionality
Using environment variables (this article)
Writing error messages to standard error instead of standard output

If you find this helpful, please like, bookmark, and follow. To keep learning along, follow this series.

12.7.1 Review

Here is all the code written up to the previous article.

lib.rs:

use std::error::Error;
use std::fs;

pub struct Config {
    pub query: String,
    pub filename: String,
}

impl Config {
    pub fn new(args: &[String]) -> Result<Config, &'static str> {
        if args.len() < 3 {
            return Err("Not enough arguments");
        }
        let query = args[1].clone();
        let filename = args[2].clone();
        Ok(Config {
            query,
            filename,
        })
    }
}

pub fn run(config: Config) -> Result<(), Box<dyn Error>> {
    let contents = fs::read_to_string(config.filename)?;
    for line in search(&config.query, &contents) {
        println!("{}", line);
    }
    Ok(())
}

pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {
    let mut results = Vec::new();
    for line in contents.lines() {
        if line.contains(query) {
            results.push(line);
        }
    }
    results
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn one_result() {
        let query = "duct";
        let contents = "\
Rust:
safe, fast, productive.
Pick three.";
        assert_eq!(vec!["safe, fast, productive."], search(query, contents));
    }
}

main.rs:

use std::env;
use std::process;
use minigrep::Config;

fn main() {
    let args: Vec<String> = env::args().collect();
    let config = Config::new(&args).unwrap_or_else(|err| {
        println!("Problem parsing arguments: {}", err);
        process::exit(1);
    });
    if let Err(e) = minigrep::run(config) {
        println!("Application error: {}", e);
        process::exit(1);
    }
}

In these earlier sections, we completed the move of the business logic into lib.rs. That is very helpful for writing tests, because the logic in lib.rs can be called directly with different arguments without running the program from the command line, and its return values can be checked. In other words, we can test the business logic directly.

12.7.2 What Is TDD?

TDD is short for Test-Driven Development, and it usually follows these steps:

Write a failing test, run it, and make sure it fails for the expected reason
Write or modify just enough code to make the new test pass
Refactor the code you just added or changed, and make sure the tests still pass
Return to step 1 and continue

TDD is only one of many software development methods, but it can guide and support code design. Writing tests first and then writing code that passes them also helps maintain a high level of test coverage during development.

In this article, we will use TDD to implement the search logic for the program: search for a specified string in the file contents and put the matching lines into a list. This function will be called search_case_insensitive.

12.7.3 Write a Failing Test

Let’s start by naming the case-insensitive function search_case_insensitive.

First, modify the test module so that it contains a case-sensitive test and a case-insensitive test:

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn case_sensitive() {
        let query = "duct";
        let contents = "\
Rust:
safe, fast, productive.
Pick three.
Duct tape.";

        assert_eq!(vec!["safe, fast, productive."], search(query, contents));
    }

    #[test]
    fn case_insensitive() {
        let query = "rUsT";
        let contents = "\
Rust:
safe, fast, productive.
Pick three.
Trust me.";

        assert_eq!(
            vec!["Rust:", "Trust me."],
            search_case_insensitive(query, contents)
        );
    }
}

Then write the body of search_case_insensitive:

pub fn search_case_insensitive<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {
    vec![]
}

To make this function callable from outside, it must be declared public with pub
The function needs a lifetime annotation because it has multiple non-self parameters, and Rust cannot determine which parameter’s lifetime should match the lifetime of the return value
The elements in the returned Vector are string slices taken from contents, so the return value should have the same lifetime as contents; that is why both are annotated with the same lifetime 'a, while query does not need a lifetime annotation
The function body only needs to compile, because the first step of TDD is to write a test that fails, so failure is the desired outcome

At this point, running the tests will definitely fail, but that is fine. This is exactly what the first TDD step is supposed to produce.

12.7.4 Write or Modify Just Enough Code for the New Test to Pass

The code for search_case_insensitive is very similar to search, so only a few small changes are needed. The logic is simple: lowercase the query and compare it against lowercase versions of the text:

pub fn search_case_insensitive<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {
    let mut results = Vec::new();
    let query = query.to_lowercase();
    for line in contents.lines() {
        if line.to_lowercase().contains(&query) {
            results.push(line);
        }
    }
    results
}

The to_lowercase method converts a string to all lowercase
The result of to_lowercase is a String, so the new query is owned String rather than &str. Inside the loop, we use &query because contains does not accept String directly, so we pass a reference

Run the tests again:

$ cargo test
   Compiling minigrep v0.1.0 (file:///projects/minigrep)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 1.33s
     Running unittests src/lib.rs (target/debug/deps/minigrep-9cd200e5fac0fc94)

running 2 tests
test tests::case_insensitive ... ok
test tests::case_sensitive ... ok

test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

     Running unittests src/main.rs (target/debug/deps/minigrep-9cd200e5fac0fc94)

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

   Doc-tests minigrep

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

Both tests pass.

12.7.5 Use This Function in `run`

Now that the function works, we can call it in run.

First, add a field to the Config struct so it can decide whether to use the normal search or the case-insensitive search_case_insensitive:

pub struct Config {
    pub query: String,
    pub filename: String,
    pub case_sensitive: bool,
}

Modify run so it checks the configuration:

pub fn run(config: Config) -> Result<(), Box<dyn Error>> {
    let contents = fs::read_to_string(config.filename)?;
    let results = if config.case_sensitive {
        search(&config.query, &contents)
    } else {
        search_case_insensitive(&config.query, &contents)
    };
    for line in results {
        println!("{}", line);
    }
    Ok(())
}

The new constructor on Config also needs to change so it assigns case_sensitive based on the environment variable:

impl Config {
    pub fn new(args: &[String]) -> Result<Config, &'static str> {
        if args.len() < 3 {
            return Err("Not enough arguments");
        }
        let query = args[1].clone();
        let filename = args[2].clone();
        let case_sensitive = std::env::var("IGNORE_CASE").is_err();
        Ok(Config {
            query,
            filename,
            case_sensitive,
        })
    }
}

Here we use std::env::var (of course, you could also bring std::env into scope first and then use env::var). Its argument is the name of the environment variable, which conventionally is all uppercase. Here I use IGNORE_CASE, which means case-insensitive. If this environment variable is present, the search is treated as case-insensitive; if it is absent, the search is case-sensitive.

std::env::var returns a Result. If the IGNORE_CASE environment variable is set, it returns Ok(String) containing the variable’s value; otherwise it returns Err(std::env::VarError).

After std::env::var, we call is_err. If is_err sees the Err variant, it returns true, which is assigned to case_sensitive; otherwise it assigns false.

PS: honestly, writing this little program in such a rigid way is also a teaching necessity. Halfway through, I was already laughing at how much code there was. When you actually write it, there is no need to be this formal.

12.7.6 The Full Code and a Trial Run

After writing all that, here is the full code up to this point.

lib.rs:

use std::error::Error;
use std::fs;

pub struct Config {
    pub query: String,
    pub filename: String,
    pub case_sensitive: bool,
}

impl Config {
    pub fn new(args: &[String]) -> Result<Config, &'static str> {
        if args.len() < 3 {
            return Err("Not enough arguments");
        }
        let query = args[1].clone();
        let filename = args[2].clone();
        let case_sensitive = std::env::var("IGNORE_CASE").is_err();
        Ok(Config {
            query,
            filename,
            case_sensitive,
        })
    }
}

pub fn run(config: Config) -> Result<(), Box<dyn Error>> {
    let contents = fs::read_to_string(config.filename)?;
    let results = if config.case_sensitive {
        search(&config.query, &contents)
    } else {
        search_case_insensitive(&config.query, &contents)
    };
    for line in results {
        println!("{}", line);
    }
    Ok(())
}

pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {
    let mut results = Vec::new();
    for line in contents.lines() {
        if line.contains(query) {
            results.push(line);
        }
    }
    results
}

pub fn search_case_insensitive<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {
    let mut results = Vec::new();
    let query = query.to_lowercase();
    for line in contents.lines() {
        if line.to_lowercase().contains(&query) {
            results.push(line);
        }
    }
    results
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn case_sensitive() {
        let query = "duct";
        let contents = "\
Rust:
safe, fast, productive.
Pick three.
Duct tape.";

        assert_eq!(vec!["safe, fast, productive."], search(query, contents));
    }

    #[test]
    fn case_insensitive() {
        let query = "rUsT";
        let contents = "\
Rust:
safe, fast, productive.
Pick three.
Trust me.";

        assert_eq!(
            vec!["Rust:", "Trust me."],
            search_case_insensitive(query, contents)
        );
    }
}

main.rs:

use std::env;
use std::process;
use minigrep::Config;

fn main() {
    let args: Vec<String> = env::args().collect();
    let config = Config::new(&args).unwrap_or_else(|err| {
        println!("Problem parsing arguments: {}", err);
        process::exit(1);
    });
    if let Err(e) = minigrep::run(config) {
        println!("Application error: {}", e);
        process::exit(1);
    }
}

Let’s try running it:

First, run the program without setting the environment variable and use the query to, which should match any line containing the lowercase word to:

$ cargo run -- to poem.txt
   Compiling minigrep v0.1.0 (file:///projects/minigrep)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.0s
     Running `target/debug/minigrep to poem.txt`
Are you nobody, too?
How dreary to be somebody!

Now set IGNORE_CASE to 1 and keep everything else the same:

$ IGNORE_CASE=1 cargo run -- to poem.txt

You will get:

Are you nobody, too?
How dreary to be somebody!
To tell your name the livelong day
To an admiring bog!

There are no problems.

Note that if you are using powershell, you set an environment variable like this:

PS> $Env:IGNORE_CASE=1; cargo run -- to poem.txt

This keeps the environment variable available for the entire session. If you want to remove it, write:

PS> Remove-Item Env:IGNORE_CASE

[Rust Guide] 12.6. Developing Library Functionality with TDD

SomeB1oody — Sat, 23 May 2026 22:12:45 +0000

12.6.0 Before We Begin

In Chapter 12, we will build a real project: a command-line program. This program is a grep (Global Regular Expression Print), a tool for global regular-expression search and output. Its job is to search for the specified text in the specified file.

This project has several steps:

Receive command-line arguments
Read files
Refactor: improve modules and error handling
Use TDD (test-driven development) to develop library functionality (this article)
Use environment variables
Write error messages to standard error instead of standard output

If you find this helpful, please like, bookmark, and follow. To keep learning along, follow this series.

12.6.1 Review

Here is all the code written up to the previous article.

lib.rs:

use std::error::Error;  
use std::fs;  

pub struct Config {  
    pub query: String,  
    pub filename: String,  
}  

impl Config {  
    pub fn new(args: &[String]) -> Result<Config, &'static str> {  
        if args.len() < 3 {  
            return Err("Not enough arguments");  
        }  
        let query = args[1].clone();  
        let filename = args[2].clone();  
        Ok(Config { query, filename})  
    }  
}  

pub fn run(config: Config) -> Result<(), Box<dyn Error>> {  
    let contents = fs::read_to_string(config.filename)?;  
    println!("With text:\n{}", contents);  
    Ok(())  
}

main.rs:

use std::env;  
use std::process;  
use minigrep::Config;  

fn main() {  
    let args:Vec<String> = env::args().collect();  
    let config = Config::new(&args).unwrap_or_else(|err| {  
        println!("Problem parsing arguments: {}", err);  
        process::exit(1);  
    });  
    if let Err(e) = minigrep::run(config) {  
        println!("Application error: {}", e);  
        process::exit(1);  
    }  
}

In the previous sections, we moved the business logic into lib.rs. That helps a lot with writing tests, because the logic in lib.rs can be called directly with different parameters without running the program from the command line, and we can verify its return values. In other words, we can test the business logic directly.

12.6.2 What Is Test-Driven Development?

TDD stands for Test-Driven Development. It usually follows these steps:

Write a failing test, run it, and make sure it fails for the expected reason
Write or modify just enough code to make the new test pass
Refactor the code you just added or changed to make sure the tests still pass
Return to step 1 and continue

TDD is just one of many software development methods, but it can guide and help code design. Writing tests first and then writing code to pass those tests also helps maintain a high level of test coverage during development.

In this article, we will use TDD to implement the search logic: search for the specified string in the file contents and put the matching lines into a list. This function will be named search.

12.6.3 Modifying the Code

Follow the TDD steps:

1. Write a Failing Test

First, write a test module in lib.rs:

#[cfg(test)]  
mod tests {  
    use super::*;  

    #[test]  
    fn one_result() {  
        let query = "duct";  
        let contents = "\  
Rust: 
safe, fast, productive.  
Pick three.";  
        assert_eq!(vec!["safe, fast, productive."],search(query, contents));  
    }  
}

That is, because "duct" stored in query appears in the line "safe, fast, productive.", the return value should be a Vector whose element type is String, and it should contain only one element: "safe, fast, productive.".

The return value is a Vector because search is expected to handle multiple matching results. Of course, this particular test can only have one result, which is why the test is named one_result.

After writing the test module, write the search function:

pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {  
    vec![]  
}

To make the function callable from outside, it must be declared pub.
The function needs lifetime annotations because it has more than one non-self parameter, so Rust cannot tell which parameter’s lifetime matches the return value.
The elements in the returned Vector are string slices taken from contents, so the return value should have the same lifetime as contents. That is why both are annotated with the same lifetime 'a, while query does not need a lifetime annotation.
The function body only needs to compile, because the first step of TDD is to write a failing test. Failure is the desired outcome right now.

The test will fail, and that is exactly what we want in the first step of TDD.

2. Write Just Enough Code for the New Test to Pass

The code for search_case_insensitive is very similar to search; we only need a few changes. The logic is simple: convert both the query and the text to lowercase.

pub fn search_case_insensitive<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {  
    let mut results = Vec::new();  
    let query = query.to_lowercase();  
    for line in contents.to_lowercase().lines() {  
        if line.contains(&query) {  
            results.push(line);  
        }  
    }  
    results  
}

The to_lowercase method converts a string to lowercase.
The result of to_lowercase is a String, which owns its data. That means the new query is a String, not a &str. In the if inside the loop, we use &query because contains does not accept String, so we must pass a reference.

Run the tests again:

$ cargo test
   Compiling minigrep v0.1.0 (file:///projects/minigrep)
    Finished `test` profile [unoptimized +debuginfo] target(s) in 1.33s
     Running unittests src/lib.rs (target/debug/deps/minigrep-9cd200e5fac0fc94)

running 2 tests
test tests::case_insensitive ... ok
test tests::case_sensitive ... ok

test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

     Running unittests src/main.rs (target/debug/deps/minigrep-9cd200e5fac0fc94)

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

   Doc-tests minigrep

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

Both tests pass.

3. Use This Function in `run`

Now that the function works, we can call it from run.

But first, we need to add a field to the Config struct to decide whether to use the normal search or the case-insensitive search_case_insensitive:

pub struct Config {  
    pub query: String,  
    pub filename: String,  
    pub case_sensitive: bool,  
}

Update run so it checks the configuration:

pub fn run(config: Config) -> Result<(), Box<dyn Error>> {  
    let contents = fs::read_to_string(config.filename)?;  
    let results = if config.case_sensitive {  
        search(&config.query, &contents)  
    } else {  
        search_case_insensitive(&config.query, &contents)  
    };  
    for line in results {  
        println!("{}", line);  
    }  
    Ok(())  
}

The new constructor on Config also needs to change, and it should set case_sensitive based on an environment variable:

impl Config {  
    pub fn new(args: &[String]) -> Result<Config, &'static str> {  
        if args.len() < 3 {  
            return Err("Not enough arguments");  
        }  
        let query = args[1].clone();  
        let filename = args[2].clone();  
        let case_sensitive = std::env::var("CASE_INSENSITIVE").is_err();  
        Ok(Config { query, filename, case_sensitive})  
    }  
}

This uses std::env::var (you can also import std::env first and then use env::var). Its argument is the name of the environment variable, usually written in all caps. Here I use CASE_INSENSITIVE, which means “case-insensitive.” If this environment variable exists, we treat the search as case-insensitive; if it does not exist, we treat it as case-sensitive.

std::env::var returns a Result. If CASE_INSENSITIVE is set, it returns Ok(String) containing the variable’s value; otherwise it returns Err(std::env::VarError).

The is_err method is chained after std::env::var. If the result is Err, it returns true and assigns true to case_sensitive; otherwise it assigns false.

PS: honestly, writing this little program in such a rigid way is a teaching compromise. When I was halfway through, even I was amused by how much code there was. In real work, you do not need to make it this rigid.

12.6.3 The Full Code and a Trial Run

Here is all the code written so far.

lib.rs:

use std::error::Error;  
use std::fs;  

pub struct Config {  
    pub query: String,  
    pub filename: String,  
    pub case_sensitive: bool,  
}  

impl Config {

[Rust Guide] 12.5. Refactoring Pt.3 - Moving Business Logic

SomeB1oody — Sat, 23 May 2026 22:11:53 +0000

12.5.0 Before We Begin

This project has several steps:

Receive command-line arguments
Read files
Refactor: improve modules and error handling (this article)
Use TDD (test-driven development) to develop library functionality
Use environment variables
Write error messages to standard error instead of standard output

If you find this helpful, please like, bookmark, and follow. To keep learning along, follow this series.

12.5.1 Review

The previous two articles completed modularization optimization and error handling. In this article, we will do further optimization on that basis.

Here is all the code written up to the previous article:

use std::env;  
use std::fs;  
use std::process;  

struct Config {  
    query: String,  
    filename: String,  
}  

fn main() {  
    let args:Vec<String> = env::args().collect();  
    let config = Config::new(&args).unwrap_or_else(|err| {  
        println!("Problem parsing arguments: {}", err);  
        process::exit(1);  
    });  

    let contents = fs::read_to_string(config.filename)  
        .expect("Something went wrong while reading the file");  
    println!("With text:\n{}", contents);  
}  

impl Config {  
    fn new(args: &[String]) -> Result<Config, &'static str> {  
        if args.len() < 3 {  
            return Err("Not enough arguments");  
        }  
        let query = args[1].clone();  
        let filename = args[2].clone();  
        Ok(Config { query, filename})  
    }  
}

12.5.2 Extracting Logic from `main`

As discussed in 12.3. Refactoring Pt. 1, we follow the guiding principle for separating concerns in binary programs:

Split the program into main.rs and lib.rs, and put business logic in lib.rs
If the logic is small, keeping it in main.rs is fine
As the logic becomes more complex, extract it from main.rs into lib.rs

According to that principle, everything in main except configuration parsing and error handling should be extracted into a run function. That keeps main small enough that we can verify correctness just by reading it, while the rest of the logic can be verified through tests (see Chapter 11 for tests).

For the code we have so far, the run function should be:

fn run(config: Config) {  
    let contents = fs::read_to_string(config.filename)  
        .expect("Something went wrong while reading the file");  
    println!("With text:\n{}", contents);  
}

main should also call run:

fn main() {  
    let args:Vec<String> = env::args().collect();  
    let config = Config::new(&args).unwrap_or_else(|err| {  
        println!("Problem parsing arguments: {}", err);  
        process::exit(1);  
    });  
    run(config);  
}

12.5.3 Improving Error Handling in `run`

Right now, run uses expect for file-reading errors. That kind of error handling calls panic!. What we want instead is to propagate errors with Result, just like Config::new:

fn run(config: Config) -> Result<(), Box<dyn Error>> {  
    let contents = fs::read_to_string(config.filename)?;  
    println!("With text:\n{}", contents);  
    Ok(())  
}

The Ok variant of Result corresponds to (), the unit type. This type means “nothing is returned” or “there is nothing here,” which is fine because run does not need to return anything on success. The final line Ok(()) returns Ok with a unit value.
The Err variant of Result is Box<dyn Error>. You do not need to understand it in depth yet; just know that it represents any type that implements the std::error::Error trait (here I wrote just Error because I imported it with use std::error::Error;). This means different error types can be returned in different situations. dyn is short for dynamic.
The ? symbol was explained in detail in 9.3. Result Enum and Recoverable Errors Pt. 2. Briefly, read_to_string returns a Result. Adding ? means that if read_to_string returns Ok, the value inside Ok is returned and assigned to the variable; if it returns Err, the function terminates immediately and returns the Err and its attached error information. In other words, ? is equivalent to:

let contents = match fs::read_to_string(config.filename){
    Ok(contents) => contents,
    Err(e) => return Err(e),
};

With this change, the error is propagated to the caller, which is main, so main must handle the error:

fn main() {  
    let args:Vec<String> = env::args().collect();  
    let config = Config::new(&args).unwrap_or_else(|err| {  
        println!("Problem parsing arguments: {}", err);  
        process::exit(1);  
    });  
    if let Err(e) = run(config) {  
        println!("Application error: {}", e);  
        process::exit(1);  
    }  
}

The if let used here is syntactic sugar for match; think of it as a match that handles only one branch. See 6.4. Simple Control Flow - If Let for details. Note that if let and if are not the same thing, so do not confuse them.

12.5.4 Moving the Business Logic

Now that all the functions and error handling are separated, the next step is to move them into lib.rs.

The things to move are these functions, structs, and related imports.

The result after moving them (lib.rs) is:

use std::error::Error;  
use std::fs;  

pub struct Config {  
    pub query: String,  
    pub filename: String,  
}  

impl Config {  
    pub fn new(args: &[String]) -> Result<Config, &'static str> {  
        if args.len() < 3 {  
            return Err("Not enough arguments");  
        }  
        let query = args[1].clone();  
        let filename = args[2].clone();  
        Ok(Config { query, filename})  
    }  
}  

pub fn run(config: Config) -> Result<(), Box<dyn Error>> {  
    let contents = fs::read_to_string(config.filename)?;  
    println!("With text:\n{}", contents);  
    Ok(())  
}

Note: all structs, methods on structs, and functions used by main.rs must be marked pub so they can be called.

Now look at main.rs:

use std::env;  
use std::process;  
use minigrep::Config;  

fn main() {  
    let args:Vec<String> = env::args().collect();  
    let config = Config::new(&args).unwrap_or_else(|err| {  
        println!("Problem parsing arguments: {}", err);  
        process::exit(1);  
    });  
    if let Err(e) = minigrep::run(config) {  
        println!("Application error: {}", e);  
        process::exit(1);  
    }  
}

All refactoring tasks are complete. The next step is to write tests (the next article).

[Rust Guide] 12.4. Refactoring Pt.2 - Error Handling

SomeB1oody — Sat, 23 May 2026 22:10:03 +0000

12.4.0 Before We Begin

This project has several steps:

Receive command-line arguments
Read files
Refactor: improve modules and error handling (this article)
Use TDD (test-driven development) to develop library functionality
Use environment variables
Write error messages to standard error instead of standard output

If you find this helpful, please like, bookmark, and follow. To keep learning along, follow this series.

12.4.1 Review

In the previous section, to improve modularity, we created a struct for the variables and moved the argument-parsing function into a method on that struct. Here is all the code written up to the previous article:

use std::env;  
use std::fs;  

struct Config {  
    query: String,  
    filename: String,  
}  

fn main() {  
    let args:Vec<String> = env::args().collect();  
    let config = Config::new(&args);  

    let contents = fs::read_to_string(config.filename)  
        .expect("Something went wrong while reading the file");  
    println!("With text:\n{}", contents);  
}  

impl Config {  
    fn new(args: &[String]) -> Config {  
        let query = args[1].clone();  
        let filename = args[2].clone();  
        Config {  
            query,  
            filename,  
        }  
    }  
}

12.4.2 Unexpected Input

The program works correctly only when the user provides valid input. Let’s try running it without arguments:

$ cargo run
   Compiling minigrep v0.1.0 (file:///projects/minigrep)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.0s
     Running `target/debug/minigrep`
thread 'main' panicked at src/main.rs:27:21:
index out of bounds: the len is 1 but the index is 1
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

It reports Index out of bounds. As the programmer, we know this is because there were not enough arguments, so the program went out of bounds when using an index to fetch them. But a user cannot understand this error message, so they cannot correct the mistake.

What this article will do is make the program’s error messages easier to understand.

12.4.3 Specifying Error Messages

The way to help users understand the error is to provide our own error message. In the previous example, the panic happened when Config::new tried to access an out-of-bounds index, so let’s modify that part:

impl Config {  
    fn new(args: &[String]) -> Config {  
        if args.len() < 3 {  
            panic!("Not enough arguments");  
        }  
        let query = args[1].clone();  
        let filename = args[2].clone();  
        Config {  
            query,  
            filename,  
        }  
    }  
}

If args contains fewer than three elements, panic and print "Not enough arguments" to tell the user that too few arguments were provided.

Try running it without arguments again:

$ cargo run
   Compiling minigrep v0.1.0 (file:///projects/minigrep)
    Finished `dev` profile [unoptimized +debuginfo] target(s) in 0.0s
     Running `target/debug/minigrep`
thread 'main' panicked at src/main.rs:26:13:
not enough arguments
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

This error message is much better than the previous one.

However, some extra information is still shown, such as thread 'main' panicked at src/main.rs:26:13: and note: run with RUST_BACKTRACE=1 environment variable to display a backtrace. Those are for programmers, not for users, so they should be removed too.

12.4.4 Using the `Result` Type

panic! is appropriate when the program itself has a bug. But here, the problem is that the program was used incorrectly because there were too few arguments. For this kind of problem, using Result to propagate the error is the best choice (see 9.2. Result Enum and Recoverable Errors Pt. 1 and Pt. 2 for details):

impl Config {  
    fn new(args: &[String]) -> Result<Config, &'static str> {  
        if args.len() < 3 {  
            return Err("Not enough arguments");  
        }  
        let query = args[1].clone();  
        let filename = args[2].clone();  
        Ok(Config { query, filename})  
    }  
}

Error information must be wrapped in Err, and successful return values must be wrapped in Ok.
The Ok variant of Result returns a Config instance, while Err returns an &str string literal. However, the compiler does not know where that &str comes from or how long its lifetime is, so we need a lifetime annotation. We want it to remain valid for the entire program run, so we write it as &'static str, the static lifetime.

Since the return type of new has changed, the code in main that receives its value must also change:

let config = Config::new(&args).unwrap_or_else(|err| {  
    println!("Problem parsing arguments: {}", err);  
    process::exit(1);  
});

The unwrap_or_else method accepts a Result. If it is Ok, it returns the value inside Ok, similar to unwrap. If it is Err, the method calls a closure.

A closure is an anonymous function that we define and pass as an argument to unwrap_or_else. Its syntax uses two pipes ||, with a variable name in the middle as the parameter. Here it is err, which can be used inside the closure body, such as when printing the error.

Then we use process::exit from the standard library. Remember to import it first with use std::process;. Calling exit terminates the program immediately, and its argument, 1 in the example, becomes the program’s exit status code. This means that after println!("Problem parsing arguments: {}", err);, the program stops, so there is no thread 'main' panicked at src/main.rs:26:13: or backtrace note.

Try it:

$ cargo run
   Compiling minigrep v0.1.0 (file:///projects/minigrep)
    Finished `dev` profile [unoptimized +debuginfo] target(s) in 0.48s
     Running `target/debug/minigrep`
Problem parsing arguments: not enough arguments

The concept of closures will be covered in the next chapter, so it is fine if this does not make complete sense yet; a rough understanding is enough here.

12.4.5 The Full Code

Here is all the code written up to this article:

use std::env;  
use std::fs;  
use std::process;  

struct Config {  
    query: String,  
    filename: String,  
}  

fn main() {  
    let args:Vec<String> = env::args().collect();  
    let config = Config::new(&args).unwrap_or_else(|err| {  
        println!("Problem parsing arguments: {}", err);  
        process::exit(1);  
    });  

    let contents = fs::read_to_string(config.filename)  
        .expect("Something went wrong while reading the file");  
    println!("With text:\n{}", contents);  
}  

impl Config {  
    fn new(args: &[String]) -> Result<Config, &'static str> {  
        if args.len() < 3 {  
            return Err("Not enough arguments");  
        }  
        let query = args[1].clone();  
        let filename = args[2].clone();  
        Ok(Config { query, filename})  
    }  
}

[Rust Guide] 12.3. Refactoring Pt.1 - Improving Modularity

SomeB1oody — Sat, 23 May 2026 22:09:07 +0000

12.3.0 Before We Begin

This project has several steps:

Receive command-line arguments
Read files
Refactor: improve modules and error handling (this article)
Use TDD (test-driven development) to develop library functionality
Use environment variables
Write error messages to standard error instead of standard output

If you find this helpful, please like, bookmark, and follow. To keep learning along, follow this series.

12.3.1 Why Refactor

The purpose of refactoring is to improve modularity and error handling.

Here is all the code written up to the previous article:

use std::env;  
use std::fs;  

fn main() {  
    let args:Vec<String> = env::args().collect();  
    let query = &args[1];  
    let filename = &args[2];  

    println!("search for {}", query);  
    println!("In file {}", filename);  

    let contents = fs::read_to_string(filename)  
        .expect("Something went wrong while reading the file");
    println!("With text:\n{}", contents);  
}

This code has four problems:

The main function is doing too much. It handles command-line parsing and file reading. The guiding principle of program design is that each function should handle only one responsibility, so the function should be split up.
The variables query and filename store program configuration, while contents stores file contents. As code and variables accumulate, it becomes harder to track what each variable actually means. These values should be stored in a struct.
File-reading errors are handled with expect, which always prints an error message and panics no matter what went wrong. That is not ideal, because a file read failure might mean the file does not exist, or it might be a permissions problem. The panic message "Something went wrong while reading the file" does not help the user diagnose the issue.
If expect is used throughout the program, users will see error messages coming from Rust internals, such as "Index out of bounds", which makes it hard to understand what actually caused the problem. It is better to centralize error handling so future maintainers only need to consider one place when changing the logic, and so the error messages shown to users are understandable.

12.3.2 A Guiding Principle for Separating Concerns in Binary Programs

Many Rust binary projects run into the same organizational problem: they put too much functionality and too many responsibilities into main. The Rust community has a guiding principle for separating concerns in binary programs:

Split the program into main.rs and lib.rs, and put business logic in lib.rs
If the logic is small, keeping it in main.rs is fine
As the logic becomes more complex, extract it from main.rs into lib.rs

After this split, the responsibilities that should remain in main in this example are:

Call the command-line parsing logic using the argument values
Perform other configuration
Call the run function in lib.rs
Handle any problems that run may return

12.3.3 Separating Logic

Take another look at the code:

use std::env;  
use std::fs;  

fn main() {  
    let args:Vec<String> = env::args().collect();  
    let query = &args[1];  
    let filename = &args[2];  

    println!("search for {}", query);  
    println!("In file {}", filename);  

    let contents = fs::read_to_string(filename)  
        .expect("Something went wrong while reading the file");
    println!("With text:\n{}", contents);  
}

First, extract the command-line argument handling:

fn parse_config(args: &[String]) -> (&str, &str) {  
    let query = &args[1];  
    let filename = &args[2];  
    (query, filename)  
}

&[String] means a slice of a Vector whose elements are String
There is no need to print query and filename here, so that part is removed

Then change main to call parse_config:

fn main() {  
    let args:Vec<String> = env::args().collect();  
    let (query, filename) = parse_config(&args);  

    let contents = fs::read_to_string(filename)  
        .expect("Something went wrong while reading the file");  
    println!("With text:\n{}", contents);  
}

12.3.4 Using a Struct

parse_config returns query and filename together as a tuple, and then main splits those two tuple values back into two variables. This back-and-forth splitting and combining shows that the abstraction in the program is not ideal.

query and filename are both part of the configuration and are related to each other, so putting them in a tuple does not express that relationship well enough. A struct is a better fit:

struct Config {  
    query: String,  
    filename: String,  
}  

fn main() {  
    let args:Vec<String> = env::args().collect();  
    let config = parse_config(&args);  

    let contents = fs::read_to_string(config.filename)  
        .expect("Something went wrong while reading the file");  
    println!("With text:\n{}", contents);  
}  

fn parse_config(args: &[String]) -> Config {  
    let query = args[1].clone();  
    let filename = args[2].clone();  
    Config {  
        query,  
        filename,  
    }  
}

In parse_config, pay attention to the types of query and filename: the parameter args has type &[String], which is a reference and therefore does not own the data, so query and filename are also references. But Config expects String, not &String, so we need to clone to gain ownership and convert &String into String.

Cloning uses more time and memory than storing references directly, but it saves us from dealing with lifetimes and makes the code more direct and simpler. In some scenarios, giving up a bit of performance in exchange for simplicity is well worth considering.

Of course, using String::from to wrap the values also works:

fn parse_config(args: &[String]) -> Config {  
    let query = &args[1];  
    let filename = &args[2];  
    Config {  
        query: String::from(query),  
        filename: String::from(filename),  
    }  
}

There are other valid ways to write this code too, but here I will use the cloning approach.

12.3.5 Turning a Function Into a Struct Method

Since parse_config creates a Config instance, it is effectively a constructor. A constructor can be written like this:

impl Config {  
    fn new(args: &[String]) -> Config {  
        let query = args[1].clone();  
        let filename = args[2].clone();  
        Config {  
            query,  
            filename,  
        }  
    }  
}

Just place this function on the Config implementation block (for details on methods, see 5.3. Methods on Structs). I also renamed parse_config to new, because I am treating it as a constructor (constructors are usually named new).

After this change, main also needs to be updated:

let config = Config::new(&args);

12.3.5 The Full Code

Here is all the code written up to this article:

use std::env;  
use std::fs;  

struct Config {  
    query: String,  
    filename: String,  
}  

fn main() {  
    let args:Vec<String> = env::args().collect();  
    let config = Config::new(&args);  

    let contents = fs::read_to_string(config.filename)  
        .expect("Something went wrong while reading the file");  
    println!("With text:\n{}", contents);  
}  

impl Config {  
    fn new(args: &[String]) -> Config {  
        let query = args[1].clone();  
        let filename = args[2].clone();  
        Config {  
            query,  
            filename,  
        }  
    }  
}

[Rust Guide] 12.2. Reading Files

SomeB1oody — Sat, 23 May 2026 22:08:22 +0000

12.2.0 Before We Begin

This project has several steps:

Receive command-line arguments
Read files (this article)
Refactor: improve modules and error handling
Use TDD (test-driven development) to develop library functionality
Use environment variables
Write error messages to standard error instead of standard output

If you find this helpful, please like, bookmark, and follow. To keep learning along, follow this series.

12.2.2 Review

Here is all the code written up to the previous article:

use std::env;  

fn main() {  
    let args:Vec<String> = env::args().collect();  
    let query = &args[1];  
    let filename = &args[2];

    println!("search for {}", query);  
    println!("In file {}", filename);  
}

At this point, the code handles reading the user’s command-line input. Next we need to read the file based on that input.

12.2.3 Reading a File

To read a file, we need to import std::fs, which handles file-related operations:

use std::fs;

Next, read the file using filename:

let contents = fs::read_to_string(filename);

Reading can fail, so the return value is not the contents directly but a Result enum. For that enum, you can use expect to unwrap it. The argument to expect is the error message to print if something goes wrong (expect is covered in detail in 9.2. Result Enum and Recoverable Errors Pt. 1).

let contents = fs::read_to_string(filename)
.expect("Something went wrong while reading the file");// line break here is only to keep the line short

If the file is read successfully, print the contents:

println!("With text:\n{}", contents);

12.2.4 Testing the Code

At this point, we can test the code.

Here is all the code written so far:

use std::env;  
use std::fs;  

fn main() {  
    let args:Vec<String> = env::args().collect();  
    let query = &args[1];  
    let filename = &args[2];  

    println!("search for {}", query);  
    println!("In file {}", filename);  

    let contents = fs::read_to_string(filename)  
        .expect("Something went wrong while reading the file");// line break here is only to keep the line short  
    println!("With text:\n{}", contents);  
}

First, create a .txt file in the project directory. You can name it whatever you like; I used poem.txt. Put some text in it, for example:

I'm nobody! Who are you?
Are you nobody, too?
Then there's a pair of us - don't tell!
They'd banish us, you know.

How dreary to be somebody!
How public, like a frog
To tell your name the livelong day
To an admiring bog!

Then run the command:

cargo run -- the poem.txt

The -- separates Cargo command arguments from program arguments. It tells Cargo that what follows is not a Cargo option or argument, but an argument passed to the program. It is not read or stored.
the is the text to search for and is stored in query
poem.txt is the file name and is stored in filename

Output:

$ cargo run -- the poem.txt
   Compiling minigrep v0.1.0 (file:///projects/minigrep)
    Finished `dev` profile [unoptimized +debuginfo] target(s) in 0.0s
     Running `target/debug/minigrep the poem.txt`
Searching for the
In file poem.txt
With text:
I'm nobody! Who are you?
Are you nobody, too?
Then there's a pair of us - don't tell!
They'd banish us, you know.

How dreary to be somebody!
How public, like a frog
To tell your name the livelong day
To an admiring bog!

No problems.

DEV Community: SomeB1oody

[Rust Guide] 13.5. Iterators - Definitions, the Iterator Trait, and the Next Method

13.5.0 Before We Begin

13.5.1 What Is an Iterator

13.5.2 The Iterator Trait

13.5.3 Several Iteration Methods

[Rust Guide] 13.4. Capturing the Environment With Closures

13.4.0 Before We Begin

13.4.1 Closures Can Capture Their Environment

13.4.2 How Closures Capture Values From Their Environment

13.4.3 The move Keyword

13.4.4 Best Practice

[Rust Guide] 13.3. Storing Closures With Generic Parameters and Fn Traits

13.3.0 Before We Begin

13.3.1 Review

13.3.2 Having a Struct Hold a Closure

13.3.3 Fn Trait

13.3.4 Limitations of the Cache Implementation

[Rust Guide] 13.2. Closure Type Inference and Annotations

13.2.0 Before We Begin

13.2.1 Type Inference for Closures

13.2.2 Syntax for Function and Closure Definitions

13.2.3 Type Inference for Closures

[Rust Guide] 13.1. What Is a Closure and How to Use Closures

13.1.0 Before We Begin

13.1.1 What Is a Closure

13.1.2 An Example of a Closure

[Rust Guide]12.8. Writing Error Messages to Standard Error

12.8.0 Before We Begin

12.8.1 Review

12.8.2 Standard Output vs. Standard Error

12.8.3 Modifying the Code

[Rust Guide] 12.7. Using Environment Variables

12.7.0 Before We Begin

12.7.1 Review

12.7.2 What Is TDD?

12.7.3 Write a Failing Test

12.7.4 Write or Modify Just Enough Code for the New Test to Pass

12.7.5 Use This Function in run

12.7.6 The Full Code and a Trial Run

[Rust Guide] 12.6. Developing Library Functionality with TDD

12.6.0 Before We Begin

12.6.1 Review

12.6.2 What Is Test-Driven Development?

12.6.3 Modifying the Code

1. Write a Failing Test

2. Write Just Enough Code for the New Test to Pass

3. Use This Function in run

12.6.3 The Full Code and a Trial Run

[Rust Guide] 12.5. Refactoring Pt.3 - Moving Business Logic

12.5.0 Before We Begin

12.5.1 Review

12.5.2 Extracting Logic from main

12.5.3 Improving Error Handling in run

12.5.4 Moving the Business Logic

[Rust Guide] 12.4. Refactoring Pt.2 - Error Handling

12.4.0 Before We Begin

12.4.1 Review

12.4.2 Unexpected Input

12.4.3 Specifying Error Messages

12.4.4 Using the Result Type

12.4.5 The Full Code

[Rust Guide] 12.3. Refactoring Pt.1 - Improving Modularity

12.3.0 Before We Begin

12.3.1 Why Refactor

12.3.2 A Guiding Principle for Separating Concerns in Binary Programs

12.3.3 Separating Logic

12.3.4 Using a Struct

12.3.5 Turning a Function Into a Struct Method

12.3.5 The Full Code

[Rust Guide] 12.2. Reading Files

12.2.0 Before We Begin

12.2.2 Review

12.2.3 Reading a File

12.2.4 Testing the Code

13.5.2 The `Iterator` Trait

13.4.3 The `move` Keyword

13.3.3 `Fn` Trait

12.7.5 Use This Function in `run`

3. Use This Function in `run`

12.5.2 Extracting Logic from `main`

12.5.3 Improving Error Handling in `run`

12.4.4 Using the `Result` Type