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

Data & Types

Memory representations of common data types.

Basic Types

Memory representations are depicted for little-endian architectures (e.g., x86-64).

Integer Types ^REF

Float Types ^REF

Float types are slightly more complicated and follow IEEE 754-2008.

Textual Types ^REF

Notice how:

• char is always 4 bytes and only holds a single Unicode scalar value (thus possibly wasting space),
• str is a byte-array of unknown length guaranteed to hold UTF-8 code points (but harder to index).

Custom Types

Basic types that can be defined by the user. Actual layout ^REF is subject to representation. ^REF Additional padding can be present.

These sum types hold a value of one of their sub types:

References & Pointers

References give safe access to another memory location. As can be seen below, lifetimes are not encoded at runtime. Pointers give unsafe access to other memory.

Rust also has a number of special reference types that encode more than just an address, see below. The respective &mut version is identical and omitted:

Box is Rust's type for heap allocation that also comes in a number of special variants:

Standard Library Types

Rust's standard library combines many of the above primitive types into useful types with special semantics. Some common types:

These dynamic collections grow when needed and are backed by the heap:

Shared ownership of memory and resources. If the type does not contain a Cell for T, these are often combined with one of the Cell types above to allow shared de-facto mutability.

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.

Unsafe, Unsound, Undefined

Unsafe leads to unsound. Unsound leads to undefined. Undefined leads to the dark side of the force.

Unsafe Code

• Code marked unsafe has special permissions, e.g., to deref raw pointers, or invoke other unsafe functions.
• Along come special promises the author must uphold to the compiler, and the compiler will trustingly reason and optimize based on these promises.
• By itself unsafe code is not bad, but dangerous, and needed for FFI, assembly, or some exotic data structures.

// `x` must always point to race-free, valid, aligned, initialized u8 memory.
unsafe fn unsafe_f(x: *mut u8) {
    my_native_lib(x);
}

Undefined Behavior (UB)

• As mentioned, unsafe code implies special promises to the compiler (it wouldn't need be unsafe otherwise).
• Failure to uphold any promise makes the compiler produce wrong code, giving an undefined program.
• With undefined behavior anything is possible. Insidiously, the effects may be 1) subtle, 2) manifest far away from the site of violation or 3) be visible only under certain conditions.
• A seemingly working program (incl. any number of unit tests) is no proof UB code might not fail on a whim.
• Code with UB is objectively dangerous and invalid and should never exist.

if user_pressed_x() {                                  // Even if user never pressed `x` compiler
    let r: &mut u8 = unsafe { &mut *ptr::null_mut() }; // might have reasoned backwards b/c broken
}                                                      // promise and tainted whole app.

Unsound Code

• Any safe Rust that could (even only theoretically) produce undefined behavior is unsound.
• Such safe Rust code should instead be tagged unsafe with all critical contracts documented.
• Any unsafe Rust code that for its user unavoidably (and undocumented) exhibits UB is likewise unsound.
• Unsound code is of particular concern in libraries, where its UB'ness depends on how the code is used.
• As such, unsound code exposed through a library is a liability to users as it violates basic assumption many Rust users have, while unsound code within an application are accidents waiting to happen.

fn unsound_ref<T>(x: &T) -> &u128 {      // Signature looks safe to users. Happens to be
    unsafe { mem::transmute(x) }         // ok if invoked with an &u128, UB for practically
}                                        // everything else.

Responsible use of Unsafe

• Do not use unsafe unless you absolutely have to.
• Follow the Nomicon, Unsafe Guidelines, always uphold all safety invariants, and never invoke UB.
• Minimize the use of unsafe and encapsulate it in a small, boring units that are trivial to review.
• Each unsafe invocation should be accompanied by plain-text comments explaining why it is safe.

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). 🔗

 

A large number of additional cargo plugins can be found here.

---

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.
std.rs	Shortcut to std documentation.
docs.rs	Documentation for 3rd party libraries, automatically generated from source.
lib.rs	Unofficial overview of quality Rust libraries and applications.
Rust Playground	Try and share snippets of Rust code.

 

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.