DEV Community: SomeB1oody

[Rust Guide] 14.6. Installing Binary Crates

SomeB1oody — Wed, 08 Jul 2026 03:35:42 +0000

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

14.6.1 Install a Binary Crate from crates.io

You can use the cargo install command to install a binary crate from crates.io. This is not meant to replace system packages; it is intended as a convenient way for Rust developers to install tools shared by others.

Its limitation is that it can only install crates that have a binary target. A binary target is an executable program, produced by a crate that has src/main.rs or is otherwise configured as a binary crate.

Since there is the concept of a binary target, there is also the concept of a library target. A library target cannot be run by itself.

Usually, the README.md file contains a description of the crate and tells you whether the crate has a library target, a binary target, or both.

14.6.2 `cargo install`

Binary files installed by cargo install are placed in the bin folder under the home directory.

If you installed Rust with the default rustup configuration, the binary directory is $HOME/.cargo/bin.

To make programs installed by cargo install directly executable, you need to make sure that directory is in the $PATH environment variable.

For example, in Chapter 12 we mentioned the Rust implementation of the grep tool, called ripgrep, which is used to search files. To install ripgrep, we can run:

$ cargo install ripgrep
    Updating crates.io index
  Downloaded ripgrep v13.0.0
  Downloaded 1 crate (243.3 KB) in 0.88s
  Installing ripgrep v13.0.0
......
   Compiling ripgrep v13.0.0
    Finished release [optimized + debuginfo] target(s) in 3m 10s
  Installing ~/.cargo/bin/rg
   Installed package `ripgrep v13.0.0` (executable `rg`)

Some output has been omitted, but this is roughly what it looks like. The penultimate line shows that the program was installed at ~/.cargo/bin/rg.

In the terminal, use echo $PATH to check whether this directory is in the environment variable.

14.6.3 Extending Cargo with Custom Commands

Cargo is designed so that it can be extended with subcommands.

For example, if a binary in $PATH is named cargo-something, you can run it with cargo something, treating it as if it were a Cargo subcommand.

When you run cargo --list, custom commands like this are also listed. Being able to install extensions with cargo install and then run them like built-in Cargo tools is a very convenient benefit of Cargo’s design.

[Rsut Guide] 14.5. Cargo Workspace

SomeB1oody — Wed, 08 Jul 2026 03:34:01 +0000

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

14.5.1 Why Cargo Workspaces Are Needed

Suppose we build a binary crate that contains both a library and an application. As the project grows, the library crate may become larger and larger. In that case, it is usually split into multiple packages. For this need, Rust provides Cargo workspaces, also called cargo workspaces.

Cargo workspaces help manage multiple related crates that need to be developed together. In essence, they are a set of packages that share the same Cargo.lock and output files.

14.5.2 Using a Workspace

There are multiple ways to create a workspace.

Here is an example: this workspace contains one binary crate and one library crate:

The binary crate has a main function and depends on the library crate.
One library crate provides a function called add_one.

1. Create the Workspace Directory

First, create a directory for the workspace. I will name it add. Enter the following commands in the terminal:

$ mkdir add
$ cd add

2. Use the Workspace in the Main Project

Next, inside the add directory, create a Cargo.toml file that configures the entire workspace. This file will not have a [package] section. Instead, it starts with a [workspace] section:

[workspace]

members = [
    "adder",
]

adder is the name I gave the binary crate, and this list can be extended with more members.

3. Add the Library

$ cargo new adder
     Created binary (application) `adder` package

This command creates the adder crate under add/adder.

At this point, the project structure looks like this:

├── Cargo.lock
├── Cargo.toml
├── adder
│   ├── Cargo.toml
│   └── src
│       └── main.rs
└── target

Note that at this point, we can run cargo build for the add project, and we can also run cargo build for the adder crate under add. However, there will only be one target directory and one Cargo.lock file, both under add, and the build output of the adder crate will also be stored there. Because crates in a workspace are often interdependent, having a separate target directory for each folder would force developers to repeatedly rebuild the other crates in the workspace.

Next, add another crate:

The other crate is called add_one, so update the workspace information:

[workspace]

members = [
    "adder",
    "add_one",
]

Use cargo new to add the library. Remember to use the --lib flag to declare it as a library crate:

$ cargo new add_one --lib
     Created library `add_one` package

Now the project structure looks like this:

├── Cargo.lock
├── Cargo.toml
├── add_one
│   ├── Cargo.toml
│   └── src
│       └── lib.rs
├── adder
│   ├── Cargo.toml
│   └── src
│       └── main.rs
└── target

