Rust Language Cheat Sheet

Clickable symbols

The Book.

Rust by Example.

Standard Library (API).

Nomicon.

Reference.

Official RFC documents.

The internet.

On this page, above.

On this page, below.

Other symbols

Largely deprecated.

Has minimum edition requirement.

Requires Rust nightly (or is incomplete).

Intentionally wrong example or pitfall.

Slightly esoteric, rarely used or advanced.

Something with outstanding utility.

The parent item expands to …

Opinionated.

Is missing good link or explanation.

X-Ray visualizations are enabled. These show aggregated feedback per section. Right now this is experimental. Known caveats:

• some sections that receive lots of feedback aren't shown (e.g., "Hello Rust")
• it does not account for age of the section (some sections have been around for many years, others for just a few months)
• it does neither account for feedback bursts (people mashing the same button 3 times), nor "most recent feedback" (people up- then down-voting).

The feedback format is (positive, negative, textual), equivalent to use of the feedback buttons.

Points you might run into

• Steep learning curve;¹ compiler enforcing (esp. memory) rules that would be "best practices" elsewhere.
• Missing Rust-native libs in some domains, target platforms (esp. embedded), IDE features.¹
• Longer compile times than "similar" code in other languages.¹
• Careless (use of unsafe in) libraries can secretly break safety guarantees.
• No formal language specification, ^🔗 can prevent legal use in some domains (aviation, medical, …). ^🔗
• Rust Foundation may offensively use their IP to affect 'Rust' projects (e.g, forbid names, impose policies). ^🔗🔗2

¹ Compare Rust Survey.
² Avoiding their marks (e.g, in your name, URL, logo, dress) is probably sufficient.

Modular Beginner Resources

• Tour of Rust - Live code and explanations, side by side.
• Rust in Easy English - 60+ concepts, simple English, example-driven.
• Rust for the Polyglot Programmer - A guide for the experienced programmer.

In addition consider The Book,^BK Rust by Example,^EX the Standard Library,^STD and Learn Rust.^🔗

Opinion ^💬 — If you have never seen or used any Rust it might be good to visit one of the links above before continuing; the next chapter might feel a bit terse otherwise.

With rare exceptions you are never 'allowed to reason' about the actual CPU. You write code for an abstracted CPU. Rust then (sort of) understands what you want, and translates that into actual RISC-V / x86 / … machine code.

This abstract machine

• is not a runtime, and does not have any runtime overhead, but is a computing model abstraction,
• contains concepts such as memory regions (stack, …), execution semantics, …
• knows and sees things your CPU might not care about,
• is de-facto a contract between you and the compiler,
• and exploits all of the above for optimizations.

• Application memory is just array of bytes on low level.
• Operating environment usually segments that, amongst others, into:
  • stack (small, low-overhead memory,¹ most variables go here),
  • heap (large, flexible memory, but always handled via stack proxy like Box<T>),
  • static (most commonly used as resting place for str part of &str),
  • code (where bitcode of your functions reside).
• Most tricky part is tied to how stack evolves, which is our focus.

¹ For fixed-size values stack is trivially manageable: take a few bytes more while you need them, discarded once you leave. However, giving out pointers to these transient locations form the very essence of why lifetimes exist; and are the subject of the rest of this chapter.

• Reserves memory location with name t of type S and the value S(1) stored inside.
• If declared with let that location lives on stack. ¹
• Note the linguistic ambiguity, in the term variable, it can mean the:
  1. name of the location in the source file ("rename that variable"),
  2. location in a compiled app, 0x7 ("tell me the address of that variable"),
  3. value contained within, S(1) ("increment that variable").
• Specifically towards the compiler t can mean location of t, here 0x7, and value within t, here S(1).

¹ Compare above,^↑ true for fully synchronous code, but async stack frame might placed it on heap via runtime.

• This will move value within t to location of a, or copy it, if S is Copy.
• After move location t is invalid and cannot be read anymore.
  • Technically the bits at that location are not really empty, but undefined.
  • If you still had access to t (via unsafe) they might still look like valid S, but any attempt to use them as valid S is undefined behavior. ^↓
• We do not cover Copy types explicitly here. They change the rules a bit, but not much:
  • They won't be dropped.
  • They never leave behind an 'empty' variable location.

