Rust From the Ground Up

The Rust CLI Programming book by Matthew Provost

New! Updated for the 2021 Edition of Rust and `clap` version 3

In 2024, developers voted for Rust as their most admired programming language for the second year in a row.

This book is for "day one" Rust programmers who want to achieve fluency in idiomatic Rust by implementing real-world programs, without fighting the borrow checker. Each example-heavy chapter implements a single CLI program in Rust based on the original BSD Unix source code. (No experience with programming in C required!).

"Rust From the Ground Up" flattens Rust's learning curve, teaching you how to build practical, real-world applications which handle realistic conditions such as edge cases and errors. Every chapter in Rust From the Ground Up takes a “show, don’t tell” approach: examining the original BSD sources for a well-known Unix CLI program, and introducing just enough Rust features to build a fully functional copy. After reading this book, you will have gained the confidence and intuition to write production-quality Rust programs.

Security

Its ownership system makes Rust particularly well suited for replacing existing programs written in the C language, which is notorious for producing programs with bugs caused by its lack of memory safety. Apple, Microsoft, and Google have reported that at least 70% of the security vulnerabilities in their C/C++ codebases are caused by memory safety bugs.

Borrow Checker

The Rust compiler's borrow checker has a reputation as being difficult to work with. The borrow checker validates the ownership and lifetimes of values in memory at compile time, without a garbage collector. New Rust programmers often feel like they are "fighting the borrow checker" until they build intuition about how ownership works.

Ownership

Understanding ownership is hard, and sometimes the easiest way to get a Rust program to compile is by copying a value in memory, or using reference counting. This book tackles ownership head on, demonstrating clear strategies for resolving common issues with the borrow checker, without relying on inefficient copying, reference counting, or more advanced concepts such as lifetimes.

Real World Code

The goal of this book is to teach a programmer with no Rust experience how to write production quality, idiomatic Rust code that safely handles real world edge cases and errors. There are no linked list exercises, made up examples (like FizzBuzz), demos (Mandelbrot), or sample code. Every chapter produces a real program by examining the original C source code for a classic BSD Unix CLI utility and incrementally building a fully functional version in Rust.

No C Required

Rust's syntax is familiar to programmers accustomed to languages such as C, C++, or Java, with blocks of code surrounded by curly braces {}, comments starting with // or surrounded by /* and */, and statements terminated with ;. But this book doesn't require specific experience in C programming; each chapter explains the syntax and functions used in the read-only C examples.

Idiomatic

Each chapter rewrites a C program in stylish, idiomatic Rust. Instead of mechanical, line by line translations, the book emphasizes a functional programming style, heavily focusing on iterators and avoiding mutable state. For example, rewriting the head program (which prints the first 10 lines from each filename argument):

#include <stdio.h> #include <stdlib.h> int main(int argc, char *argv[]) { FILE *fp; int ch; long cnt, linecnt = 10; for (argv++; *argv; ++argv) { if ((fp = fopen(*argv, "r")) != NULL) { for (cnt = linecnt; cnt && !feof(fp); --cnt) { while ((ch = getc(fp)) != EOF) { if (putchar(ch) == '\n') { break; } } } fclose(fp); } } }

use std::env::args; use std::fs::File; use std::io::{self, BufRead, BufReader}; fn main() -> io::Result<()> { let args = args().skip(1); let files = args.map(|arg| File::open(arg).map(BufReader::new)); let linecnt = 10; for file in files { for line in file?.lines().take(linecnt) { println!("{}", line?); } } Ok(()) }

Table of Contents

Checking the exit status of a process with the shell's $? variable
Defining a Rust function with the fn keyword
Installing the Rust toolchain with rustup
Verifying the version of Rust with the rustc compiler
Creating a new Rust project with cargo new
Building Rust programs with cargo build
Installing a linker with apt
Running a Rust program with cargo run
Formatting Rust source code with cargo fmt
Running a specific binary with cargo's --bin option
Representing signed and unsigned integer types
Specifying a function's return type with a right arrow "->"
Returning a value from a function with the return keyword
Representing an empty value with the unit type "()"
Representing fallible operations with the Result type
Separating namespace paths with "::"
Importing a function with a use declaration
Annotating the types of function parameters with ":"
Returning a status code with exit()
Representing the Never type with "!"
Linting Rust source code with clippy
Implicitly returning the unit type "()" from a function

