Rustic Symmetries

In honor of the second birthday of stable Rust, here is a small contribution to Rust documentation.

Many concepts in Rust come in matching sets or have some pleasing symmetry. This is a summary or "cheat sheet" for some of these.

Some of these tables may look intimidating, but they reflect the reality of systems programming with fine-grained control over memory. If you're just getting started with Rust, don't panic and do set this article aside! It's intended as a reference and a guide to how to organize these things in your head once you vaguely know what they are.

Contributions are welcome! Just open a pull request.

References

This demonstrates that neither &T nor &mut T is a subtype of the other, in the Liskov sense.

Ownership and mutability

Ownership controls when a value is destroyed. A value can have either a unique owner, or a number of references which collectively share ownership. The latter case usually involves reference counting.

Interior mutability refers to any wrapper type Wrapper such that we can go from &Wrapper<T> to &mut T, or at least have some of the capabilities of &mut T.

The column headings here refer (more or less) to the point in time at which Rust's safety invariants are checked. Note that no unsafety can occur due to sharing the thread-unsafe structures between threads. The compiler will simply reject your code, through the magic of the Sync trait.

Numeric types

^α Nightly-only, as of rustc 1.18.

Strings

^α Nearly useless, because most mutations could change the length of a UTF-8 codepoint. One exception is ASCII-only case conversion.

^β In most cases, you can borrow static memory (e.g. a string literal) with a type like &'static str.

^γ With raw pointers, you are on your own regarding ownership / borrowing semantics. Any good C library will document its expectations.

^δ You can slice off the front of a NUL-terminated string, but not the end.

^ε On the general principle that if you own something you can mutate it. But you could use *const c_char instead.

Functions and closures

The captures or free variables of a closure are the variables used in a lambda expression which are not defined in the lambda or its arguments list. The captures come from the surrounding environment of a lambda expression.

Rust infers which trait(s) a closure can implement from how the captures are used. You can force values to be moved into a closure by prefixing the move keyword.

Each lambda and fn has its own unique, un-nameable type (Voldemort type?). This enables static dispatch and inlining. Each of these un-nameable types can be coerced to the appropriate fn / Fn / FnMut / FnOnce.

^α Nightly-only, as of rustc 1.18.

Sizes

This table describes the sizes of some common types.

A word is a pointer or a pointer-sized integer.

The first size is the size of the value itself: the stuff that ends up on the stack if you put it in a let variable. The second size is the size of any owned data in the heap.

We assume T, A, B, C are Sized.

^α These are function pointers. Technically, they can have a different size from a data pointer, but this does not happen on common architectures.

^β This optimization actually applies to any Option-shaped enum which contains, somewhere, a field which cannot be 0.

See also

rust-learning cheat sheets

Rust Cheatsheet

Rust Iterator Cheat Sheet

The Periodic Table of Rust Types

Cheatsheet for Futures

Time complexity for collections