• The type of a variable serves multiple important purposes, it:
  1. dictates how the underlying bits are to be interpreted,
  2. allows only well-defined operations on these bits
  3. prevents random other values or bits from being written to that location.
• Here assignment fails to compile since the bytes of M::new() cannot be converted to form of type S.
• Conversions between types will always fail in general, unless explicit rule allows it (coercion, cast, …).

• Once the 'name' of a non-vacated variable goes out of (drop-)scope, the contained value is dropped.
  • Rule of thumb: execution reaches point where name of variable leaves {}-block it was defined in
  • In detail more tricky, esp. temporaries, …
• Drop also invoked when new value assigned to existing variable location.
• In that case Drop::drop() is called on the location of that value.
  • In the example above drop() is called on a, twice on c, but not on t.
• Most non-Copy values get dropped most of the time; exceptions include mem::forget(), Rc cycles, abort().

• When a function is called, memory for parameters (and return values) are reserved on stack.¹
• Here before f is invoked value in a is moved to 'agreed upon' location on stack, and during f works like 'local variable' x.

¹ Actual location depends on calling convention, might practically not end up on stack at all, but that doesn't change mental model.

• Recursively calling functions, or calling other functions, likewise extends the stack frame.
• Nesting too many invocations (esp. via unbounded recursion) will cause stack to grow, and eventually to overflow, terminating the app.

• Stack that previously held a certain type will be repurposed across (even within) functions.
• Here, recursing on f produced second x, which after recursion was partially reused for m.

Key take away so far, there are multiple ways how memory locations that previously held a valid value of a certain type stopped doing so in the meantime. As we will see shortly, this has implications for pointers.

• A reference type such as &S or &mut S can hold the location of some s.
• Here type &S, bound as name r, holds location of variable a (0x3), that must be type S, obtained via &a.
• If you think of variable c as specific location, reference r is a switchboard for locations.
• The type of the reference, like all other types, can often be inferred, so we might omit it from now on:let r: &S = &a; let r = &a;

• References can read from (&S) and also write to (&mut S) locations they point to.
• The dereference *r means to use the location r points to (not the location of or value within r itself)
• In the example, clone d is created from *r, and S(2) written to *r.
  • We assume S implements Clone, and r.clone() clones target-of-r, not r itself.
  • On assignment *r = … old value in location also dropped (not shown above).

• While bindings guarantee to always hold valid data, references guarantee to always point to valid data.
• Esp. &mut T must provide same guarantees as variables, and some more as they can't dissolve the target:
  • They do not allow writing invalid data.
  • They do not allow moving out data (would leave target empty w/o owner knowing).

• In contrast to references, pointers come with almost no guarantees.
• They may point to invalid or non-existent data.
• Dereferencing them is unsafe, and treating an invalid *p as if it were valid is undefined behavior. ^↓

• Every entity in a program has some (temporal / spatial) extent where it is relevant, i.e., alive.
• Loosely speaking, this alive time can be¹
  1. the LOC (lines of code) where an item is available (e.g., a module name).
  2. the LOC between when a location is initialized with a value, and when the location is abandoned.
  3. the LOC between when a location is first used in a certain way, and when that usage stops.
  4. the LOC (or actual time) between when a value is created, and when that value is dropped.
• Within the rest of this section, we will refer to the items above as the:
  1. scope of that item, irrelevant here.
  2. scope of that variable or location.
  3. lifetime² of that usage.
  4. lifetime of that value, might be useful when discussing open file descriptors, but also irrelevant here.
