Work In Progress

This book is still going through heavy edits. Pardon the dust.

What you will find here

This book is a compendium of Rust ecosystem examples and resources. It is intended to be everything you need for day-to-day Rust coding, in one place. It demonstrates good practices to accomplish common programming tasks, using the crates of the Rust ecosystem. It summarizes the language and key features of the standard library. It includes numerous links to Rust resources.

Who should read this book

This book is intended for

• new Rust programmers, to get an overview of the capabilities of the Rust ecosystem and pointers to other resources,
• experienced programmers, to find code examples and review best practices for common programming tasks.

Readers should have already some basic familiarity with Rust⮳ concepts. The Rust book⮳ is an excellent resource for complete beginners to get started with. This said, key features of the language are succinctly summarized in this book's language section.

Why this book

Per the curated list of Rust crates blessed.rs⮳, "the standard library in Rust is much smaller than in Python or Go, for example. Those languages come with "batteries included" support ... Rust, on the other hand, gets things like that from the crates.io ecosystem and the Cargo package manager. But with more than 160 thousand crates (libraries) to choose from, a common complaint from new Rust developers is that they don't know where to start, which crates they ought to use, and which crates they ought to trust." There are no dominant frameworks or platforms akin to Rails, Django, Spring or Node in the Rust world at this time.

This book therefore intends to provide EXAMPLES to demonstrate the uses of KEY CRATES, that is libraries necessary for day-to-day Rust coding - examples which are absent from or scattered in the reference documentation⮳. It hopes to become a "cheat sheet on steroid" for the Rust ecosystem (not just for the Rust language).

This book includes most of the "Rust Cookbook"

The "Rust How-to" project started as a set of notes kept while the author was learning Rust and evolved in a standalone book. The author then came across the Rust Cookbook⮳ community project, which shares very similar goals. Unfortunately, no updates have been made to that book in more than 4 years. Many of its examples no longer work. Several crates it references are no longer maintained. The author thus decided to merge the contents of the Rust Cookbook into this book, testing and refreshing its examples, and expanding its coverage significantly.

How to read this book

The left sidebar is organized by topic.

• The book first quickly summarizes the basics of the language and often-used elements of the standard library.
• The crates section provides pointers on how to locate key crates and provides alphabetical and categorical indices of crates used in the book.
• The bulk of the book is divided in sections named after the crates.io categories⮳ whenever possible.
• Each section contains a list of recipes. The recipes are simple statements of a task to accomplish, like "generate random numbers in a range"; and each recipe is tagged with badges indicating which crates they use, like , and which categories on crates.io those crates belong to, like .
• The book focuses on cross-cutting concerns that affect most aspects of development e.g. error handling, error customization, configuration, debugging...
• Concurrency, including asynchronous programming, is covered in details. So are development tools.
• programming domains such as CLI and Web development.

The links section provides pointers to notable Rust websites, learning resources, cheat sheets, books, and code examples...

The contributing section details how to contribute to the book itself.

New Rust programmers should be comfortable reading from the first section to the last, and doing so should give one a strong overview of the crate ecosystem. Click on a topic in the sidebar to navigate to the page for that section of the book.

If you are simply looking for the solution to a simple task, the easiest ways to find a specific recipe are to

• use the search button,
• scan the left-side bar for categories you are interested in,
• scan the Index of examples, and from there, click on the name of the recipe to view it.
• look up into the Word index lists concepts, crates (in lowercase), and Rust items (using their full path e.g. parking_lot::ReentrantMutex).
• consult the alphabetical and categorical crates indices.

How to use the recipes

Recipes are designed to give you instant access to working code, along with a full explanation of what it is doing, and to guide you to further information. All recipes are self-contained programs, so that they may be copied directly into your own projects for experimentation. To do so follow the instructions below.

Consider this example for "generate random numbers within a range":

