Contains clickable links to The Book ^BK, Rust by Example ^EX, Std Docs ^STD, Nomicon ^NOM, Reference ^REF. Other symbols used: largely deprecated ^🗑️, has a minimum edition ^'18, is work in progress ^🚧, or bad ^🛑.

fn main() {
    println!("Hello, world!");
}

Data Structures

Data types and memory locations defined via keywords.

Creating and accessing data structures; and some more sigilic types.

References & Pointers

Granting access to un-owned memory. Also see section on Generics & Constraints.

Functions & Behavior

Define units of code and their abstractions.

Control Flow

Control execution within a function.

Organizing Code

Segment projects into smaller units and minimize dependencies.

Type Aliases and Casts

Short-hand names of types, and methods to convert one type to another.

Macros & Attributes

Code generation constructs expanded before the actual compilation happens.

In a macro_rules! implementation, the following macro captures can be used:

Pattern Matching

Constructs found in match or let expressions, or function parameters.

Pattern matching arms in match expressions. The left side of these arms can also be found in let expressions.

Generics & Constraints

Generics combine with many other constructs such as struct S<T>, fn f<T>(), ...

Strings & Chars

Rust has several ways to create string or char literals, depending on your needs.

Comments

No comment.

Miscellaneous

These sigils did not fit any other category but are good to know nonetheless.

Common Operators

Rust supports all common operators you would expect to find in a language (+, *, %, =, ==...). Since they behave no differently in Rust we do not list them here. For some of them Rust also supports operator overloading. ^STD

Guides

Project Anatomy

Basic project layout, and common files and folders, as used by Rust tooling.

An minimal library entry point with functions and modules looks like this:

// src/lib.rs (default library entry point)

pub fn f() {}      // Is a public item in root, so it's accessible from the outside.

mod m {
    pub fn g() {}  // No public path (`m` not public) from root, so `g`
}                  // is not accessible from the outside of the crate.

For binaries (not depicted), function fn main() {} is the entry point. Unit tests (not depicted), usually reside in a #[cfg(test)] mod test { } next to their code. Integration tests and benchmarks, in their basic, form look like this:

// tests/sample.rs (sample integration test)

#[test]
fn my_sample() {
    assert_eq!(my_crate::f(), 123); // Integration tests (and benchmarks) 'depend' to the crate like
}                                   // a 3rd party would. Hence, they only see public items.

// benches/sample.rs (sample benchmark)

#![feature(test)]   // #[bench] is still experimental

extern crate test;  // Even in '18 this is needed ... for reasons.
                    // Normally you don't need this in '18 code.

use test::{black_box, Bencher};

#[bench]
fn my_algo(b: &mut Bencher) {
    b.iter(|| black_box(my_crate::f())); // `black_box` prevents `f` from being optimized away.
}

Idiomatic Rust

If you are used to programming Java or C, consider these.

🔥 We highly recommend you also follow the API Guidelines (Checklist) for any shared project! 🔥

Async-Await 101

If you are familiar with async / await in C# or TypeScript, here are some things to keep in mind:

At each x.await, state machine passes control to subordinate state machine x. At some point a low-level state machine invoked via .await might not be ready. In that the case worker thread returns all the way up to runtime so it can drive another Future. Some time later the runtime:

• might resume execution. It usually does, unless sm / Future dropped.
• might resume with the previous worker or another worker thread (depends on runtime).

Simplified diagram for code written inside an async block :

       consecutive_code();           consecutive_code();           consecutive_code();
START --------------------> x.await --------------------> y.await --------------------> READY
// ^                          ^     ^                               Future<Output=X> ready -^
// Invoked via runtime        |     |
// or an external .await      |     This might resume on another thread (next best available),
//                            |     or NOT AT ALL if Future was dropped.
//                            |
//                            Execute `x`. If ready: just continue execution; if not, return
//                            this thread to runtime.

This leads to the following considerations when writing code inside an async construct:

Closures

There is a subtrait relationship Fn : FnMut : FnOnce. That means, a closure that implements Fn, also implements FnMut and FnOnce. Likewise, a closure that implements FnMut, also implements FnOnce.

From a call site perspective that means:

From the perspective of someone defining a closure:

That gives the following advantages and disadvantages:

A Guide to Reading Lifetimes

Lifetimes can be overwhelming at times. Here is a simplified guide on how to read and interpret constructs containing lifetimes if you are familiar with C.

Invisible Sugar

If something works that "shouldn't work now that you think about it", it might be due to one of these.

Formatting Strings

Formatting applies to print!, eprint!, write! (and their -ln siblings like println!). The format! macro can create a formatted String.

Each format argument follows a basic grammar:

{[argument][':'[[fill]align][sign]['#']['0'][width]['.' precision][type]]}

The full grammar is specified in the std::fmt documentation, but here are some commonly used flags:

Element	Meaning
argument	Omitted (next {}), number (0, 1, ...) or identifier for named arguments.
align	Left (<), center (^), or right (>) , if width is specified, fills with fill.
#	Alternate formatting. Pretty-print with {:#?}, for example.
0	Zero-pads numeric values.
width	Minimum width (≥ 0), padding with fill (default to space).
precision	Decimal digits (≥ 0) for numerics, or max width for non-numerics.
type	Debug (?), hex (x), binary (b), or octal (o) (there are more, using Traits).

Note that width and precision can use other arguments as their values, allowing for dynamic sizing of fields.

 

