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

Standard Library

Traits

Traits define common behavior. If S implements trait T, you know S can behave as prescribed by T. Below is an overview of traits that may be a bit more tricky.

🧵 Thread Safety

🚥 Iterators

String Conversions

If you want a string of type ...

use std::os::unix::ffi::OsStrExt;
let bytes: &[u8] = my_os_str.as_bytes();
CString::new(bytes)?

String Formatting

Formatting applies to print!, eprint!, write! (and their -ln siblings like println!). Each format argument is either empty {}, {argument}, or follows a basic syntax:

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

Tooling

Project Anatomy

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

// src/main.rs (default application entry point)

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

// 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.

// src/lib.rs (default entry point for proc macros)

extern crate proc_macro;  // Apparently needed to be imported like this.

use proc_macro::TokenStream;

#[proc_macro_attribute]   // Can now be used as `#[my_attribute]`
pub fn my_attribute(_attr: TokenStream, item: TokenStream) -> TokenStream {
    item
}

// Cargo.toml

[package]
name = "my_crate"
version = "0.1.0"

[lib]
crate_type = ["proc-macro"]

// src/my_module.rs (any file of your project)

fn f() -> u32 { 0 }

#[cfg(test)]
mod test {
    use super::f;           // Need to import items from parent module. Has
                            // access to non-public members.
    #[test]
    fn ff() {
        assert_eq!(f(), 0);
    }
}

// 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.
}

Cargo

Some commands and tools that are good to know.

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

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

Cross Compilation

Coding Guides

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 in APIs

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:

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.

Unsafe, Unsound, Undefined

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

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

if maybe_true() {
   let r: &u8 = unsafe { &*ptr::null() };    // Once this runs, ENTIRE app is undefined. Even if
} else {                                     // line seemingly didn't do anything, app might now run
    println!("the spanish inquisition");     // both paths, corrupt database, or anything else.
}

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 the small, sound modules that are easy to review.
• Each unsafe unit should be accompanied by plain-text reasoning outlining its safety.

API Stability

These changes can break client code, compare RFC 1105. Major changes (🔴) are definitely breaking, while minor changes (🟡) might be breaking:

---

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.
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.
API Guidelines	How to write idiomatic and re-usable Rust.
Asynchronous Programming in Rust 🚧	Explains async code, Futures, ...
Edition Guide	Working with Rust 2015, Rust 2018, and beyond.
Guide to Rustc Development	Explains how the compiler works internally.
Little Book of Rust Macros 🚧	Community's collective knowledge of Rust macros.
Reference 🚧	Reference of the Rust language.
RFC Book	Look up accepted RFCs and how they change the language.
Rust Cookbook	Collection of simple examples that demonstrate good practices.
Rustdoc Book	Tips how to customize cargo doc and rustdoc.
Rustonomicon	Dark Arts of Advanced and Unsafe Rust Programming.
Unsafe Code Guidelines 🚧	Concise information about writing unsafe code.
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
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.
ALL the Clippy Lints	All the clippy lints you might be interested in.
Configuring Rustfmt	All rustfmt options you can use in .rustfmt.toml.
Compiler Error Index	Ever wondered what E0404 means?

 

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.