use rand::Rng;
fn main() {
    let mut rng = rand::thread_rng();
    println!("Random f64: {}", rng.r#gen::<f64>());
}

To work with it locally we can run the following commands to create a new cargo project, and change to that directory:

cargo new my-example --bin
cd my-example

Now, we also need to add the necessary crates to Cargo.toml⮳, as indicated by the crate badges, in this case just "rand". To do so, we'll use the cargo add command.

cargo add rand

Next you can replace src/main.rs with the full contents of the example and run it:

cargo run

The crate badges that accompany the examples link to the crates' full documentation on docs.rs⮳, and is often the next documentation you should read after deciding which crate suites your purpose.

A note about error handling

Error handling in Rust is robust when done correctly, but can require a fair bit of boilerplate. Because of this, one often sees Rust examples filled with unwrap calls, instead of proper error handling.

Since this book's recipes are intended to be reused as-is and encourage best practices, they set up error handling correctly when there are Result types involved. The structure generally looks like:

use std::net::IpAddr;
use std::str;

use anyhow::Result;

fn main() -> Result<()> {
    let bytes = b"2001:db8::1";

    // Bytes to string.
    let s = str::from_utf8(bytes)?;

    // String to IP address.
    let addr: IpAddr = s.parse()?;

    println!("{:?}", addr);
    Ok(())
}

use anyhow::Result;
use url::Position;
use url::Url;

fn main() -> Result<()> {
    let parsed = Url::parse("https://httpbin.org/cookies/set?k2=v2&k1=v1")?;
    let cleaned: &str = &parsed[..Position::AfterPath];
    println!("cleaned: {}", cleaned);
    Ok(())
}

In most examples, we have chosen to use anyhow's Result as the return type of any fallible function, instead of writing std::result::Result<_, Box<dyn std::error::Error>> or using custom Result / Error types.

Within the code, we use the ? operator to easily propagate any error that implements the std::error::Error trait.

For more background on error handling in Rust, read this page⮳ of the Rust book.

Additional examples

The crates/xmpl folder in the book's GitHub repo contains additional examples that can't be embedded into the book, due to their length.

A note about crate representation

This book is intended to provide expansive coverage of "key" or "foundational" crates - those crates that make up the most common programming tasks, and that the rest of the ecosystem builds off of.

Key crates are identified by cross-referencing:

• blessed.rs⮳ and similar resources,
• most downloaded crates (overall and per category) in crates.io⮳,
• high-quality crates per lib.rs⮳ statistics⮳.

The selection process is necessarily opinionated. Feel free to offer suggestions (or submit a PR), if the author missed an important, widely used crate.

What other books should I consult?

Rust by Example⮳ is similar in concept - a collection of runnable examples - but not in scope, as it focuses solely on the Rust language and standard library.

Consult the links section and its books page for other recommendations.

Index of Examples

Algorithms

Randomness

Recipe	Crates	Categories
Generate random numbers
Generate random numbers within a range
Generate random numbers within a given distribution
Generate random values of a custom type
Create random passwords from a set of alphanumeric characters
Create random passwords from a set of user-defined characters

Sorting

Recipe	Crates	Categories
Sort a vector of integers
Sort a vector of floats
Sort a vector of structs

Asynchronous

Async

Recipe	Crates	Categories
Basic example
Differences with other languages
Which crate provides what?
Async runtimes

Async and Blocking

Recipe	Crates	Categories
Call blocking code from async code
Use spawn_blocking
Use the rayon crate
Spawn a dedicated thread
Call async code from blocking code
Use the futures executor
Use the Tokio runtime directly

Async Channels

Recipe	Crates	Categories
OneShot
Multiple Producer, Single Consumer

Async Traits

Recipe	Crates	Categories
Async traits

Futures

Recipe	Crates	Categories
Selecting futures
Joining futures
Map, then, either, flatten

Streams

Recipe	Crates	Categories
Streams

Tokio

Recipe	Crates	Categories
Basics
Join
Spawning
IO
Graceful shutdown

Authentication

Basic Authentication

Recipe	Crates	Categories
Perform a basic HTTP authentication

Command Line Interface

ANSI Terminal

Recipe	Crates	Categories
ANSI Terminal
Print colored text to the terminal
Print bold text to the terminal
Print bold and colored text to the terminal
Manipulate the cursor, style the output, handle input events

Arguments

Recipe	Crates	Categories
Using clap's builder API
Using clap's derive API
lexopt
pico-args

TUI

Recipe	Crates	Categories
Build complex TUI

User Interaction

Recipe	Crates	Categories
Ask for confirmation, selection, text input
Display progress bars and spinners

Command Line Utilities

Filesystem

Recipe	Crates	Categories
lsd
exa
broot
bat
open

Networking

Recipe	Crates	Categories
gping

Shells

Recipe	Crates	Categories
starship
nushell	nushell⮳

Compression

tar

Recipe	Crates	Categories
Compress a directory into a tarball
Decompress a tarball
Decompress a tarball while removing a prefix from the paths

Concurrency

Concurrent Data Structures

Recipe	Crates	Categories
Bounded multi-producer multi-consumer queue
dashmap
flurry

Crossbeam

Recipe	Crates	Categories
Spawn a short-lived thread
Create a parallel pipeline
Pass data between two threads

Data Parallelism

Recipe	Crates	Categories
rayon
Iterate in parallel
Sort in parallel
Implement custom parallel tasks
Mutate the elements of an array in parallel
Test in parallel if any or all elements of a collection match a given predicate
Search items using a given predicate in parallel
Sort a vector in parallel
Map-reduce in parallel
Generate JPEG thumbnails in parallel

Explicit Threads

Recipe	Crates	Categories
Use spawn, join		[]
Use scoped threads

Message Passing

Recipe	Crates	Categories
Multiple producers, single consumer
crossbeam-channel
flume
tokio

Send

Recipe	Crates	Categories
Send and Sync traits

Shared State

Recipe	Crates	Categories
Maintain a global mutable state
Mutexes
parking_lot
Atomics
arc-swap

Threadpool

Recipe	Crates	Categories
Calculate the SHA256 of ISO files concurrently
Draw a fractal, dispatching work to a thread pool

Config

Configuration

Recipe	Crates	Categories
config
confy

Environment Variables

Recipe	Crates	Categories
dotenvy
std::env
envy

Cryptography

Encryption

Recipe	Crates	Categories
Salt and hash a password with PBKDF2

Hashing

Recipe	Crates	Categories
Calculate the SHA-256 digest of a file
Sign and verify a message with a HMAC digest
Use general-purpose hashing algorithms
Encrypt with AEAD
Use the RSA algorithm
Compute digital signatures
Create certificates
Use TLS / SSL
Utilities

Data Structures

Bitfield

Recipe	Crates	Categories
Define and operate on a type represented as a bitfield
flagset

Maps

Recipe	Crates	Categories
Store data in an insertion-ordered map
Store data in a multimap
slotmap

Stack Allocated Arrays

Recipe	Crates	Categories
arrayvec
smallvec
tinyvec

UUID

Recipe	Crates	Categories
Generate and parse UUIDs

Database

Connection Pool

Recipe	Crates	Categories
Create a connection pool

NoSQL

Recipe	Crates	Categories
Connect to MongoDB
Connect to Redis

Postgres

Recipe	Crates	Categories
Create tables in a Postgres database
Insert and query data
Aggregate data
tokio-postgres
cornucopia for postgres	cornucopia-rs⮳

Query Builders Orms

Recipe	Crates	Categories
sqlx
diesel
SeaORM
toasty

Search

Recipe	Crates	Categories
Connect to Elasticsearch
infisearch
stork-search
minisearch
typesense
tinysearch

SQLite

Recipe	Crates	Categories
Create a SQLite database
Insert and select data
Using transactions

Date and Time

Duration

Recipe	Crates	Categories
Measure the elapsed time between two code sections
Perform checked date and time calculations
Convert a local time to another timezone

Parse

Recipe	Crates	Categories
Examine the date and time
Convert date to UNIX timestamp and vice versa
Display formatted date and time
Parse string into DateTime struct

Time

Recipe	Crates	Categories
Use the time crate

Cargo

Cargo

Recipe	Crates	Categories
Basic cargo usage
Cargo.toml and lock files

Crate Registries

Recipe	Crates	Categories
Crate registries	crates.io⮳

Package Layout

Recipe	Crates	Categories
Package layout

Documentation

Badges

Recipe	Crates	Categories
Badges	shield.io⮳

Documentation

Recipe	Crates	Categories
Document your code
Create module- or crate-level documentation

mdBook

Recipe	Crates	Categories
Write online books with mdBook
mdbook plugins
Deploy your book or documentation in a CD / CI pipeline	GitHub Actions for mdBook
Let readers execute your sample code in the Rust playground

Formatting

Formatting

Recipe	Crates	Categories
Format your Rust code with rustfmt
Configure rustfmt
Use attributes to skip code formatting in your code

Installation

Install

Recipe	Crates	Categories
Build and install a Rust binary with cargo install
Install a Rust binary with cargo binstall

Rustup

Recipe	Crates	Categories
Install and manage Rust toolchains with rustup

Other

Code Build

Recipe	Crates	Categories
Save and run project-specific commands with the just command runner
Check your Rust code in the background

Code Verification

Recipe	Crates	Categories
Verify your Rust code	{{hi:kani}}

miri

Recipe	Crates	Categories
Install the miri interpreter
Detect undefined behavior with the miri interpreter

Other

Recipe	Crates	Categories
Search for Rust APIs	roogle
Deploy your Rust code on shuttle.rs	shuttle.rs
Minimize Rust binary sizes	{{#crate }}
Generate Rust code	{{#crate }}

Versioning

Versioning

Recipe	Crates	Categories
Parse and increment a version string
Parse a complex version string
Check if a given version is pre-release
Find the latest version satisfying a given range
Check external command version for compatibility

Development Tools: Build Utils

Build Utils

Recipe	Crates	Categories
Compile and link statically to a bundled C library
Compile and link statically to a bundled C++ library
Compile a C library while setting custom defines

Development Tools: Cargo Plugins

Auditing

Recipe	Crates	Categories
Audit cargo.lock files for crates containing security vulnerabilities
Embded the exact crate versions in your Rust executable for auditability
List the license(s) of dependencies
cargo deny

Building

Recipe	Crates	Categories
cargo make
Use devx
Make Rust a better bash with xshell

Code Formatting Linting

Recipe	Crates	Categories
Format your code
Lint your code
Fix compiler warnings automatically
Format or lint your code before committing it

Cross Compiling

Recipe	Crates	Categories
Cross-compile using zig as the linker

Maintaining

Recipe	Crates	Categories
Edit Cargo.toml
Find unused dependencies
Detect dependencies that are out of date
Lint your crate API changes for semver violations
Manage the cargo cache

Performance

Recipe	Crates	Categories
Configure your cargo project for maximum performance, fast compile times or minimal binary size
cargo hakari

Watching For Changes

Recipe	Crates	Categories
cargo watch
cargo limit

Writing

Recipe	Crates	Categories
Generate a Rust project from a template
Quickly open the crates.io or docs.rs page for the latest version of a crate

Development Tools: Debugging

Alternatives

Recipe	Crates	Categories
log
slog
log4rs
env_logger
OpenTelemetry	OpenTelemetry Rust documentation⮳
OpenObserve	OpenObserve⮳

Config Log

Recipe	Crates	Categories
Enable log levels per module
Use a custom environment variable to set up logging
Include a timestamp in log messages
Log messages to a custom location

Diagnostic Functions

Recipe	Crates	Categories
Get the type name of the pointed-to value

Log

Recipe	Crates	Categories
Log a debug message to the console
Log an error message to the console
Log to stdout instead of stderr
Log messages with a custom logger
Log to the Unix syslog

Tracing

Recipe	Crates	Categories
Initialize the logger
Enable basic tracing
Combine layers
Configure a custom event formatter
Events
Spans
Add tracing spans to functions
See also

Encoding

Binary Encoders

Recipe	Crates	Categories
bincode
CBOR with ciborium
prost
protobuf
MessagePack with rmp-serde

Complex

Recipe	Crates	Categories
Serialize and deserialize unstructured JSON
Deserialize a TOML configuration file
Read and write integers in little-endian byte order

CSV

Recipe	Crates	Categories
Read CSV records
Read CSV records with different delimiter
Filter CSV records matching a predicate
Handle invalid CSV data with serde
Serialize records to CSV
Serialize records to CSV using serde
Transform a CSV column

Serde

Recipe	Crates	Categories
Serialize JSON
monostate
serde-ignored

Strings

Recipe	Crates	Categories
Percent-encode a string
Encode a string as application/x-www-form-urlencoded
Encode and decode hexadecimal
Encode and decode base64

Typecasts

Recipe	Crates	Categories
bytemuck
zerocopy

Filesystem

cwd

Recipe	Crates	Categories
Get the current working directory

Dir

Recipe	Crates	Categories
Find files that have been modified in the last 24 hours
Find loops for a given path
Recursively find duplicate file names
Recursively find all files with a given predicate
Traverse directories while skipping dotfiles
Recursively calculate file sizes at a given depth
Find all files with a given extension recursively
Find all files with given pattern, ignoring filename case

File Watching

Recipe	Crates	Categories
Watch files or directories and execute a function when they change

Ignore

Recipe	Crates	Categories
Walk the filesystem while respecting ignore files

Read-Write

Recipe	Crates	Categories
Read lines of strings from a file
Avoid writing and reading from the same file
Access a file randomly using a memory map

Tempfile

Recipe	Crates	Categories
Create temporary files or temporary directories

User Directories

Recipe	Crates	Categories
dirs
directories

Hardware Support

Processor

Recipe	Crates	Categories
Check the number of logical cpu cores

Mathematics

Additional Numeric Types

Recipe	Crates	Categories
Abstract over different number types
Use big integers
Use big decimals
Sort floats

Complex Numbers

Recipe	Crates	Categories
Create complex numbers
Add complex numbers
Use mathematical functions on complex numbers

Linear Algebra

Recipe	Crates	Categories
Calculate vector norms
Add matrices
Multiply matrices
Multiply a scalar with a vector and a matrix
Invert a matrix
Compare vectors
(De)serialize a matrix

Statistics

Recipe	Crates	Categories
Calculate measures of central tendency
Compute the standard deviation

Trigonometry

Recipe	Crates	Categories
Calculate the side length of a triangle
Verify that tan is equal to sin divided by cos
Calculate the distance between two points on Earth

Memory Management

Global Static

Recipe	Crates	Categories
Declare lazily evaluated constants

Lazy Initialization

Recipe	Crates	Categories
std
once_cell
lazy_static

OS

External

Recipe	Crates	Categories
Read an environment variable
Run an external command and process its stdout
Run an external command, passing it stdin, then check for an error code
Run piped external commands
Redirect both the stdout and stderr of a child process to the same file
Continuously process the outputs of a child process
Run child processes using duct

Low Level System Calls

Recipe	Crates	Categories
Call libc, the C standard library

Rust OS

Recipe	Crates	Categories
Host containers with bottlerocket
Run a Rust operating system on your computer with Redox

Rust Patterns

Builder Pattern

Recipe	Crates	Categories
bon
derive_builder
typed-builder

Design Patterns

Recipe	Crates	Categories
Implement an abstract factory	{{#crate }}
Clone a struct storing a boxed trait object

Error Customization

Recipe	Crates	Categories
anyhow
thisError
miette
color-eyre

Error Handling

Recipe	Crates	Categories
Trigger and handle irrecoverable panics
Provide a fallback value with unwrap_or_else
Return recoverable errors with Result
Propagate errors with the ? operator
Avoid discarding errors during error conversions
Obtain the backtrace in complex error scenarios
Handle errors correctly in main

Functional Programming

Recipe	Crates	Categories
Compose iterators

Rust Idioms

Recipe	Crates	Categories
Rust idioms and patterns	{{#crate }}

Template Engine

Tera

Recipe	Crates	Categories
Create HTML files from a template

Tinytemplate

Recipe	Crates	Categories
Create Markdown fragments from a template

Text Editors

IDEs

Recipe	Crates	Categories
Write Rust code with VS Code	VS Code⮳
Write Rust code with the zed editor

Text Processing

Regex

Recipe	Crates	Categories
Verify and extract login from an email address
Extract a list of unique #hashtags from a text
Extract phone numbers from text
Filter a log file by matching multiple regular expressions
Replace all occurrences of one text pattern with another pattern
Longer regex example

Regex2

Recipe	Crates	Categories
Longer Regex Example

String Concat

Recipe	Crates	Categories
Compare string concatenation methods

String Parsing

Recipe	Crates	Categories
Collect unicode graphemes
Implement the FromStr trait for a custom struct

Web Programming

Mime

Recipe	Crates	Categories
Get a MIME type from a string
Get a MIME type from a filename
Parse the MIME type of a HTTP response

Scraping

Recipe	Crates	Categories
Extract all links from the HTML of a webpage
Check a webpage for broken links
Extract all unique links from a MediaWiki markup

Url

Recipe	Crates	Categories
Parse a URL from a string to a Url type
Create a base URL by removing path segments
Create new URLs from a base URL
Extract the URL origin (scheme / host / port)
Remove fragment identifiers and query pairs from a URL

Web Programming: HTTP Client

APIs

Recipe	Crates	Categories
Query the GitHub API
Check if an API resource exists
Create and delete a Gist with the GitHub API
Consume a paginated RESTful API
Handle a rate-limited API

Download

Recipe	Crates	Categories
Download a file to a temporary directory
Make a partial download with HTTP range headers
POST a file to paste.rs

HTTP Clients

Recipe	Crates	Categories
reqwest
ureq
hyper

Requests

Recipe	Crates	Categories
Make a HTTP GET request
Make a HTTP GET request asynchronously
Set custom headers and URL parameters for a REST request

Web Programming: HTTP Server

actix

Recipe	Crates	Categories
Create a web server with Actix Web

axum

Recipe	Crates	Categories
Create a web server with axum

Batteries-Included Frameworks

Recipe	Crates	Categories
loco
Rust on Nails	Rust on Nails⮳

CORS

Recipe	Crates	Categories
Implement CORS

GraphQL

Recipe	Crates	Categories
Create a GraphQL endpoint

gRPC

Recipe	Crates	Categories
Implement gRPC

hyper

Recipe	Crates	Categories
Implement an HTTP API with hyper

Middleware

Recipe	Crates	Categories
tower
tower-http
Investigate alternatives to tower

Other Frameworks

Recipe	Crates	Categories
Implement a HTTP server using rocket
leptos

Static Website Generators

Recipe	Crates	Categories
Create a simple website using a static website generator

Contributing

API Documentation

Development Editing

Dev Container Docker

Dev Environment Setup

Optional Preprocessors

Publication

Repo Structure

Topics of Interest

Crates

Language

Attributes

Closures

Control Flow

Enums

Functions

Generics

Iterators

Lifetimes

Macros

Main

Match

Modules

Ownership Borrowing

Rust Install

Simple Data Types

Slices

Structs

Traits

Trait Objects

Variables and Constants

Links

Blogs Podcasts Meetups

Books

Companies

Example Code

Learning

Links

Rust Cheatsheets

Standard Library

AsRef

Recipe	Crates
AsRef and &T

Cow

Recipe	Crates
Convert Cow to &str
Convert Cow to String

Derive

Recipe	Crates
Automatically implement common traits using the derive attribute
Derive More

Hashmaps

Recipe	Crates
Hashmaps

Option

Recipe	Crates
Option
Use adapters when working with references
Extract the value contained in Option
Use combinators

Result

Recipe	Crates
Result

Smart Pointers

Recipe	Crates
Box
Rc
RefCell

Strings

Recipe	Crates
String
Placeholders
Concatenate strings

Vectors

Recipe	Crates
Vec

Rust language

Rust is a modern programming language that offers high performance, reliability, and productivity. It is designed to prevent common errors such as memory leaks, data races, and null pointer dereferences, by enforcing strict rules at compile time. Rust also supports powerful features such as generics, traits, macros, and concurrency, making it suitable for a wide range of applications.

Rust prefers snake case for variables and functions, so a method would be called read_str instead of readStr. For structs, traits and enums, camel case (or Pascal case) is used, for example HttpClient.

Rust Installation

Install Rust⮳

Install Rust and create a first project

• Install Rustup⮳

On WSL / Unix:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

• Check whether you have Rust installed correctly

rustc --version
cargo --version

• Open the documentation, if needed

rustup doc

• Create a new project

cargo new hello_world
cd hello_world
code . # open VS Code (or your favorite editor) and edit the code as you wish

• Build / run the code.

cargo check # check if the code can compile
cargo build # compile
cargo run # run the executable

cargo run builds the code if cargo build has not been invoked before or the code has changed.

Main function

use std::fs::File;
use std::io::Read;

use anyhow::Result;
use anyhow::anyhow;

fn read_uptime() -> Result<u64> {
    let mut uptime = String::new();
    File::open("/proc/uptime")?.read_to_string(&mut uptime)?;

    Ok(uptime
        .split('.')
        .next()
        .ok_or(anyhow!("Cannot parse uptime data"))?
        .parse()?)
}

fn main() {
    match read_uptime() {
        Ok(uptime) => println!("uptime: {} seconds", uptime),
        Err(err) => eprintln!("error: {}", err),
    };
}

Async main function

use anyhow::Result;

#[tokio::main]
async fn main() -> Result<()> {
    println!("I'm async!");
    Ok(())
}

Simple data types

• Integers: i8⮳, i16⮳, i32⮳, i64⮳, i128⮳, isize⮳
• Unsigned: u8⮳, u16⮳, u32⮳, u128⮳, usize⮳
  • usize⮳ and isize⮳ are 32 or 64 bits, depending on the architecture of the computer.
• Floating point: f32⮳, f64⮳
• Boolean: bool⮳: true, false
• Char: let z: char = 'ℤ'; Unicode
• Tuples: let tup: (i32, f64, u8) = (500, 6.4, 1);
  • Access via let five_hundred = x.0;
  • Destructuring via let (x, y, z) = tup;
• Arrays: let a: [i32; 5] = [1, 2, 3, 4, 5]; allocated on the stack. access via let first = a[0];
  • A vector is a similar collection type provided by the standard library that is allowed to grow or shrink in size
• Unit (aka void): ()
• Type aliases: type Kilometers = i32;

Handle overflows

• Wrap in all modes with the wrapping_* methods, such as wrapping_add⮳.
• Return the std::option::Option::None⮳ value if there is overflow with the checked_* methods.
• Return the value and a boolean indicating whether there was overflow with the overflowing_* methods.
• Saturate at the value’s minimum or maximum values with the saturating_* methods.

Variables and Constants

fn main() {
    // `const` is set to a constant expression
    // The type must be annotated
    const THREE_HOURS_IN_SECONDS: u32 = 60 * 60 * 3;
    // ERROR: THREE_HOURS_IN_SECONDS = 10800;

    // Immutable variable
    let apples = 5;
    // ERROR: apples = 6;
    println!("apples: {}", apples);

    // Mutable variable
    let mut guess = String::new();
    guess.push_str("42");
    println!("guess: {}", guess);
}

Shadowing

fn main() {
    // `x` is an immutable variable
    let x = 5;
    // ERROR: x = x +1;

    // But it can be redefined:
    let x = x + 1;
    println!("{x}");

    // The type can change
    let x = "example";
    println!("{x}");
}

Destructuring

fn main() {
    // Destructuring a tuple
    let (x, y, _) = (1, 2, 3);
    // x, y are now stored individually in two separate `i32` variables
    // Use _ to ignore a field you don't care about.
    println!("x: {x}, y: {y}");

    struct Point {
        x: i32,
        y: i32,
    }

    let p = Point { x: 0, y: 7 };
    // Destructuring a struct - sets a = 0 and b = 7:
    let Point { x: a, y: b } = p;
    println!("a: {a}, b: {b}");

    // Here is a simpler way:
    let Point { x, y } = p;
    // This is equivalent to `let Point { x: x, y: y } = p;``
    print!("x and y: {:?}", (x, y));
    // An underscore can be used as well, if needed.
}

Starting the name of a variable with an underscore silences unused variable warnings.

Ownership and Borrowing

Ownership

• No garbage collector. Ownership instead.
• Each value in Rust has an owner.
• There can only be one owner at a time.

fn main() {
    // Strings have move semantics.
    let s1 = String::from("hello");
    // s1 is MOVED into s2 - this is NOT a shallow copy
    let s2 = s1;
    println!("{}, world!", s2);
    // ...but Rust has invalidated s1
    // ERROR: println!("{}, world!", s1);
}

When the owner goes out of scope, the value will be dropped.

fn main() {
    {
        let s = String::from("hello");
        println!("{}", s);
    } // The `s` variable is now out of scope - Rust calls `drop`

    // ERROR println!("{}", s);
}

Rust will never automatically create “deep” copies of your data. Use std::clone::Clone⮳

fn main() {
    let s1 = String::from("hello");
    let s2 = s1.clone();
    // `clone` deeply copies the heap data of the `String`,
    // not just the stack data.
    println!("{s2}");
}

If a type implements the std::marker::Copy⮳ trait (stack-only, fixed-size values, like integers, floats, and tuples thereof), variables that use it do not move, but rather are trivially copied, making them still valid after assignment to another variable.

fn main() {
    let x = 5; // Integer
    let y = x; // No MOVE

    println!("x = {}, y = {}", x, y); // OK
}

Borrowing

Passing a variable to a function will move or copy, just as assignment does. To avoid passing a value along, borrow the value:

fn main() {
    let s1 = String::from("hello");

    let _len = calculate_length(&s1); // `&s1` passes an immutable reference to `s1`

    fn calculate_length(s: &str) -> usize {
        s.len()
    } // Here, `s` goes out of scope. Because the function does not have
    // ownership of what it refers to, `s1` is not dropped.

    println!("{s1}");
}

Mutable references

// Note the `&mut` in the function's signature.
fn change(some_string: &mut String) {
    some_string.push_str(", world");
    println!("{some_string}");
}

fn main() {
    let mut s = String::from("hello"); // note the `mut`
    change(&mut s);
}

If you have a mutable reference to a value, you can have no other simultaneous references to that value! Functions like a read/write lock.

Slices

Slices

fn main() {
    let s = String::from("hello world");

    let hello: &str = &s[0..5]; // or &s[..5];
    let world = &s[6..11]; // or &s[6..];

    println!("{}", hello);
    println!("{}", world);
}

Functions

fn foo(x: i32, unit_label: char) -> i32 {
    let y = {
        let z = 3;
        x + z // Expression at the end of a block - no semi-colon
    };

    println!("The value of y is: {y}{unit_label}");
    y // Returns y - no semi-colon
}

fn main() {
    println!("{}", foo(1, 'm'));
}

The unit type () (void in some languages) is the default return type when no type is given for a function. It could be omitted: fn log(message: &str) { ... }

Generic functions

fn generic<T>(_t: T) {
    println!("In `generic`");
}

// Explicitly specified type parameter `char` to `generic()`.
// Note the turbofish notation ::<>

fn main() {
    generic::<char>('a');
}

use std::fmt::Display;

fn generic<T: ?Sized + Display>(t: &T) {
    // By default, generic functions will work only on types that have a
    // known size at compile time. Use `?Sized` to relax that rule.
    // `t` must be some kind of (smart) pointer: &, `Rc`, `Box`...
    println!("{}", t);
}

fn main() {
    let s = String::from("hello");
    generic(&s[..]);
}

Function pointers

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

fn do_twice(f: fn(i32) -> i32, arg: i32) -> i32 {
    // function pointer
    f(arg) + f(arg)
}

fn main() {
    println!("{}", do_twice(add_one, 1));
}

Diverging functions

Diverging functions never return.

fn foo() -> ! {
    // ! is the Never type
    panic!("This call never returns.");
}

fn main() {
    println!("Will panic");
    foo();
}

Control flow

If else

fn main() {
    let number = 3;
    let result: u8 = if number < 5 {
        println!("Condition was true");
        5 // `if` is an expression
    } else {
        println!("Condition was false");
        6
    };
    println!("{}", result);
}

Also else if <cond> { ... }

Loop

fn main() {
    let mut counter = 0;

    let result = loop {
        counter += 1;

        if counter == 10 {
            break counter * 2;
            // `continue` and loop labels also exist:
            // https://doc.rust-lang.org/book/ch03-05-control-flow.html
        }
    };
    println!("{}", result);
}

While

fn main() {
    let mut number = 5;
    while number != 0 {
        println!("{number}!");
        number -= 1;
    }
}

For

fn main() {
    let a = [10, 20, 30, 40, 50];

    for element in a {
        println!("the value is: {element}");
    }

    // Range - generates all numbers in sequence
    // starting from one number and ending before another number.
    for number in (1..4).rev() {
        // reverse enumeration
        println!("{number}!");
    }
}

Structs

// We first define the struct's fields (which can be of any type).
// The `derive` attribute is not required - it just enables `println!` below.
#[derive(Debug)]
struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {
    // We create an instance of the struct.
    // Note that there is no `new` or similar.
    let user1 = User {
        active: true,
        username: String::from("someusername123"),
        email: String::from("someone@example.com"),
        sign_in_count: 1,
    };
    println!("{:?}", user1);
}

Struct fields follow the general rule of everything being private by default unless annotated with pub⮳.

#[derive(Debug)]
struct User {
    active: bool,
    username: String,
    email: String,
}

// It is common to define a function (or an associated function, see below) that
// initializes the struct:
fn build_user(email: String, username: String) -> User {
    User {
        active: true,
        username, /* Field init shorthand, instead of writing `username:
                   * username` */
        email, // Same
    }
}

fn main() {
    // We create an instance of the struct:
    let user1: User = build_user("user@example.com".into(), "user".to_string());

    // Then update the struct.
    // .. is used to fill in the rest
    let user2 = User {
        email: String::from("another@example.com"),
        ..user1 /* The remaining fields not explicitly set will have the
                 * same value as the fields in the given instance. */
    };
    println!("{:?}", user2);
}

// A tuple struct
// Note the ( ) and the lack of field names.
#[derive(Debug)]
struct Color(i32, i32, i32);

// A unit-like struct
#[derive(Debug)]
struct AlwaysEqual; // Note that there are no fields

fn main() {
    let black = Color(0, 0, 0);
    println!("{black:?}");
    let s = AlwaysEqual;
    println!("{s:?}");
}

struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    // implementation block (multiple allowed for a given struct)
    // Method
    fn area(&self) -> u32 {
        // short for self: &Self, an alias for the type that the impl block is
        // for
        self.width * self.height
    }

    // Associated Functions - NO self, &self, or &mut self
    // often use for constructors: SomeType::new(...)
    fn square(size: u32) -> Self {
        Self {
            width: size,
            height: size,
        }
    }
}

fn main() {
    let sq = Rectangle::square(5);
    println!("Area: {}", sq.area());
}

Enums

#[derive(Debug)]
enum Message {
    Quit,                       // Unit-like variant (no fields)
    Move { x: i32, y: i32 },    // Struct-like variant (named fields)
    Write(String),              // Tuple-like variant (numbered fields)
    ChangeColor(i32, i32, i32), // Another tuple-like variant
}

// Define methods on enums.
impl Message {
    fn call(&self) {
        // method body would be defined here
    }
}

fn main() {
    // `msg` is assigned one of the variants.
    // Note the :: between the name of the type and the name of the variant.
    let msg = Message::Quit;
    println!("{msg:?}");
    // or
    let msg = Message::Move { x: 10, y: 15 };
    println!("{msg:?}");
    // or
    let msg = Message::ChangeColor(127, 0, 0);
    println!("{msg:?}");
}

If we make an enum public, all of its variants are then public. We only need pub⮳ before the enum⮳ keyword.

Traits

pub trait Summary {
    fn summarize(&self) -> String;
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

// Implement Trait on a Type
impl Summary for NewsArticle {
    fn summarize(&self) -> String {
        format!("{}, by {} ({})", self.headline, self.author, self.location)
    }
}

fn main() {
    let na = NewsArticle {
        headline: "headline".to_string(),
        location: "location".to_string(),
        author: "author".to_string(),
        content: "...".to_string(),
    };
    println!("Summary: {}", na.summarize());
}

Trait methods are in scope only when their trait is.

Default implementation

trait Summary {
    fn summarize_author(&self) -> String;

    // Default implementation
    fn summarize(&self) -> String {
        format!("(Read more from {}...)", self.summarize_author())
        // The default implementation can call a non-default
        // (abstract) method
    }
}

struct Blog {
    author: String,
}

impl Summary for Blog {
    fn summarize_author(&self) -> String {
        self.author.clone()
    }
}

fn main() {
    let blog = Blog {
        author: "ferris".into(),
    };
    println!("{}", blog.summarize());
}

Supertraits

use std::fmt;

trait OutlinePrint: fmt::Display {
    fn outline_print(&self) {
        println!("* {} *", self);
        // We can use `println!` here,
        // because `self` is guaranteed to implement `Display`
    }
}

// String implements Display. That would not work otherwise.
impl OutlinePrint for String {}

fn main() {
    String::from("test").outline_print();
}

"Newtype" pattern

Unlike interfaces in languages like Java, C# or Scala, new traits can be implemented for existing types.

trait MyHash {
    fn myhash(&self) -> u64;
}

impl MyHash for i64 {
    fn myhash(&self) -> u64 {
        *self as u64
    }
}

fn main() {
    let x = 1i64;
    println!("{}", x.myhash());
}

One restriction to note is that we can implement a trait on a type only if at least one of the trait or the type is local to our crate. If neither are, use the newtype pattern:

use std::fmt;

// Tuple struct wrapping the type we want to add a non-local trait to.
struct Wrapper(Vec<String>);

impl fmt::Display for Wrapper {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "[{}]", self.0.join(", "))
    }
}
// If you want the new type to have every method the inner type has,
// implement the `Deref` trait instead.

fn main() {
    println!(
        "{}",
        Wrapper(vec!["example".to_string(), "example 2".to_string()])
    );
}

Traits as parameters

// Accepts any type that implements the specified trait:
fn notify(item: &impl Summary) {
    println!("Breaking news! {}", item.summarize());
}

// Trait bound syntax (mostly equivalent):
fn notify2<T: Summary>(item: &T) {
    println!("Breaking news! {}", item.summarize());
}

trait Summary {
    fn summarize(&self) -> String;
}

struct Article {
    txt: String,
}

impl Summary for Article {
    fn summarize(&self) -> String {
        self.txt.clone()
    }
}

fn main() {
    let a = Article {
        txt: String::from("Some text"),
    };
    notify(&a);
    notify2(&a);
}

Multiple traits

use std::clone::Clone;
use std::fmt::Debug;

// Note the `+`
fn a_function(item: &(impl Debug + Clone)) {
    println!("{:?}", item.clone());
}

fn some_function<T, U>(_t: &T, _u: &U) -> i32
where
    T: Debug + Clone, // Note the `+`
    U: Debug + Clone,
{
    42
}

#[derive(Debug, Clone)]
struct S;

fn main() {
    let s = S;
    a_function(&s);
}

Return-position impl Trait

fn returns_closure() -> impl Fn(i32) -> i32 {
    |x| x + 1
}

fn main() {
    let f = returns_closure();
    println!("{}", f(1));
}

Generic traits

trait Test<T> {
    fn test(_t: T);
}

struct SomeStruct;

// Note the <> in two places:
impl<T> Test<T> for SomeStruct {
    fn test(_t: T) {
        println!("test");
    }
}

fn main() {
    SomeStruct::test(1);
    SomeStruct::test(true);
}

Associated types

trait Iterator {
    type Item; // <-- associated type

    // Note the use of :: to refer to the associated type
    fn next(&mut self) -> Option<Self::Item>;
}

struct MyIterator(u32);

// We implement the trait for a given struct
impl Iterator for MyIterator {
    // ...and define what associated type should be used here
    type Item = u32;

    fn next(&mut self) -> Option<Self::Item> {
        Some(self.0)
    }
}

fn use_iterator(it: &mut impl Iterator<Item = u32>) -> Option<u32> {
    it.next()
}

// A common pattern is a generic type (with a default) and an associated type:
trait Add<Rhs = Self> {
    type Output; // <-- associated type

    fn add(self, rhs: Rhs) -> Self::Output;
}

fn main() {
    let mut it = MyIterator(42);
    println!("{:?}", use_iterator(&mut it));
}

Trait bounds

use std::collections::hash_map::DefaultHasher;
use std::hash::Hash;
use std::hash::Hasher;

// Trait bounds: the `print_hash` function is generic over an unknown
// type `T`, but requires that `T` implements the `Hash` trait.
fn print_hash<T: Hash>(t: &T) {
    let mut hasher = DefaultHasher::new();
    t.hash(&mut hasher);
    println!("The hash is {:x}", hasher.finish());
}
struct Pair<A, B> {
    first: A,
    second: B,
}

// Generics make it possible to implement a trait conditionally.
// Here, the Pair type implements Hash if, and only if,
// its components do.
impl<A: Hash, B: Hash> Hash for Pair<A, B> {
    fn hash<H: Hasher>(&self, state: &mut H) {
        self.first.hash(state);
        self.second.hash(state);
    }
}

fn main() {
    let p = Pair {
        first: 1,
        second: "2",
    };
    print_hash(&p);
}

Constants in traits

trait Example {
    const CONST_NO_DEFAULT: i32;
    const CONST_WITH_DEFAULT: i32 = 99;
}
struct S;

impl Example for S {
    const CONST_NO_DEFAULT: i32 = 0;
}

fn main() {
    println!("{} {}", S::CONST_NO_DEFAULT, S::CONST_WITH_DEFAULT);
}

Async and traits

See Async⮳

See also

Traits (blog)⮳

Trait objects

In Rust, traits are types, but they are "unsized", which roughly means that they are only allowed to show up behind a pointer like std::boxed::Box⮳ (which points onto the heap) or & (which can point anywhere).

A type like &dyn ClickCallback or Box<dyn ClickCallback> where ClickCallback is a Trait, is called a "trait object", and includes a pointer to an instance of a type T implementing ClickCallback, and a 'vtable': a pointer to T's implementation of each method in the trait.

trait Draw {
    fn draw(&self);
}

struct Button;

impl Draw for Button {
    fn draw(&self) {
        println!("Button");
    }
}

struct Text;

impl Draw for Text {
    fn draw(&self) {
        println!("Text");
    }
}

struct Screen {
    components: Vec<Box<dyn Draw>>, // <-- trait object
}

impl Screen {
    fn new() -> Self {
        Screen {
            components: vec![Box::new(Button), Box::new(Text), Box::new(Text)],
        }
    }

    fn run(&self) {
        for component in self.components.iter() {
            // The purpose of trait objects is to permit "late binding" of
            // methods. Calling a method on a trait object results
            // in virtual dispatch at runtime. Here, `components` is
            // a mix of `Button` and `Text` structs.
            component.draw();
        }
    }
}

fn main() {
    let s = Screen::new();
    s.run();
}

The set of traits after dyn can be made up of an object-safe⮳ base trait plus any number of autotraits (one of std::marker::Send⮳, std::marker::Sync⮳, std::marker::Unpin⮳, std::panic::UnwindSafe⮳, and std::panic::RefUnwindSafe⮳ - see special traits⮳).

dyn Trait
dyn Trait + Send
dyn Trait + Send + Sync
dyn Trait + 'static

See also

Trait Objects (docs)⮳

Attributes

Attributes

Attributes can take arguments with different syntaxes:

#[attribute = "value"]
#[attribute(key = "value")]
#[attribute(value)]
#[attribute(value, value2)]

Inner attributes #![attr] apply to the item that the attribute is declared within.

Lint attributes

During early development, place the following attributes at the top of main.rs or lib.rs

#![allow(unused_variables)]
#![allow(unused_mut)]
#![allow(unused_imports)]
#![allow(unused_must_use)]
// or simply: #![allow(unused)]
#![allow(dead_code)]
#![allow(missing_docs)]

// This import is not used anywhere
use std::thread;

// This struct is public but is not documented
pub struct S;

#[must_use]
fn required() -> u32 {
    42
}

// Nothing calls this function
fn dead_code() {}

fn main() {
    // This variable is not used
    let x = 1;
    // This mutable variable is not used
    let mut m = 2;
    // The return value of this function is not used
    required();
    println!("Done!");
}

For production-ready code, replace the above by the following, for example.

//! Crate documentation goes here.
#![warn(unused, missing_debug_implementations, missing_docs, rust_2018_idioms)]
// You may also add `missing_copy_implementations` if desirable.
// It detects potentially-forgotten implementations of Copy for public types.

// `deny` creates an error in case of violation
#![deny(unreachable_pub)]
// Prohibit unsafe blocks / functions
// `forbid` is the same as `deny`, but also forbids changing the lint level
// afterwards
#![forbid(unsafe_code)]

// WARNING: fn dead_code() {}

// ERROR: unsafe fn unsafe_func() {}

// ERROR
// fn unsafe_block() {
//     unsafe {
//     }
// }

/// This is the required documentation for S
/// We had to derive Debug to avoid a warning
#[derive(Debug)]
pub(crate) struct S;

/// Here is the required documentation
/// for the main function.
fn main() {
    let s = S;
    println!("{:?}", s);
}

You also apply these attributes to specific functions:

// Disables the `dead_code` lint
#[allow(dead_code)]
fn unused_function() {}

fn main() {
    println!("Nobody is calling `unused_function`.");
}

List of lint checks: rustc -W help. rustc⮳ also recognizes the tool lints for "clippy" and "rustdoc" e.g. #![warn(clippy::pedantic)]

Automatically derive common traits

See Automatic derivation.

Mark as must use

// Must use the results of the fn
// Also applies to traits, structs, enums...
#[must_use]
fn add(a: i32, b: i32) -> i32 {
    a + b
}

fn main() {
    println!("{}", add(1, 2));
}

Mark as deprecated

#![allow(deprecated)]

// Mark a function as deprecated
// That also works for structs, enums, etc...
#[deprecated(since = "5.2.0", note = "Use bar instead")]
pub fn foo() {
    println!("foo");
}

fn main() {
    // Use of a deprecated item
    foo();
    // Normally we would get a warning.
    // In this case, we used the module-wide #![allow(deprecated)] attribute
    // (first line above) to suppress it.
}

Compile conditionally

Conditional compilation⮳

// This function only gets compiled if the target OS is linux
#[cfg(target_os = "linux")]
fn are_you_on_linux() {
    println!("You are running Linux!");
}

// And this function only gets compiled if the target OS is *not*
// linux
#[cfg(not(target_os = "linux"))]
fn are_you_on_linux() {
    println!("You are *not* running Linux!");
}

fn main() {
    are_you_on_linux();

    println!("Are you sure?");
    if cfg!(target_os = "linux") {
        // alternative: use cfg!
        println!("Yes. It's definitely Linux!");
    } else {
        println!("Yes. It's definitely *not* Linux!");
    }
}

See also

Attributes reference⮳

Generics

Generic structs

use std::fmt::Display;

struct Point<T> {
    x: T,
    y: T,
}

impl<T> Point<T> {
    fn x(&self) -> &T {
        &self.x
    }
}

impl Point<f32> {
    // specify constraints on generic types
    fn distance_from_origin(&self) -> f32 {
        (self.x.powi(2) + self.y.powi(2)).sqrt()
    }
}

impl<T: Display + PartialOrd> Point<T> {
    // use Trait Bounds to Conditionally Implement Methods
    fn cmp_display(&self) {
        if self.x >= self.y {
            println!("The largest member is x = {}", self.x);
        } else {
            println!("The largest member is y = {}", self.y);
        }
    }
}

fn main() {
    let p = Point { x: 5, y: 10 };

    println!("p.x = {}", p.x());
}

Lifetimes

Prevent dangling references.

&i32 a reference &'a i32 a reference with an explicit lifetime &'a mut i32 a mutable reference with an explicit lifetime

// 'static indicates that the data pointed to by the reference lives
// for the _remaining_ lifetime of the running program. It can still
// be coerced to a shorter lifetime.
fn my_string() -> &'static str {
    let s: &'static str = "I have a static lifetime.";
    s
}

fn main() {
    println!("{}", my_string());
}

The generic lifetime 'a will get the concrete lifetime that is equal to the smaller of the lifetimes of x and y:

fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
    if x.len() > y.len() { x } else { y }
}

fn main() {
    let (x, y) = ("short", "looooooong");
    println!("{}", longest(x, y));
}

Lifetime Annotations in Struct Definitions and methods

struct ImportantExcerpt<'a> {
    part: &'a str,
}

impl ImportantExcerpt<'_> {
    fn level(&self) -> i32 {
        3
    }
}

fn main() {
    let ie = ImportantExcerpt { part: "a part" };
    println!("{}", ie.level());
}

Modules

Crates can contain modules.

Declaring modules: In the crate root file (main.rs or lib.rs), you can declare new modules; say, you declare a “garden” module with mod garden; (or pub mod garden; for public); The compiler will look for the module’s code in these places:

• Inline, within curly brackets that replace the semicolon following mod garden
• In the file src/garden.rs
• In the file src/garden/mod.rs (older style)

In any file other than the crate root, you can declare submodules. For example, you might declare mod vegetables; in ``src/garden.rs`. The compiler will look for the submodule’s code within the directory named for the parent module in these places:

• Inline, directly following mod vegetables, within curly brackets instead of the semicolon
• In the file src/garden/vegetables.rs
• In the file src/garden/vegetables/mod.rs (older style)

In Rust, all items (functions, methods, structs, enums, modules, and constants) are private to parent modules by default. Items can access other items in the same module, even when private.

Items in a parent module can’t use the private items inside child modules, but items in child modules can use the items in their ancestor modules.

A clear explanation of Rust’s module system⮳

use keyword

Create a shortcut to a path with the use⮳ keyword once, and then use the shorter name everywhere else in the scope.

// With the following, `File` without prefix is available in the scope
// For code from an external crate, the absolute path begins with the
// crate name - here, the standard `std` library
use std::collections::HashMap;
// Glob - all public objects in `collections` are now in scope
// Use sparingly
use std::collections::*;
// Use `as` to define aliases, for example in case of name conflict
use std::fmt::Result;
use std::fs::File;
use std::io::Result as IoResult;
// The following is equivalent to `use std::io; use std::io::Write;`
use std::io::{self, Write};
// You can combine multiple `use` lines together with { } as well
use std::{cmp::Ordering, fmt};

mod a {
    pub mod b {
        pub fn fn_in_b() {
            println!("in b!");
        }
    }
    pub struct A;
}
// For internal code, a relative path starts from the current module and uses
// `self`, or an identifier in the current module.
use self::a::b;
// b is now in scope

// Try the simpler version:
// use a::b;

fn do_something() {
    b::fn_in_b();
}

mod c {
    // We can construct relative paths that begin in the parent module,
    // rather than the current module or the crate root, by using `super`
    // at the start of the path.
    use super::a;
    // a is now in scope

    pub fn do_something_else() {
        let _a = a::A;
        println!("do_something_else");
    }
}

mod d {
    pub fn let_try_this() {}
}
// Absolute paths start with the literal `crate`.
// You can try:
// use crate::d;

mod e {
    pub mod f {
        pub fn try_that() {
            println!("try_that");
        }
    }
}
// `pub use` re-exports the `f` module from the
// root module, thus external code can use the path
// `<crate_name>::f::try_that()` instead of
// `<crate_name>::e::f::try_that()`.
pub use e::f;

fn main() {
    do_something();
    c::do_something_else();
    // You can of course access the item made public by `pub use` from your
    // module
    f::try_that();
}

Idiomatic - bringing the function’s parent module into scope, not the function itself:

// We bring the hosting module in scope...
use front_of_house::hosting;

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {
            println!("add_to_waitlist");
        }
    }
}

fn eat_at_restaurant() {
    // ...then we access the function within
    hosting::add_to_waitlist();
}

fn main() {
    eat_at_restaurant();
}

On the other hand, when bringing in structs, enums, and other items with use, it’s idiomatic to specify the full path.

// Bring `HashMap` in scope
use std::collections::HashMap;

fn main() {
    // We now refer to `HaspMap` without using its path
    let mut mymap: HashMap<u32, String> = HashMap::new();

    // Let's add something to it then print...
    mymap.entry(42).or_insert("my favorite number".into());
    println!("{:?}", mymap);
}

Match, if let, while let

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(String),
}

fn value_in_cents(coin: Coin) -> u8 {
    match coin {
        Coin::Penny => 1,
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter(state) => {
            // pattern binding to value
            println!("State quarter from {:?}!", state);
            25
        } // if needed, use catchall _ =>
    }
}

fn main() {
    println!("{}", value_in_cents(Coin::Penny));
}

// struct pattern matching
struct Point {
    x: i32,
    y: i32,
    z: i32,
}

fn main() {
    let origin = Point { x: 0, y: 0, z: 0 };

    match origin {
        // Ignoring all fields of a Point except for x by using ..
        Point { x, .. } => println!("x is {}", x),
    }
}

Patterns accept 1 | 2 for or, 1..=5 for inclusive range, if x % 2 == 0 guards, @-binding Message::Hello { id: id_variable @ 3..=7,}.

if let

fn main() {
    let config_max = Some(3u8);
    if let Some(max) = config_max {
        // <-- if let
        println!("The maximum is configured to be {}", max);
    }
}

while let

    let mut stack = Vec::new();

    stack.push(1);
    stack.push(2);
    stack.push(3);

    while let Some(top) = stack.pop() {
        // <-- while let
        println!("{}", top);
    }

See also

Pattern matching⮳

Closures

Closures

fn find_emails(list: Vec<String>) -> Vec<String> {
    list.into_iter()
        .filter(|s| s.contains('@')) // <-- closure
        .collect()
}

fn main() {
    for s in find_emails(vec![
        String::from("example"),
        String::from("example@example.com"),
    ]) {
        println!("{}", s);
    }
}

Closure with type annotations

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

fn main() {
    // closure can use type annotation. Multiple statements can be
    // enclosed in a block.
    let _expensive_closure = |num: u32| -> u32 {
        println!("Calculating slowly...");
        thread::sleep(Duration::from_secs(2));
        num
    };
}

Closures can capture variables

• by reference: &T
• by mutable reference: &mut T
• by value: T

They preferentially capture variables by reference and only go lower when required.

To force a move:

use std::thread;

fn main() {
    let list = vec![1, 2, 3];
    println!("Before defining closure: {:?}", list);

    // `move` forces the closure to take ownership of the values it uses.
    thread::spawn(move || println!("From thread: {:?}", list))
        .join()
        .unwrap();
}

Closures as input parameters

// A function which takes a closure as an argument and calls it.
// <F> denotes that F is a "Generic type parameter"
fn apply<F>(f: F)
where
    F: FnOnce(),
{
    // The closure takes no input and returns nothing.
    // could also be `Fn` or `FnMut`.
    f();
}

// A function which takes a closure and returns an `i32`.
fn apply_to_3<F>(f: F) -> i32
where
    // The closure takes an `i32` and returns an `i32`.
    F: Fn(i32) -> i32,
{
    f(3)
}

fn main() {
    apply(|| println!("Applied"));
}

• std::ops::Fn⮳: the closure uses the captured value by reference (&T)
• std::ops::FnMut⮳: the closure uses the captured value by mutable reference (&mut T)
• std::ops::FnOnce⮳: the closure uses the captured value by value (T)

Functions may also be used as arguments.

Iterators

fn main() {
    let vec1 = vec![1, 2, 3];
    let vec2 = vec![4, 5, 6];

    // `iter()` for vecs yields `&i32`. Destructure to `i32`. `iter()`
    // only borrows `vec1` and its elements, so they can be used again
    println!("2 in vec1: {}", vec1.iter().any(|&x| x == 2));
    // `into_iter()` for vecs yields `i32`. No destructuring required.
    // `into_iter()` does move `vec2` and its elements, so they cannot be
    // used again
    println!("2 in vec2: {}", vec2.into_iter().any(|x| x == 2));
}

See also

Iterators⮳

Macros

Rust reference - Macros⮳

Rust by example - Macros⮳

The Little Book of Rust Macros⮳

fn main() {
    // Macro used as an expression
    // Define a vector
    let _x = vec![1, 2, 3];

    // Macro used as a statement
    // Print the string
    println!("Hello!");

    // Macro definition
    macro_rules! pat {
        ($i:ident) => {
            Some($i)
        };
    }

    // Macro used in a pattern
    // Destructure an Option
    if let pat!(x) = Some(1) {
        assert_eq!(x, 1);
    }

    print_tuple((1, 3));
    use_thread_local();
}

macro_rules! Tuple {
    { $A:ty, $B:ty } => { ($A, $B) };
}

// Macro used in a type
// Define a tuple type
type T2 = Tuple!(i32, i32);

fn print_tuple(tupl: T2) {
    println!("{} {}", tupl.0, tupl.1);
}

fn use_thread_local() {
    use std::cell::RefCell;
    // Macro used as an item
    thread_local!(static FOO: RefCell<u32> = const { RefCell::new(1) });
}

macro_rules! const_maker {
    ($t:ty, $v:tt) => {
        const CONST: $t = $v;
    };
}

#[allow(dead_code)]
trait T {
    // Macro used as an associated item
    const_maker! {i32, 7}
}

// Macro calls within macros.
//
// When used, the outer macro `example` is expanded,
// then the inner macro `println` is expanded.
macro_rules! _example {
    () => {
        println!("Macro call in a macro!")
    };
}

Standard Library

Option

Recipe	Crates
Option
Use adapters when working with references
Extract the value contained in Option
Use combinators

Result

Recipe	Crates
Result

Vectors

Recipe	Crates
Vec

HashMap

Recipe	Crates
Hashmaps

Strings

Recipe	Crates
String
Placeholders
Concatenate strings

Copy-on-write

Recipe	Crates
Convert Cow to &str
Convert Cow to String

Smart Pointers

Recipe	Crates
Box
Rc
RefCell

Automatic Trait Derivation

Recipe	Crates
Automatically implement common traits using the derive attribute
Derive More

Asref

Recipe	Crates
AsRef and &T

Option

Recipe	Crates
Option
Use adapters when working with references
Extract the value contained in Option
Use combinators

Option

Rust has no null. Instead, use std::option::Option⮳:

enum Option<T> {
  None,
  Some(T),
}

Every std::option::Option⮳ is either std::option::Option::Some⮳ and contains a value, or std::option::Option::None⮳, and does not.

fn main() {
    let _some_number = Some(5);

    let absent_number: Option<i32> = None;
    println!("{:?}", absent_number);
}

It is often used with match⮳, if let, or while let:

fn bake_cake(sprinkles: Option<&str>) -> String {
    let mut cake = String::from("A delicious cake...");

    // Add required ingredients

    // Handle optional sprinkles
    if let Some(sprinkle_choice) = sprinkles {
        cake.push_str(
            format!(" with a sprinkle of {}", sprinkle_choice).as_str(),
        );
    } else {
        // sprinkles is None
        cake.push_str(" ready for your decorating touch!");
    }
    cake
}

fn main() {
    print!("{}", bake_cake(Some("rainbow nonpareils")));
}

Use adapters when working with references

• std::convert::AsRef⮳ converts from &Option<T> to Option<&T>
• std::convert::AsMut⮳ converts from &mut Option<T> to Option<&mut T>
• std::option::Option::as_deref⮳ converts from &Option<T> to Option<&T::Target>
• std::option::Option::as_deref_mut⮳ converts from &mut Option<T> to Option<&mut T::Target>

Extract the value contained in Option

These methods extract the contained value in an std::option::Option when it is the Some variant. If the std::option::Option⮳ is None:

• std::option::Option::expect⮳ panics with a provided custom message
• std::option::Option::unwrap⮳ panics with a generic message
• std::option::Option::unwrap_or⮳ returns the provided default value
• std::option::Option::unwrap_or_default⮳ returns the default value of the type T (which must implement the std::default::Default⮳ trait)
• std::option::Option::unwrap_or_else⮳ returns the result of evaluating the provided function

Use combinators

use std::fs;

fn read_file(filename: &str) -> Option<String> {
    fs::read_to_string(filename)
        // Convert `Result` to `Option`
        .ok()
        // `and_then` applies a function to the wrapped value if it's Some.
        .and_then(|contents| Some(contents.trim().to_string()))
}

fn main() -> anyhow::Result<()> {
    if !std::fs::exists("temp")? {
        std::fs::create_dir("temp")?;
    }
    fs::write("temp/poem.txt", b"Lorem ipsum")?;
    let contents = read_file("temp/poem.txt");

    // Using `match` to process the returned Option.
    match contents {
        Some(poem) => println!("{}", poem),
        None => println!("Error reading file"),
    }
    Ok(())
}

Result

Recipe	Crates
Result

Result

use std::fs::File;
use std::io;
use std::io::Read;
use std::num::ParseIntError;

// Result  is a type that represents either success (Ok) or failure (Err).
// pub enum Result<T, E> {
//     Ok(T),
//     Err(E),
// }

// Faillible functions like `File::open` return a `Result`...
fn open_file(file_path: &str) {
    let open_result: Result<File, io::Error> = File::open(file_path);
    // You could handle their `Result` there and then...
    match open_result {
        Err(e) => eprintln!("An error occurred while opening the file: {}", e),
        Ok(file) => println!("Opened {:?}", file),
    }
}

// ...but most often you'll want to return early when encountering an error,
// and propagate the error up the call stack.
#[allow(clippy::question_mark)]
fn read_file(file_path: &str) -> Result<String, io::Error> {
    let mut file = match File::open(file_path) {
        Ok(file) => file,
        Err(e) => return Err(e),
    };
    // This said, having to use multiple `match` or `if let` is verbose
    // when chaining calls to faillible methods...
    let mut contents = String::new();
    if let Err(e) = file.read_to_string(&mut contents) {
        Err(e)
    } else {
        Ok(contents)
    }
}

// Therefore, use the ? operator as a shortcut to return early
// in case of an error. The following is equivalent to the previous function.
fn read_file2(file_path: &str) -> Result<String, io::Error> {
    let mut file: File = File::open(file_path)?;
    // Note that file is of type `File`, not `io::Result<File> = Result<File,
    // io::Error>`
    let mut contents = String::new();
    file.read_to_string(&mut contents)?;
    Ok(contents)
}
// You can even chain method calls immediately after the ?, e.g.
// File::open(file_path)?.read_to_string(&mut contents)?;

// You will often need to return one of multiple Result types.
// You could create a custom error `enum` to do so:
fn read_and_parse_file(file_path: &str) -> Result<i32, MyError> {
    let mut file = File::open(file_path)?;
    let mut contents = String::new();
    file.read_to_string(&mut contents)?; // `read_to_string` returns `Result<_, io::Error>`
    let number = contents.trim().parse()?; // `parse` returns `Result<_, std::num::ParseIntError>`
    Ok(number)
}

#[allow(dead_code)]
#[derive(Debug)]
enum MyError {
    Io(io::Error),
    Parse(ParseIntError),
}

// That custom error type must implement the `From` trait.
impl From<io::Error> for MyError {
    fn from(err: io::Error) -> MyError {
        MyError::Io(err)
    }
}
impl From<ParseIntError> for MyError {
    fn from(err: ParseIntError) -> MyError {
        MyError::Parse(err)
    }
}

// The `thisError` crate provides a convenient derive macro
// for the standard library’s `std::error::Error` trait.
// Use when writing libraries.
#[allow(dead_code)]
#[derive(thiserror::Error, Debug)]
enum MyError2 {
    #[error("Io error")]
    Io(#[from] io::Error),
    #[error("Parse error")]
    Parse(#[from] ParseIntError),
}

// A simpler method than returning a custom error type
// may be to return a trait object (at the cost of opacity)...
fn read_and_parse_file2(
    file_path: &str,
) -> Result<i32, Box<dyn std::error::Error>> {
    let mut file = File::open(file_path)?;
    let mut contents = String::new();
    file.read_to_string(&mut contents)?;
    let number = contents.trim().parse()?;
    Ok(number)
}

// ...but crates like `anyhow` can simplify error management a great deal...
// `anyhow::Result<T>` is equivalent to `std::result::Result<T, anyhow::Error>`.
fn read_and_parse_file3(file_path: &str) -> anyhow::Result<i32> {
    let mut file = File::open(file_path)?;
    let mut contents = String::new();
    file.read_to_string(&mut contents)?;
    let number = contents.trim().parse()?;
    Ok(number)
}

// A function without return value in truth returns `Unit`:
// `fn func() {...}` is a shorthand for `fn func() -> () { ... }`
// To convert it to a faillible function, return `Result<(), SomeErrorType>`.
fn unit_return_value(file_path: &str) -> anyhow::Result<()> {
    let _i: i32 = read_and_parse_file3(file_path)?;
    println!("I don't return anything!");
    // Do not forget to return an Result in the happy path.
    // The double parentheses are required. It is `Ok( () )`.
    Ok(())
}

// `main()` can return a `Result`, more precisely a `Result<T, E> where T:
// Termination, E: Debug)`. `Result<(), Box<dyn std::error::Error>>`,
// `anyhow::Result<()>` are common choices.
fn main() -> Result<(), Box<dyn std::error::Error>> {
    let file_path = "example.txt";
    open_file(file_path);
    // Here we ignore the `Result` return values
    // to avoid returning early and exercise all the code.
    // You should rarely need to do this.
    let _ = read_file(file_path);
    let _ = read_file2(file_path);
    let _ = read_and_parse_file(file_path);
    let _ = read_and_parse_file2(file_path);
    let _ = read_and_parse_file3(file_path);
    let _ = unit_return_value(file_path);
    Ok(())
}

See also

• What is the Rust equivalent to a try catch statement⮳

Vectors

Recipe	Crates
Vec

Vec

Vectors can only store values that are the same type.

fn main() {
    let mut v: Vec<i32> = Vec::new();
    v.push(5);
    v.push(6);

    let mut v = vec![1, 2, 3]; // or vec!(1, 2, 3)

    let _third: &i32 = &v[2]; // read

    let _third: Option<&i32> = v.get(2);

    for i in &v {
        println!("{i}");
    }

    for i in &mut v {
        *i += 50; // dereference operator
    }
}

Hashmaps

Recipe	Crates
Hashmaps

All of the hashmap keys must have the same type as each other, and all of the values must have the same type.