4. Write the Code

In add_one/src/lib.rs, add an add_one function:

pub fn add_one(x: i32) -> i32 {
    x + 1
}

Now we can make the adder package and our binary depend on add_one. First, add the path dependency add_one to adder/Cargo.toml, because Cargo does not assume that crates in a workspace depend on each other, so we need to make the dependency explicit. Write this in adder/Cargo.toml:

[dependencies]
add_one = { path = "../add_one" }

Next, let’s use the add_one function from the add_one crate. Open adder/src/main.rs, add use at the top to bring add_one into scope, and then modify main to call the add_one function.

use add_one;

fn main() {
    let num = 10;
    println!("Hello, world! {num} plus one is {}!", add_one::add_one(num));
}

5. Build

Run cargo build for the add project:

$ cargo build
   Compiling add_one v0.1.0 (file:///projects/add/add_one)
   Compiling adder v0.1.0 (file:///projects/add/adder)
    Finished dev [unoptimized + debuginfo] target(s) in 0.68s

No errors occurred; it runs normally.

6. Testing

We can also run tests for a specific package in the workspace from the top-level directory by using the -p flag and specifying the package name. For example, to test only the add_one function:

$ cargo test -p add_one
    Finished test [unoptimized + debuginfo] target(s) in 0.00s
     Running unittests src/lib.rs (target/debug/deps/add_one-b3235fea9a156f74)

running 1 test
test tests::it_works ... ok

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

   Doc-tests add_one

running 0 tests

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

If you publish the crates in a workspace to crates.io, each crate in the workspace must be published separately. As with cargo test, we can use -p to target a specific package in the workspace and specify the package name we want to publish.

[Rust Guide] 14.4. Publishing Crates Part 2

SomeB1oody — Wed, 08 Jul 2026 03:32:51 +0000

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

14.4.1 Create and Set Up a crates.io Account

Before publishing any crate, you need to have a crates.io account and obtain an API token. To do this, visit the crates.io homepage and sign in with a GitHub account. Currently, only GitHub login is supported. If you are already signed in, open your account settings at https://crates.io/me/ and find the API key. Then use the cargo login command locally and paste your API key when prompted:

$ cargo login
just1a1nexample

This command tells Cargo your API token and stores it locally in ~/.cargo/credentials. Note that this token must not be shared with anyone else. If you leak it, you should revoke it and generate a new token on crates.io.

14.4.2 Add Metadata to the Crate

Before publishing a crate, you also need to add some metadata to the [package] section in Cargo.toml:

First, make sure the project name is unique on the website.
Second, write a description, which is a short introduction. It does not need to be long; one or two sentences is enough. The description will appear in crate search results.
You need to provide the license identifier value used by this crate (you can look it up at spdx.org/licenses/); you can specify multiple licenses, separated by OR, in license.
Semantic version information goes in version.
Author information goes in authors.

Of course, you can provide more information than that; for details, see the Cargo Book.

The full [package] section should look like this:

[package]
name = "guessing_game"
version = "0.1.0"
edition = "2021"
description = "A fun game where you guess what number the computer has chosen."
license = "MIT OR Apache-2.0"

14.4.3 Publish a Crate with a Command

You can publish a crate with the cargo publish command, but only if the metadata is complete and the project name is unique.

When cargo publish runs successfully, it sends a verification email to the address registered to your crates.io account; just confirm it in your inbox.

If something goes wrong, cargo publish reports an error:

$ cargo publish
    Updating crates.io index
warning: manifest has no description, license, license-file, documentation, homepage or repository.
See https://doc.rust-lang.org/cargo/reference/manifest.html#package-metadata for more info.
......
error: failed to publish to registry at https://crates.io

Caused by:
  the remote server responded with an error: missing or empty metadata fields: description, license. Please see https://doc.rust-lang.org/cargo/reference/manifest.html for how to upload metadata

I omitted some of the middle content. The Caused by section says that the error was caused by missing metadata.

Once a crate is published, it is permanent: that version cannot be overwritten, and the code cannot be deleted. This is so projects depending on that version can continue to work normally.

14.4.4 Publish a New Crate Version

If you need to publish a newer version of an existing crate, modify the crate source code, update the version value in Cargo.toml according to semantic versioning, and then publish again.

14.4.5 Yank a Version

Yanking a version prevents new projects from depending on that version, but projects that were already built against it can still use and download it.

The command is cargo yank --vers the-specified-version. For example, to yank version 1.0.1, write:

cargo yank --vers 1.0.1

If you change your mind after yanking and want to undo it, write:

cargo yank --vers 1.0.1 --undo

yank means:

Projects that already have a generated Cargo.lock will not be interrupted by the version being yanked.
Future Cargo.lock files will not use the yanked version.

[Rust Guide] 14.3. Re-Exporting APIs with Pub Use

SomeB1oody — Wed, 08 Jul 2026 03:30:52 +0000

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

14.3.1 Re-Exporting APIs with `pub use`

In Chapter 7, we introduced the mod keyword. We use it to organize code into modules. The pub keyword introduced there can make modules or methods public so that external code can call them. External code then uses the use keyword to bring modules or methods into the current scope.

Using these keywords lets us organize code in a developer-friendly way. However, this structure is not always very friendly for the end users of the codebase. For example, the structure of a crate may be very convenient for developers during development, but not very convenient for users. Developers often split the program into many layers, and users may find it difficult to locate a type hidden deep inside that structure. For example, my_crate::some_module::another_module::UsefulType is cumbersome, while my_crate::UsefulType is much easier to use.

For this kind of problem, there is no need to reorganize the internal code structure. Instead, pub use can be used to re-export items and create a public-facing structure different from the internal private structure. Re-exporting takes a public item from one location and makes it public at another location, as if it had been defined there originally.

Here is an example:
lib.rs:

//! # Art
//!
//! A library for modeling artistic concepts.

pub mod kinds {
    /// The primary colors according to the RYB color model.
    pub enum PrimaryColor {
        Red,
        Yellow,
        Blue,
    }

    /// The secondary colors according to the RYB color model.
    pub enum SecondaryColor {
        Orange,
        Green,
        Purple,
    }
}

pub mod utils {
    use crate::kinds::*;

    /// Combines two primary colors in equal amounts to create
    /// a secondary color.
    pub fn mix(c1: PrimaryColor, c2: PrimaryColor) -> SecondaryColor {
        //...
    }
}

Under the kinds module there are two enum types, PrimaryColor and SecondaryColor, used to store color variants.
Under the utils module there is a function called mix. Its job is to mix two PrimaryColor values into a SecondaryColor. The code inside is not shown here.
Putting the enum types under kinds and the function under utils is very developer-friendly.

main.rs:

use art::kinds::PrimaryColor;
use art::utils::mix;

fn main() {
    let red = PrimaryColor::Red;
    let yellow = PrimaryColor::Yellow;
    mix(red, yellow);
}

This uses the enum types and the mix function from lib.rs. Because it requires three levels to bring them into scope, and because the enum type and function live in different modules, it is quite inconvenient for users.

The generated crate documentation looks like this:

If we refactor the code using re-exports:
lib.rs:

//! # Art
//!
//! A library for modeling artistic concepts.

pub use self::kinds::PrimaryColor;
pub use self::kinds::SecondaryColor;
pub use self::utils::mix;

pub mod kinds {
    /// The primary colors according to the RYB color model.
    pub enum PrimaryColor {
        Red,
        Yellow,
        Blue,
    }

    /// The secondary colors according to the RYB color model.
    pub enum SecondaryColor {
        Orange,
        Green,
        Purple,
    }
}

pub mod utils {
    use crate::kinds::*;

    /// Combines two primary colors in equal amounts to create
    /// a secondary color.
    pub fn mix(c1: PrimaryColor, c2: PrimaryColor) -> SecondaryColor {
        //...
    }
}

main.rs:

use art::mix; 
use art::PrimaryColor;

fn main() {
    let red = PrimaryColor::Red;
    let yellow = PrimaryColor::Yellow;
    mix(red, yellow);
}

At this point, calling the enum type and the function no longer requires writing module paths layer by layer.

The generated crate documentation now looks like this:

The documentation includes a Re-exports section, and all re-exported items are listed there. For actual users of the crate, this makes it very convenient to find these types and functions.

[Rust Guide] 14.2. Documentation Comments and Publishing Crates

SomeB1oody — Wed, 08 Jul 2026 03:27:13 +0000

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

14.2.1 crates.io

crates.io is the official package management platform for the Rust programming language, similar to package managers in other languages such as npm for JavaScript and pip for Python. Its main uses include:

Hosting Rust libraries (crates): Developers can publish their own Rust libraries on crates.io, and other developers can download and use them.
Dependency management: Cargo, Rust’s build tool and package manager, downloads required dependencies from crates.io to simplify project development.
Search and discovery: Users can search for existing libraries on crates.io and find solutions that fit their project needs.
Versioning and updates: crates.io supports version management, so developers can upload new versions of libraries and users can update dependencies easily.

In the guessing game from Chapter 1, we already used the third-party rand crate from crates.io to get random numbers. We can use crates provided by others, and we can also publish our own crates to crates.io for others to use.

Rust and Cargo include features that make your published packages easier for people to find and use. Next we will discuss some of those features and then explain how to publish a package.

14.2.2 Documentation Comments

Use /// to write documentation comments. Documentation comments are used to generate project documentation. They are different from //, which is used for code comments. Documentation comments are annotations for the whole project.

This documentation is HTML documentation and supports Markdown. It displays documentation comments for public APIs and usually explains how readers should use the API.

Documentation comments are usually placed directly before the item they describe.

Here is an example:

PS: In Markdown, # marks a heading.

14.2.3 Commands for Generating HTML Documentation

Running cargo doc in the terminal uses the rustdoc tool, which comes with Rust, to generate documentation. The generated documentation is placed in the target/doc directory.

cargo doc --open generates the documentation and opens the result in a web browser:

14.2.4 Common Sections

Here are some sections that crate authors often use in their documentation:

# Example is the examples section, where sample code is placed in the code block.
Panic: The function being documented may panic. Callers who do not want the program to panic should ensure that the function is not called in those cases.
Error: If the function returns a Result, then describing the possible error types and the conditions that may cause those errors is helpful to callers, so they can write code that handles different errors in different ways.
Safety: If the function calls unsafe (which we will cover later), there should be a section explaining why the function is unsafe and covering the invariants the caller is expected to uphold.

14.2.5 Documentation Comments as Tests

Code blocks in documentation comments are executed as tests when you run cargo test. You will see this part in the test results:

   Doc-tests my_crate

running 1 test
test src/lib.rs - add_one (line 5) ... ok

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

14.2.6 Adding Documentation Comments for Items with Outer Comments

//! adds documentation to the outer item, rather than to the item that follows the comment. We usually use these documentation comments in the crate root file, conventionally src/lib.rs, or inside a module to document a crate or an entire module:

In this example, we added documentation describing what my_crate does, that is, comments on the outer item of add_one.

The HTML documentation changes accordingly as well:

[Rust Guide] 14.1. Cargo Publishing Configuration

SomeB1oody — Wed, 08 Jul 2026 03:10:53 +0000

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

14.1.1 Release Profile

A release profile is a publishing configuration, meaning it is a set of pre-defined configuration options. It is also customizable. We can define our own configurations and use different settings, giving programmers more control over how code is compiled.

Each profile is its own configuration preset and is independent from the others.

Cargo mainly has two profiles:

dev profile: used for development and cargo build
release profile: used for publishing and cargo build --release

Using cargo build and cargo build --release will apply two different configuration profiles:

$ cargo build
    Finished dev [unoptimized + debuginfo] target(s) in 0.0s
$ cargo build --release
    Finished release [optimized] target(s) in 0.0s

14.1.2 Custom Profiles

Cargo provides default settings for each profile.

If you want to customize the configuration, whether for dev profile or release profile, you can add a [profile.xxxx] section to Cargo.toml and override a subset of the default settings. Usually we do not override every option; we only override the ones we want to change.

Here is an example:

[profile.dev]
opt-level = 0

[profile.release]
opt-level = 3

The opt-level setting controls how much optimization Rust applies to your code, with values ranging from 0 to 3. Applying more optimizations increases compile time, so if you are developing and compiling code frequently, you may want fewer optimizations even if the generated code runs more slowly, because that speeds up compilation. That is why the default opt-level for dev is 0.

When you are ready to publish code, it is better to spend more time compiling. Code is compiled only once in release mode, but the compiled program runs many times, so release mode trades longer compile time for faster code. That is why the default opt-level for release is 3.

[Rust Guide] 13.10. Performance Comparison - Loops vs. Iterators

SomeB1oody — Mon, 06 Jul 2026 04:25:01 +0000

13.10.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
Improving the I/O Project with Closures and Iterators
Performance of Closures and Iterators (this article)

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

13.10.1 A Test

To run a benchmark test, load all of The Adventures of Sherlock Holmes by Sir Arthur Conan Doyle into a String and search the contents for the word the. Here are the benchmark results for the search version that uses a for loop and the version that uses iterators:

test bench_search_for  ... bench:  19,620,300 ns/iter (+/- 915,700)
test bench_search_iter ... bench:  19,234,900 ns/iter (+/- 657,200)

The iterator version is slightly faster!

We will not explain the benchmark code here, because the point is not to prove that the two versions are equivalent. The point is to get a rough idea of how these two implementations compare in performance.

Iterators are a high-level abstraction in Rust, yet the code they generate after compilation is almost the same as the low-level code we would write by hand. This is called a zero-cost abstraction.

13.10.2 Zero-Cost Abstraction

Zero-cost abstraction means that using an abstraction does not introduce extra runtime overhead.

Rust iterators can achieve zero-cost abstraction because:

1. Generics and Monomorphization

Rust iterators make heavy use of generics to define operations, such as the Iterator trait. During compilation, the compiler instantiates generic code for each concrete type and generates efficient machine code specialized for those types. This process is called monomorphization.

Static dispatch: The compiler generates code that calls functions directly for concrete types, so there is no need to look up function addresses at runtime, unlike dynamic dispatch through a virtual table.
Optimization opportunities: Because the types are known at compile time, the compiler can deeply optimize the code, such as eliminating function-call overhead and inlining.

2. Inlining and LLVM Optimization

Rust uses LLVM as its backend compiler. The compiler can optimize iterator chains in the following ways:

Function inlining: The Rust compiler inlines operations inside iterators, such as map and filter, expanding them into compact code without function-call overhead.
Loop unrolling and merging: Multiple iterator method calls, such as map().filter().collect(), can be merged into a single loop at compile time.
Redundancy elimination: For example, the compiler can directly remove some unnecessary intermediate variables or operations.

The result is that the final code executed by an iterator chain is almost as efficient as a hand-written loop.

3. Lazy Evaluation

Rust iterators are lazy, which means:

Before a terminal method is called, such as collect() or for_each(), the iterator does not perform any actual work.
Each intermediate operation, such as map and filter, only creates a new iterator and does not apply the operation immediately.

This lazy design allows the compiler to generate code optimized for the final use case when the iterator is actually used, without introducing unnecessary intermediate data structures or calculations.

4. No Runtime Overhead

One of Rust’s design principles is to avoid runtime costs. Iterator implementations avoid dynamic allocation and runtime polymorphism:

Rust iterators are based on static types, so they usually do not require heap allocation, unless you explicitly use Box or dyn Iterator.
The Iterator trait uses static dispatch, which avoids dynamic dispatch. Even when dynamic dispatch is needed, you must explicitly declare dyn Iterator.

5. No Extra Abstraction Cost

Rust iterators provide functionality by operating directly on the underlying data structures, without introducing extra abstraction layers. For example:

An iterator created by calling .iter() operates directly on the underlying slice or collection, so the overhead is very low.
Intermediate iterators, such as Map and Filter, are optimized at compile time into a compact set of instructions instead of introducing unnecessary wrapping.

13.10.3 An Example: An Audio Decoder

The following code comes from an audio decoder. The decoding algorithm uses linear prediction math to estimate future values from a linear function of previous samples. This code uses an iterator chain to perform several mathematical operations on three variables in a range: a buffer slice of data, an array of 12 coefficients, and the amount of data shifting in qlp_shift. We declare the variables in this example but do not assign values to them. Although this code does not mean much outside its original context, it is still a concise, real-world example of how Rust turns high-level ideas into low-level code.

let buffer: &mut [i32];
let coefficients: [i64; 12];
let qlp_shift: i16;

for i in 12..buffer.len() {
    let prediction = coefficients.iter()
                                 .zip(&buffer[i - 12..i])
                                 .map(|(&c, &s)| c * s as i64)
                                 .sum::<i64>() >> qlp_shift;
    let delta = buffer[i];
    buffer[i] = prediction as i32 + delta;
}

To compute the prediction value, this code iterates over each of the 12 values in coefficients and uses zip to pair each coefficient with the previous 12 values in buffer. Then, for each pair, it multiplies the values, sums all the results, and shifts the total to the right by qlp_shift bits.

All coefficients are stored in registers, which means accessing these values is very fast. There are no bounds checks on array access at runtime. All of these optimizations that Rust can apply make the generated code extremely efficient. Now that you know this, you can use iterators and closures without fear! They make the code look higher level without causing runtime performance loss.

[Rust Guide] 13.9. Improving the I/O Project With Closures and Iterators

SomeB1oody — Mon, 06 Jul 2026 04:18:02 +0000

13.9.0 Before We Begin

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

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

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

13.9.1 Review

This article uses the grep project from Chapter 12 as an example to show how closures and iterators can improve an I/O project, so let’s review it first.

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

The project is split into these steps:

Accept command-line arguments
Read a file
Refactor to improve modules and error handling
Develop library functionality with TDD (test-driven development)
Use environment variables
Write error messages to standard error instead of standard output

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("CASE_INSENSITIVE").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.to_lowercase().lines() {  
        if line.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| {  
        eprintln!("Problem parsing arguments: {}", err);  
        process::exit(1);  
    });  
    if let Err(e) = minigrep::run(config) {  
        eprintln!("Application error: {}", e);  
        process::exit(1);  
    }  
}

13.9.2 Improving the `new` Function

Take a look at the new function in lib.rs:

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})  
    }  
}