Piping the output of one program to another with the shell's "|" operator
Outputting a line of text with the println! macro
Identifying macros with "!"
Looping infinitely with a loop expression
Building a specific program with cargo's --bin option
Constructing an Args struct with args()
Representing a group of fields as a struct
Declaring public visibility with the pub keyword
Representing a sequence of items with an iterator
Defining methods with the fn keyword
Receiving a method with the self keyword
Defining sets of methods with the trait keyword
Associating types with a trait
Representing optional values with the Option enum
Composing an Option enum of the Some and None variants
Enclosing generic types in angle brackets "<>"
Yielding the next item in an iterator with next()
Implementing a trait with the impl keyword
Yielding a heap-allocated String from the Args iterator
Returning an item at an index with nth()
Binding a value to a variable with a let statement
Terminating statements with ";"
Formatting output with format strings
Enclosing string literals in double quotes ""
Replacing placeholders "{}" in format strings
Mutably borrowing a value with &mut
Unwrapping an Option with unwrap()
Calling methods with "."
Automatically borrowing method receivers
Chaining method calls together
Terminating programs safely by panicking
Pattern matching with a match expression
Binding candidate patterns with a fat arrow "=>"
Automatically importing the prelude
Destructuring the target of a match arm
Returning errors from the writeln! macro
Obtaining a handle to stdout with stdout()
Generating code with a macro
Formatting function names in snake_case
Suppressing an expression's value with ";"
Creating a mutable variable binding with the mut keyword
Returning an unwrapped Option or a default value with unwrap_or()
Referencing a string elsewhere in memory with a string slice (&str)
Copying a static string to the heap with to_string()
Lazily computing a default value with unwrap_or_else()
Specifying a bounds on a generic parameter with a where clause
Creating an anonymous function with a closure expression
Composing a Result enum of the Ok and Err variants
Unwrapping the Ok value from a Result with unwrap()
Naming structs, enums, and variants in UpperCamelCase
Matching any value with the wildcard pattern "_"
Ignoring variable names prefixed with "_"
Implicitly borrowing the parameters to println! and writeln!
Determining the kind of error with kind()
Redirecting the output of a command with the shell's ">" operator

Defining a type alias for std::io::Result with the type keyword
Cheaply converting references with the AsRef trait's as_ref() method
Implementing AsRef converts a String to a Path
Importing a struct with use to access its associated functions
Binding the receiver of the current method to the self variable
Generating an alias to the type of a method's receiver with the Self keyword
Transforming the elements of an iterator with map()
Creating an unnamed, anonymous function with a closure expression
Processing iterators with for loops
Reading lines with the std::io::Lines iterator
Creating a Lines iterator with the BufRead traits's lines() method
Requiring a Sized type with a where clause
Creating a BufReader (implementing BufRead) with new()
Transforming an Ok Result with map()
Importing multiple paths in a single use declaration
Formatting strings with the Display trait
Iterating on a Result to yield the Ok value
Discarding the first n items from an iterator with the skip() iterator adaptor
Shadowing existing identifiers when declaring a variable with let
Replacing redundant closures with a function name
Conditionally binding a value with an if let expression
Removing one level of iteration with flatten()
Yielding up to n items from an iterator with take()
Closing files automatically with the Drop trait's drop() method
Transforming the Err value of a Result with map_err()
Capturing variables with closures
Printing to stderr with the eprintln! macro
Reducing an iterator to a single value with fold()
Returning the number of items in an ExactSizeIterator with len()
Obtaining a handle to standard input with stdin()
Reading a line from stdin with the Stdin struct's read_line() method
Creating an iterator yielding integers starting with one value up until a second with the range
operator (..)
Allocating an empty String with String::new()
Exiting a for loop with a break expression
Matching and removing a pattern from the start of a string with strip_prefix()
Tracking references to values with lifetimes
Converting a string to another type with parse()
Performing conversions by implementing the FromStr trait's from_str() method
Transforming an Option's Some value with map()
Mutably borrowing a value with &mut
Unwrapping an Option or a default value with unwrap_or()
Creating a Peekable iterator with peekable()
Peeking at the next item yielded from a Peekable iterator with peek()
Checking if an Option has Some value with is_some()