Example	Explanation
{:#?}	Pretty-print the next argument using Debug.
{2:#?}	Pretty-print the 3rd argument using Debug.
{val:^2$}	Center the val named argument, width specified by the 3rd argument.
{:<10.3}	Left align with width 10 and a precision of 3.
{val:#x}	Format val argument as hex, with a leading 0x (alternate format for x).

Tooling

Some commands and tools that are good to know.

Command	Description
cargo init	Create a new project for the latest edition.
cargo build	Build the project in debug mode (--release for all optimization).
cargo check	Check if project would compile (much faster).
cargo test	Run tests for the project.
cargo run	Run your project, if a binary is produced (main.rs).
cargo doc --open	Locally generate documentation for your code and dependencies.
cargo rustc -- -Zunpretty=X	Show more desugared Rust code, in particular with X being:
expanded	Show with expanded macros, ...
cargo +{nightly, stable} ...	Runs command with given toolchain, e.g., for 'nightly only' tools.
rustup docs	Open offline Rust documentation (incl. the books), good on a plane!

A command like cargo build means you can either type cargo build or just cargo b.

 

These are optional rustup components. Install them with rustup component add [tool].

Tool	Description
cargo clippy	Additional (lints) catching common API misuses and unidiomatic code. 🔗
cargo fmt	Automatic code formatter (rustup component add rustfmt). 🔗

 

These are 3rd party tools and usually need to be installed with cargo install cargo-[tool] first. They often require unstable and are subject to break.

Command	Description
cargo asm	Show generated assembly instructions for code. 🔗
cargo outdated	List upgradable dependencies. 🔗
cargo tree	Print dependencies as a tree. 🔗
cargo-edit	Meta package (cargo install cargo-edit) 🔗. Provides:
cargo add <crate>	Add latest version of <crate> to your Cargo.toml.
cargo rm <crate>	Remove <crate> from your Cargo.toml.
cargo upgrade <crate>	Upgrade the version of <crate> to the latest.
cargo flamegraph	Visualize CPU time (cargo install flamegraph). 🔗 OSX, Linux only
cargo cache	Show statistics on or clean the local download cache of cargo. 🔗

---

Misc

Links & Services

These are other great visual guides and tables.

Containers

Macro Railroad

Lifetimes

 

Cheat Sheets	Description
Rust Learning⭐	Probably the best collection of links about learning Rust.
Functional Jargon in Rust	A collection of functional programming jargon explained in Rust.
String Conversions	How to get type of string from another.
Periodic Table of Types	How various types and references correlate.
Futures	How to construct and work with futures.
Rust Iterator Cheat Sheet	Summary of iterator-related methods from std::iter and itertools.
Type-Based Rust Cheat Sheet	Lists common types and how they convert.

 

All major Rust books developed by the community.

Books ️📚	Description
The Rust Programming Language	Standard introduction to Rust, start here if you are new.
The API Guidelines	How to write idiomatic and re-usable Rust.
The Async Book 🚧	Explains async code, Futures, ...
The Edition Guide	Working with Rust 2015, Rust 2018, and beyond.
The Little Book of Rust Macros 🚧	Community's collective knowledge of Rust macros.
The Reference 🚧	Reference of the Rust language.
The RFC Book	Look up accepted RFCs and how they change the language.
The Rust Cookbook	Collection of simple examples that demonstrate good practices.
The Rustc Guide	Explains how the compiler works internally.
The Rustdoc Book	Tips how to customize cargo doc and rustdoc.
The Rustonomicon	Dark Arts of Advanced and Unsafe Rust Programming.
The SIMD Performance Guide 🚧	Work with u8x32 or f32x8 to speed up your computations.
The Unsafe Code Guidelines 🚧	Concise information about writing unsafe code.
The Unstable Book	Information about unstable items, e.g, #![feature(...)].
The Cargo Book	How to use cargo and write Cargo.toml.
The CLI Book	Information about creating CLI tools.
The Embedded Book	Working with embedded and #![no_std] devices.
The Embedonomicon	First #![no_std] from scratch on a Cortex-M.
The WebAssembly Book	Working with the web and producing .wasm files.
The wasm-bindgen Guide	How to bind Rust and JavaScript APIs in particular.

 

Comprehensive lookup tables for common components.

Tables 📋	Description
Compiler Error Index	Ever wondered what E0404 means?
ALL the Clippy Lints	All the clippy lints you might be interested in.
Configuring Rustfmt	All rustfmt options you can use in .rustfmt.toml.
Rust Changelog	See all the things that changed in a particular version.
Rust Forge	Lists release train and links for people working on the compiler.
Rust Platform Support	All supported platforms and their Tier.
Rust Component History	Check nightly status of various Rust tools for a platform.

 

Online services which provide information or tooling.

Services ⚙️	Description
crates.io	All 3rd party libraries for Rust.
docs.rs	Documentation for 3rd party libraries, automatically generated from source.
libs.rs	Unofficial overview of quality Rust libraries and applications.
Rust Playground	Try and share snippets of Rust code.

 

🦀 Year One Survey (September 2019) 🦀 [X]
Takes 1 minute to give feedback on how we're doing ...

Printing & PDF

Want this Rust cheat sheet as a PDF download? Generate PDF (or select File > Print – might take 10s so) and then "Save as PDF". It looks great in both Firefox's and Chrome's PDF exports. Alternatively use the cached PDF.