• Likewise, lifetime parameters in code, e.g., r: &'a S, are
  • concerned with LOC any location r points to needs to be accessible or locked;
  • unrelated to the 'existence time' (as LOC) of r itself (well, it needs to exist shorter, that's it).
• &'static S means address must be valid during all lines of code.

¹ There is sometimes ambiguity in the docs differentiating the various scopes and lifetimes. We try to be pragmatic here, but suggestions are welcome.

² Live lines might have been a more appropriate term …

• Assume you got a r: &'c S from somewhere it means:
  • r holds an address of some S,
  • any address r points to must and will exist for at least 'c,
  • the variable r itself cannot live longer than 'c.

• Assume you got a mut r: &mut 'c S from somewhere.
  • That is, a mutable location that can hold a mutable reference.
• As mentioned, that reference must guard the targeted memory.
• However, the 'c part, like a type, also guards what is allowed into r.
• Here assigning &b (0x6) to r is valid, but &a (0x3) would not, as only &b lives equal or longer than &c.

• Once the address of a variable is taken via &b or &mut b the variable is marked as borrowed.
• While borrowed, the content of the address cannot be modified anymore via original binding b.
• Once address taken via &b or &mut b stops being used (in terms of LOC) original binding b works again.

• When calling functions that take and return references two interesting things happen:
  • The used local variables are placed in a borrowed state,
  • But it is during compilation unknown which address will be returned.

• Since f can return only one address, not in all cases b and c need to stay locked.
• In many cases we can get quality-of-life improvements.
  • Notably, when we know one parameter couldn't have been used in return value anymore.

• Lifetime parameters in signatures, like 'c above, solve that problem.
• Their primary purpose is:
  • outside the function, to explain based on which input address an output address could be generated,
  • within the function, to guarantee only addresses that live at least 'c are assigned.
• The actual lifetimes 'b, 'c are transparently picked by the compiler at call site, based on the borrowed variables the developer gave.
• They are not equal to the scope (which would be LOC from initialization to destruction) of b or c, but only a minimal subset of their scope called lifetime, that is, a minmal set of LOC based on how long b and c need to be borrowed to perform this call and use the obtained result.
• In some cases, like if f had 'c: 'b instead, we still couldn't distinguish and both needed to stay locked.

• A variable location is unlocked again once the last use of any reference that may point to it ends.

Here (M) means compilation fails because mutability error, (L) lifetime error. Also, dereference *rb not strictly necessary, just added for clarity.

• f_sr cases always work, short reference (only living 'b) can always be produced.
• f_sm cases usually fail simply because mutable chain to S needed to return &mut S.
• f_lr cases can fail because returning &'a S from &'a mut S to caller means there would now exist two references (one mutable) to same S which is illegal.
• f_lm cases always fail for combination of reasons above.

Note: This example is about the f functions, not compute. You can assume it to be defined as fn compute(x: &S, y: &S) {}. In that case the ra parameter would be automatically coerced ^↓ from &mut S to &S, since you can't have a shared and a mutable reference to the same target.

Here Scope means contained value lives until end of scope, i.e., past the println!().

• Functions or expressions producing movable values must be handled by callee.
• Values stores in 'normal' bindings are kept until end of scope, then dropped.
• Values stored in _ bindings are usually dropped right away.
• However, sometimes references (e.g., ref x3) can keep value (e.g., the tuple (S(3), S(6))) around for longer, so S(6), being part of that tuple can only be dropped once reference to its S(3) sibling disappears).

let s = "I ❤ Rust";
let t = "I ❤️ Rust";

^⚠️ For what seem to be browser bugs Safari and Edge render the hearts in Footnote 3 and 4 wrong, despite being able to differentiate them correctly in s and t above.

S O M E D R A M D A T A Main Memory S O M E (E) D A T A (S) CPU1 Cache S R A M (M) D A T A (S) CPU2 Cache

S O M E D X T A (M) Cycle 1 O3 S O M 4 D X T A Cycle 2 23 STALLED 1 4 (M) D X T Y (M) Cycle 3 23

1 2 3 4 S R A M D X T Y Main Memory RA 1 R A M Cycle 4 RA 1 2 M Cycle 5 23 1 2 3 4 (M) Cycle 6 23

Each argument designator in format macro is either empty {}, {argument}, or follows a basic syntax:

Rust has three kinds of namespaces:

¹ Counts in Types and in Functions, defines type X and constant X.
² Counts in Types and in Functions, defines type X and function X.

• In any given scope, for example within a module, only one item per namespace can exist, e.g.,
  • enum X {} and fn X() {} can coexist
  • struct X; and const X cannot coexist
• With a use my_mod::X; all items called X will be imported.

Due to naming conventions (e.g., fn and mod are lowercase by convention) and common sense (most developers just don't name all things X) you won't have to worry about these kinds in most cases. They can, however, be a factor when designing macros.

• Set of values with given semantics, layout, …

Sample types and sample values.

• It may be obvious but   u8,    &u8,    &mut u8, are entirely different from each other
• Any t: T only accepts values from exactly T, e.g.,
  • f(0_u8) can't be called with f(&0_u8),
  • f(&mut my_u8) can't be called with f(&my_u8),
  • f(0_u8) can't be called with f(0_i8).

Yes, 0 != 0 (in a mathematical sense) when it comes to types! In a language sense, the operation ==(0_u8, 0_u16) just isn't defined to prevent happy little accidents.

How values differ between types.

• However, Rust might sometimes help to convert between types¹
  • casts manually convert values of types, 0_i8 as u8
  • coercions ^↑ automatically convert types if safe², let x: &u8 = &mut 0_u8;

¹ Casts and coercions convert values from one set (e.g., u8) to another (e.g., u16), possibly adding CPU instructions to do so; and in such differ from subtyping, which would imply type and subtype are part of the same set (e.g., u8 being subtype of u16 and 0_u8 being the same as 0_u16) where such a conversion would be purely a compile time check. Rust does not use subtyping for regular types (and 0_u8 does differ from 0_u16) but sort-of for lifetimes. ^🔗

² Safety here is not just physical concept (e.g., &u8 can't be coerced to &u128), but also whether 'history has shown that such a conversion would lead to programming errors'.

• Types usually come with inherent implementations, ^REF e.g., impl Port {}, behavior related to type:
  • associated functions Port::new(80)
  • methods port.close()

What's considered related is more philosophical than technical, nothing (except good taste) would prevent a u8::play_sound() from happening.

• Traits …
  • are way to "abstract" behavior,
  • trait author declares semantically this trait means X,
  • other can implement ("subscribe to") that behavior for their type.
• Think about trait as "membership list" for types:

Traits as membership tables, Self refers to the type included.

• Whoever is part of that membership list will adhere to behavior of list.
• Traits can also include associated methods, functions, …

• Traits without methods often called marker traits.
• Copy is example marker trait, meaning memory may be copied bitwise.

• Some traits entirely outside explicit control
• Sized provided by compiler for types with known size; either this is, or isn't

• Traits are implemented for types 'at some point'.
• Implementation impl A for B add type B to the trait membership list:

• Visually, you can think of the type getting a "badge" for its membership:

Interfaces

• In Java, Alice creates interface Eat.
• When Bob authors Venison, he must decide if Venison implements Eat or not.
• In other words, all membership must be exhaustively declared during type definition.
• When using Venison, Santa can make use of behavior provided by Eat:

Traits

• In Rust, Alice creates trait Eat.
• Bob creates type Venison and decides not to implement Eat (he might not even know about Eat).
• Someone^* later decides adding Eat to Venison would be a really good idea.
• When using Venison Santa must import Eat separately:

^* To prevent two persons from implementing Eat differently Rust limits that choice to either Alice or Bob; that is, an impl Eat for Venison may only happen in the crate of Venison or in the crate of Eat. For details see coherence. ^?

• Vec<u8> is type "vector of bytes"; Vec<char> is type "vector of chars", but what is Vec<>?

Types vs type constructors.

• Vec<> is no type, does not occupy memory, can't even be translated to code.
• Vec<> is type constructor, a "template" or "recipe to create types"
  • allows 3^rd party to construct concrete type via parameter,
  • only then would this Vec<UserType> become real type itself.

• Parameter for Vec<> often named T therefore Vec<T>.
• T "variable name for type" for user to plug in something specific, Vec<f32>, S<u8>, …

Type vs type constructors.

• Some type constructors not only accept specific type, but also specific constant.
• [T; n] constructs array type holding T type n times.
• For custom types declared as MyArray<T, const N: usize>.

Type constructors based on constant.

• If T can be any type, how can we reason about (write code) for such a Num<T>?
• Parameter bounds:
  • limit what types (trait bound) or values (const bound ^?) allowed,
  • we now can make use of these limits!
• Trait bounds act as "membership check":

We add bounds to the struct here. In practice it's nicer add bounds to the respective impl blocks instead, see later this section.

• Long trait bounds can look intimidating.
• In practice, each + X addition to a bound merely cuts down space of eligible types.

When we write:

It can be read as:

• here is an implementation recipe for any type T (the impl <T> part),
• where that type must be member of the Absolute + Dim + Mul traits,
• you may add an implementation block to the type family S<>,
• containing the methods …

You can think of such impl<T> … {} code as abstractly implementing a family of behaviors. ^REF Most notably, they allow 3^rd parties to transparently materialize implementations similarly to how type constructors materialize types:

Can also write "family implementations" so they apply trait to many types:

These are called blanket implementations.

→ Whatever was in left table, may be added to right table, based on the following recipe (impl) →

They can be neat way to give foreign types functionality in a modular way if they just implement another interface.

Notice how some traits can be "attached" multiple times, but others just once?

Why is that?

• Traits themselves can be generic over two kinds of parameters:
  • trait From<I> {}
  • trait Deref { type O; }
• Remember we said traits are "membership lists" for types and called the list Self?
• Turns out, parameters I (for input) and O (for output) are just more columns to that trait's list:

Input and output parameters.

Now here's the twist,

• any output O parameters must be uniquely determined by input parameters I,
• (in the same way as a relation X Y would represent a function),
• Self counts as an input.

A more complex example:

• this creates a relation of types named Complex,
• with 3 inputs (Self is always one) and 2 outputs, and it holds (Self, I1, I2) => (O1, O2)

Various trait implementations. The last one is not valid as (NiceMonster, u16, String) has
already uniquely determined the outputs.

• Parameter choice (input vs. output) also determines who may be allowed to add members:
  • I parameters allow "familes of implementations" be forwarded to user (Santa),
  • O parameters must be determined by trait implementor (Alice or Bob).

Santa may add more members by providing his own type for T.

For given set of inputs (here Self), implementor must pre-select O.

Choice of parameters goes along with purpose trait has to fill.

No Additional Parameters

Trait author assumes:

• neither implementor nor user need to customize API.

Input Parameters

Trait author assumes:

• implementor would customize API in multiple ways for same Self type,
• users may want ability to decide for which I-types behavior should be possible.

Output Parameters

Trait author assumes:

• implementor would customize API for Self type (but in only one way),
• users do not need, or should not have, ability to influence customization for specific Self.

As you can see here, the term input or output does not (necessarily) have anything to do with whether I or O are inputs or outputs to an actual function!

Multiple In- and Output Parameters

Like examples above, in particular trait author assumes:

• users may want ability to decide for which I-types ability should be possible,
• for given inputs, implementor should determine resulting output type.

• A type T is Sized ^STD if at compile time it is known how many bytes it occupies, u8 and &[u8] are, [u8] isn't.
• Being Sized means impl Sized for T {} holds. Happens automatically and cannot be user impl'ed.
• Types not Sized are called dynamically sized types ^{BK NOM REF} (DSTs), sometimes unsized.
• Types without data are called zero sized types ^NOM (ZSTs), do not occupy space.

• T can be any concrete type.
• However, there exists invisible default bound T: Sized, so S<str> is not possible out of box.
• Instead we have to add T : ?Sized to opt-out of that bound:

• Lifetimes act^* as type parameters:
  • user must provide specific 'a to instantiate type (compiler will help within methods),
  • S<'p> and S<'q> are different types, just like Vec<f32> and Vec<u8> are
  • meaning you can't just assign value of type S<'a> to variable expecting S<'b> (exception: subtype relationship for lifetimes, i.e., 'a outlives 'b).

• 'static is only globally available type of the lifetimes kind.

^* There are subtle differences, for example you can create an explicit instance 0 of a type u32, but with the exception of 'static you can't really create a lifetime, e.g., "lines 80 - 100", the compiler will do that for you. ^🔗

Safe Code

• Safe has narrow meaning in Rust, vaguely 'the intrinsic prevention of undefined behavior (UB)'.
• Intrinsic means the language won't allow you to use itself to cause UB.
• Making an airplane crash or deleting your database is not UB, therefore 'safe' from Rust's perspective.
• Writing to /proc/[pid]/mem to self-modify your code is also 'safe', resulting UB not caused intrinsincally.

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 trust you.
• By itself unsafe code is not bad, but dangerous, and needed for FFI or exotic data structures.

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 compiler produce fallacious code, execution of which leads to UB.
• After triggering undefined behavior anything can happen. 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, invalid and should never exist.

Unsound Code

• Any safe Rust that could (even only theoretically) produce UB for any user input is always unsound.
• As is unsafe code that may invoke UB on its own accord by violating above-mentioned promises.
• Unsound code is a stability and security risk, and violates basic assumption many Rust users have.