Folding an iterator into a single value
Reading bytes with the Read trait's bytes() iterator
Translating an escape sequence into a nonprinting character
Encoding characters as a single byte with a byte literal
Borrowing a String with the borrow operator
Specifying a minimum width for a format string placeholder
Defining a new function with the fn keyword
Accepting a variable number of parameters with a macro
Printing a blank line with the println! macro
Checking the size of the args() iterator with the ExactSizeIterator's len() method
Defining unique names for functions
Checking if a byte represents an ASCII whitespace character with is_ascii_whitespace()
Storing a fixed number of values in a tuple
Destructuring a tuple to bind its elements to local variables
Ignoring values with a "_" wildcard
Enclosing generic parameters in angle brackets "<>"
Constraining a generic parameter to a list of trait bounds
Monomorphizing a generic function for each parameter type
Mangling function names so they're unique
Examining compiled Rust executables with rust-gdb
Listing functions with gdb's info functions command
Extending the Rust standard library's functionality with crates
Adding a dependency for a crate to the project's Cargo.toml file
Creating a named clap App with new()
Converting types with the Into and From traits
Allocating a String from a &str with from()
Constructing a clap argument with Arg::new()
Automatic reflexive conversions with the Into trait
Implementing a fluent interface with methods that return Self
Incrementally constructing complex structs following the "builder" pattern
Chaining methods to create and configure a struct in a single expression
Parsing the command line arguments into an ArgMatches struct with get_matches()
Iterating over the values of an argument with values_of()
Binding an argument to an option letter with short()
Escaping a character literal in single quotes
Adding a description to an argument with help()
Converting any type into Some with from()
Declaring global variables with the static keyword
Specifying the return type of a function with a right arrow "->"
Evaluating a function's body to return a value
Checking for the presence of an argument with is_present()
Assigning multiple variables by destructuring a tuple
Matching on a tuple
Enabling an Arg to accept multiple values with multiple_values()
Automatically deallocating values with drop()
Verifying that the program closes files with strace
Buffering input with a BufReader
Creating a buffer with a specific capacity using with_capacity()
Reading from Stdin without a lock()
Compiling Rust programs in "release" mode
Inlining to eliminate the overhead of generic functions

Copying data from a reader to a writer with the std::io::copy() function
Relaxing the Sized restriction on generic parameters with the questionably sized (?Sized) trait bound
Implementing a trait with a dynamically sized trait object
Dynamically dispatching to different concrete types at runtime with the dyn keyword
Referencing a trait object with a fat pointer
Mapping an iterator of arguments to opened files with map()
Comparing two values with the equality operator "=="
Overloading the equality operator "==" with the PartialEq trait's eq() method
Specifying a return type for a closure with "->"
Allocating a sized Box containing a questionably sized type with Box::new()
Creating an iterator yielding a single value with std::iter::once()
Erasing a concrete type by casting to a trait object
Casting a value to a type in a type cast expression with the "as" operator
Aliasing a type to a new identifier with the "type" keyword
Specifying an identifier for an associated type in a trait definition with a type alias
Implementing a trait with the "impl" keyword
Yielding multiple values from an iterator with a tuple
Destructuring a tuple to multiple variables
Exiting the program with a status code with exit()
Writing a slice of bytes with write()
Enclosing a series of values in "[]" to create an array
Taking a slice of an array with the borrow operator "&"
Evaluating for expressions to "()"
Returning Ok(()) from a function to indicate success
Returning an Err value early with the try operator "?"
Flushing a write buffer with flush()
Combining two Results with the and() combinator method