These two lines:

let query = args[1].clone();  
let filename = args[2].clone();

use cloning. That is because the argument passed in is &[String], which does not have ownership, but the Config struct needs to own the data. Only cloning lets Config own query and filename, even though cloning adds performance overhead.

After learning iterators, we can pass an iterator directly into new so that it can take ownership. We can also use the iterator to handle length checks and indexing, which makes the scope of new’s responsibility clearer.

Before changing new, we need to change how main handles input arguments. Originally it was:

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

Now we remove collect and pass the arguments from env::args() directly to new:

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

The return type of env::args() is std::env::Args, which implements the Iterator trait, so it is an iterator.

Now let’s modify new:

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

The parameter args is changed to std::env::Args, and it must also be declared mutable with mut because next is a consuming iterator method.
The line that contains only args.next(); is there because the first value returned by env::args() is the program name, not an argument. Calling args.next(); skips that value.
query and filename are then obtained in order by calling next. At that point, query and filename are owned String values. Since next returns an Option, we can use unwrap to extract the value.

13.9.3 Improving the `search` Function

The current search function looks like this:

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  
}

contents.lines() also returns an iterator. Here we manually check whether each line contains the keyword stored in query, and if it does, we push that line into the Vector and finally return the Vector.

For finding items that satisfy a condition in an iterator and building a new iterator, we can use filter:

pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {  
    contents.lines().filter(|line| line.contains(query)).collect()  
}

Using contains inside the closure implements the same logic.

Since the ordinary search function can use iterators, the case-insensitive search function can use them too:

pub fn search_case_insensitive<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {  
    contents.to_lowercase()  
        .lines()  
        .filter(|line| line.contains(&query.to_lowercase()))  
        .collect()  
}

Note that query.to_lowercase() needs & because query.to_lowercase() produces a String, while contains expects &str. So you cannot pass query.to_lowercase() directly; you must pass a reference, that is, &query.to_lowercase(), for it to work correctly.

To convert to &str, you can use &, of course, but you can also use as_str:

pub fn search_case_insensitive<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {  
    contents.to_lowercase()  
        .lines()  
        .filter(|line| line.contains(query.to_lowercase().as_str()))  
        .collect()  
}

In terms of both code volume and readability, using filter is better. In addition, filter reduces temporary variables. Eliminating mutable state (let mut results = Vec::new();) also makes it possible to improve search performance through parallelization in the future, because we no longer need to worry about concurrent access safety for results.

[Rust Guide] 13.8. Creating Custom Iterators

SomeB1oody — Mon, 06 Jul 2026 04:06:44 +0000

13.8.0 Before We Begin

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.8.1 Creating a Custom Iterator With the `Iterator` Trait