Querying arguments at runtime with clap's is_present() method
Mapping an io::Result to an io::Result<(u8,u8)>
Replacing an if expression evaluating to a boolean with a match guard
Inferring the type of Item yielded by an iterator with the "_" placeholder
Skipping None values yielded by an iterator with flatten()
Destructuring a tuple with a pattern in a let statement
Mapping and then flattening each element in an iterator with flat_map()
Specifying a minimum width for a number in a format string
Writing to stdout with the write! macro
Obtaining a mutually exclusive lock on Stdout with its lock() method
Making borrows immutable with lock()
Printing to stdout as a side effect of a map()
Checking if a byte is a valid ASCII value with is_ascii()
Matching meta characters with a match guard which calls is_ascii()
Converting a byte into a valid ASCII value by stripping its high bit with a bitwise and ("&")
Converting a control character into a printable character with a bitwise or ("|")
Adapting an iterator to filter certain items and map others with filter_map()
Testing if a byte is a control character with is_ascii_control()
Matching control characters with a match guard which calls is_ascii_control()
Printing the value of an if...else expression with write!
Printing a slice of a buffer of bytes with write()
Taking a slice of an array with the borrow operator ("&")
Transposing a Result containing an Option into an Option containing a Result with transpose()

Annotating functions with the #[test] attribute

Causing tests to fail with the assert_eq! macro

Calling functions with either stack or heap allocated parameters using a slice (&[T])

Checking if a slice contains an element with contains()

Creating a negation expression with the negation operator (!)

Allocating an empty Vec struct with its new() function

Running tests with cargo's test subcommand

Unwrapping a Result as an assertion

Importing std::io to use the io::Result alias

Creating an iterator of lines with the BufRead trait's split() method

Obtaining a StdinLock struct implementing BufRead with lock()

Returning a Result from main()

Taking a mutable slice (&mut [T]) with as_mut_slice()

Writing an entire buffer with write_all()

Querying the current length of a Vec with len()

Enclosing a usize value in square brackets [] as an index expression

Defining an array of bytes with a double quoted byte string literal

Creating a range expression with the .. operator

Taking a slice of a Vec by borrowing it

Returning a value from a string with the std::str::FromStr trait's from_str() function

Parsing any type implementing FromStr with parse()

Converting a value to a string with the ToString trait's to_string() method

Creating an inclusive range with the ..= operator

Extending a Vec with new elements with resize()

Returning a ParseIntError from the NonZeroUsize struct's from_str() function when parsing "0"

Extracting a usize value from a NonZeroUsize struct with its get() method

Creating an iterable range by adding a starting value

Configuring clap to parse multiple, comma-delimited values for an Arg with the use_delimiter() builder method

Returning an iterator of values for an Arg with values_of()

Returning different error types from main() by returning a boxed trait object implementing std::error::Error

Finding the index of an item in an iterator with position()

Splitting a slice into subslices with split()

Comparing two iterators with the eq() method

Dereferencing with a reference pattern

Combining a pair of sequences into a sequence of pairs with zip()

Taking a slice of a Vec to iterate over its elements with iter()

Allocating a Vec by invoking the vec! macro with a value and a size

Appending a value to a Vec with push()

Setting a default value for an Arg with default_value()

Encoding a sequence of bytes as a string of characters with from_utf8()

Defines a double-quotes UTF-8 string literal

Defining a new module with the mod keyword

Prefixing a module with the #[cfg(test)] attribute to build it in test mode

Importing items from the parent module with the super keyword

Creating an empty Vec by invoking the vec! macro with an empty array ([])

Filtering items yielded from an iterator with filter()

Filtering items from an iterator and yielding items with a different type with filter_map()

Short-circuiting iteration with the fallible try_fold() method

Splitting a string into two substrings on a delimiter pattern with the split_once() method

Setting every element in a slice to a value with fill()

Testing if a Result is an Err value with is_err()

Defining a constant value with the const keyword