The main step is just one: provide an implementation of next.

Take an example:

Build an iterator that traverses from 1 to 5

struct Counter {  
    count: u32,  
}  

impl Counter {  
    fn new() -> Counter {  
        Counter { count: 0 }  
    }  
}  

impl Iterator for Counter {  
    type Item = u32;  
    fn next(&mut self) -> Option<u32> {  
        if self.count < 5 {  
            self.count += 1;  
            Some(self.count)  
        } else {  
            None  
        }  
    }  
}

First create a struct called Counter. It has a count field used to store the value needed during iteration, that is, the iterator’s state. The count field is private rather than pub so that the Counter struct manages its own value independently.
Then write an associated function new on the struct to create a new instance and make sure the new instance starts from 0.
Next, implement the Iterator trait for Counter. The Iterator trait has an associated type type Item and a next method. First set the associated type to u32, which means writing type Item = u32;. This syntax will be covered in detail in Chapter 19; for now, just know that this iterator returns u32.
The return type of next is Option<Self::Item>. Since the associated type above is u32, you can think of it as Option<u32>. When the count field is less than 5, it keeps increasing by 1; when it is 5 or greater, it returns None. That guarantees iteration from 1 to 5.

Now let’s implement something more complex:

Use a Counter struct in two forms: one from 1 to 5 and another from 2 to 5. Multiply each pair of elements from the two iterators, keep only the elements in the new iterator that are divisible by 3, and then return the sum of those elements

fn using_other_iterator_traits_methods() {  
    let sum: u32 = Counter::new()  
        .zip(Counter::new().skip(1))  
        .map(|(a, b)| a * b)  
        .filter(|x| x % 3 == 0)  
        .sum();  
}

I wrote it on separate lines because the chained call would be too long on one line. If the chain is not long, there is no need to split it across lines.
The zip method pairs each element from two iterators to form a new iterator. The elements of that new iterator are tuples, and each tuple has two values, one from each iterator.
Counter::new() creates a Counter that goes from 1 to 5, and Counter::new().skip(1) creates a Counter that skips the first value, so it goes from 2 to 5. When the two are zipped together, the result looks like this:

	`Counter::new()`	`Counter::new().skip(1)`
Tuple 0	1	2
Tuple 1	2	3
Tuple 2	3	4
Tuple 3	4	5

PS: Counter::new() does not iterate to 5 because Counter::new().skip(1) is None at that point, so no more values are produced.

map takes a closure that is applied to each element of the iterator. It transforms each element of the current iterator into another element, and those new elements form a new iterator. In this example, it multiplies the two values in each tuple stored in the iterator to produce a new iterator.
filter keeps the values divisible by 3 and forms a new iterator through the closure.
sum consumes all elements of the iterator and adds them together.

The final result should be 18.

[Rust Guide] 13.7. Using Closures to Capture the Environment With Iterators

SomeB1oody — Mon, 06 Jul 2026 04:01:27 +0000

13.7.0 Before We Begin

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.7.1 Using Closures to Capture the Environment

The filter method is an iterator adaptor that is usually used together with a closure that captures the environment.

The filter method takes a closure that returns a boolean value as it traverses each element of the iterator. If the return value is true, the current element will be included in the new iterator produced by filter; otherwise, the current element will not be included.

Take an example:

Use filter with a closure to capture the shoe_size variable from the environment and iterate over a collection of Shoe struct instances. It will return only shoes of the specified size.

#[derive(PartialEq, Debug)]
struct Shoe {
    size: u32,
    style: String,
}

fn shoes_in_size(shoes: Vec<Shoe>, shoe_size: u32) -> Vec<Shoe> {
    shoes.into_iter().filter(|s| s.size == shoe_size).collect()
}

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

    #[test]
    fn filters_by_size() {
        let shoes = vec![
            Shoe {
                size: 10,
                style: String::from("sneaker"),
            },
            Shoe {
                size: 13,
                style: String::from("sandal"),
            },
            Shoe {
                size: 10,
                style: String::from("boot"),
            },
        ];

        let in_my_size = shoes_in_size(shoes, 10);

        assert_eq!(
            in_my_size,
            vec![
                Shoe {
                    size: 10,
                    style: String::from("sneaker")
                },
                Shoe {
                    size: 10,
                    style: String::from("boot")
                },
            ]
        );
    }
}

The Shoe struct has two fields: size, which represents the shoe size and is of type u32, and style, which represents the style and is of type String.
The shoes_in_size function takes two parameters: shoes, whose type is Vec<Shoe>, and shoe_size, whose type is u32, and it returns a Vec<Shoe>. The function body first calls into_iter on the incoming Vector to create an iterator that takes ownership. Then it uses filter, whose argument is a closure. The closure checks each element’s size field to see whether it matches shoe_size; if it does, the element is included in the new iterator. Finally, collect is called to turn the result into a collection and return it.

[Rust Guide] 13.6. Methods That Consume and Produce Iterators

SomeB1oody — Mon, 06 Jul 2026 03:59:32 +0000

13.6.0 Before We Begin

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.6.1 Methods That Consume Iterators

In the standard library, the Iterator trait has some methods with default implementations. Some of them call next, which is why implementing the Iterator trait requires implementing next.

Methods that call next are called consuming adaptors because next consumes the iterator one element at a time until the iterator is exhausted.

For example, the sum method takes ownership of the iterator and repeatedly calls next to traverse the items, thereby consuming the iterator. As it iterates, it adds each item to a running total and returns the total when iteration is complete.

#[cfg(test)]
mod tests {
    #[test]
    fn iterator_sum() {
        let v1 = vec![1, 2, 3];
        let v1_iter = v1.iter();
        let total: i32 = v1_iter.sum();
        assert_eq!(total, 6);
    }
}

13.6.2 Methods That Produce Other Iterators

The Iterator trait also defines other methods called iterator adaptors. They turn the current iterator into a different kind of iterator. You can also chain multiple iterator adaptors together to perform complex operations, and this style of code is quite readable.

Take map as an example. It takes a closure that is applied to each element of the iterator. It transforms each element of the current iterator into another element, and those new elements form a new iterator.

let v1: Vec<i32> = vec![1, 2, 3];
v1.iter().map(|x| x + 1);

This code adds 1 to each element in the Vector.

There is nothing wrong with the code itself, but the compiler produces a warning:

$ cargo run
   Compiling iterators v0.1.0 (file:///projects/iterators)
warning: unused `Map` that must be used
 --> src/main.rs:4:5
  |
4 |     v1.iter().map(|x| x + 1);
  |     ^^^^^^^^^^^^^^^^^^^^^^^^
  |
  = note: iterators are lazy and do nothing unless consumed
  = note: `#[warn(unused_must_use)]` on by default
help: use `let _ = ...` to ignore the resulting value
  |
4 |     let _ = v1.iter().map(|x| x + 1);
  |     +++++++

warning: `iterators` (bin "iterators") generated 1 warning
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.47s
     Running `target/debug/iterators`

Because Rust iterators are lazy, if you do not consume them (that is, if you do not call consuming adaptor methods), they do nothing. In other words, in this state it does not add 1 to the three elements in the Vector unless a consuming method is called:

let v1: Vec<i32> = vec![1, 2, 3];
let v2:Vec<_> = v1.iter().map(|x| x + 1).collect();

Here collect is used as a consuming adaptor to collect the results into some kind of collection. Since collect can produce many collection types, we need to explicitly annotate v2 as a Vec<_>. The _ in Vec<_> tells the compiler to infer the element type.

[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

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.

DEV Community: SomeB1oody

[Rust Guide] 14.6. Installing Binary Crates

14.6.1 Install a Binary Crate from crates.io

14.6.2 cargo install

14.6.3 Extending Cargo with Custom Commands

[Rsut Guide] 14.5. Cargo Workspace

14.5.1 Why Cargo Workspaces Are Needed

14.5.2 Using a Workspace

1. Create the Workspace Directory

2. Use the Workspace in the Main Project

3. Add the Library

4. Write the Code

5. Build

6. Testing

[Rust Guide] 14.4. Publishing Crates Part 2

14.4.1 Create and Set Up a crates.io Account

14.4.2 Add Metadata to the Crate

14.4.3 Publish a Crate with a Command

14.4.4 Publish a New Crate Version

14.4.5 Yank a Version

[Rust Guide] 14.3. Re-Exporting APIs with Pub Use

14.3.1 Re-Exporting APIs with pub use

[Rust Guide] 14.2. Documentation Comments and Publishing Crates

14.2.1 crates.io

14.2.2 Documentation Comments

14.2.3 Commands for Generating HTML Documentation

14.2.4 Common Sections

14.2.5 Documentation Comments as Tests

14.2.6 Adding Documentation Comments for Items with Outer Comments

[Rust Guide] 14.1. Cargo Publishing Configuration

14.1.1 Release Profile

14.1.2 Custom Profiles

[Rust Guide] 13.10. Performance Comparison - Loops vs. Iterators

13.10.0 Before We Begin

13.10.1 A Test

13.10.2 Zero-Cost Abstraction

13.10.3 An Example: An Audio Decoder

[Rust Guide] 13.9. Improving the I/O Project With Closures and Iterators

13.9.0 Before We Begin

13.9.1 Review

13.9.2 Improving the new Function

13.9.3 Improving the search Function

[Rust Guide] 13.8. Creating Custom Iterators

13.8.0 Before We Begin

13.8.1 Creating a Custom Iterator With the Iterator Trait

[Rust Guide] 13.7. Using Closures to Capture the Environment With Iterators

13.7.0 Before We Begin

13.7.1 Using Closures to Capture the Environment

[Rust Guide] 13.6. Methods That Consume and Produce Iterators

13.6.0 Before We Begin

13.6.1 Methods That Consume Iterators

13.6.2 Methods That Produce Other Iterators

[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

14.6.2 `cargo install`

14.3.1 Re-Exporting APIs with `pub use`

13.9.2 Improving the `new` Function

13.9.3 Improving the `search` Function

13.8.1 Creating a Custom Iterator With the `Iterator` Trait

13.5.2 The `Iterator` Trait