Example

Explanation

//

Line comment, use these to document code flow or internals.

///

Outer line doc comment, use these on types.

//!

Inner line doc comment, mostly used at start of file to document module.

/*...*/

Block comment.

/**...*/

Outer block doc comment.

/*!...*/

Inner block doc comment.

rust ...

In doc comments, include a doc test (doc code running on cargo test).

#

In doc tests, hide line from documentation (# use x::hidden;).

Example

Explanation

struct S {}

Define a struct with named fields.

struct S { x: T }

Define struct with named field x of type T.

struct S (T);

Define "tupled" struct with numbered field .0 of type T.

struct S;

Define zero sized unit struct. Occupies no space, optimized away.

enum E {}

Define an enum, c. algebraic data types, tagged unions.

enum E { A, B``(), C {} }

Define variants of enum; can be unit- A, tuple- B () and struct-like C{}.

enum E { A = 1 }

If variants are only unit-like, allow discriminant values, e.g., for FFI.

union U {}

Unsafe C-like union for FFI compatibility.

static X: T = T();

Global variable with 'static lifetime, single memory location.

const X: T = T();

Defines constant . Copied into a temporary when used.

let x: T;

Allocate T bytes on stack bound as x. Assignable once, not mutable.

let mut x: T;

Like let, but allow for mutability and mutable borrow.

x = y;

Moves y to x, invalidating y if T is not Copy, and copying y otherwise.

Example

Explanation

S { x: y }

Create struct S {} or use'ed enum E::S {} with field x set to y.

S { x }

Same, but use local variable x for field x.

S { ..s }

Fill remaining fields from s, esp. useful with Default.

S { 0: x }

Like S (x) below, but set field .0 with struct syntax.

S (x)

Create struct S (T) or use'ed enum E::S () with field .0 set to x.

S

If S is unit struct S; or use'ed enum E::S create value of S.

E::C { x: y }

Create enum variant C. Other methods above also work.

()

Empty tuple, both literal and type, aka unit.

(x)

Parenthesized expression.

(x,)

Single-element tuple expression.

(S,)

Single-element tuple type.

[S]

Array type of unspecified length, i.e., slice. Can't live on stack.

[S; n]

Array type of fixed length n holding elements of type S.

[x; n]

Array instance with n copies of x.

[x, y]

Array instance with given elements x and y.

x[0]

Collection indexing. Overloadable Index, IndexMut​

x[..]

Collection slice-like indexing via RangeFull, c. slices.

x[a..]

Collection slice-like indexing via RangeFrom.

x[..b]

Collection slice-like indexing RangeTo.

x[a..b]

Collection slice-like indexing via Range.

a..b

Right-exclusive range creation, also seen as ..b.

a..=b

Inclusive range creation, also seen as ..=b.

s.x

Named field access, might try to Deref if x not part of type S.

s.0

Numbered field access, used for tuple types S (T).

Example

Explanation

​

​

!

Always empty never type.

​

​

_

Unnamed variable binding, e.g., `

x, _

{}`.

let _ = x;

Unnamed assignment is no-op, does not move out x or preserve scope!

​

​

_x

Variable binding explicitly marked as unused.

​

​

1_234_567

Numeric separator for visual clarity.

​

​

1_u8

Type specifier for numeric literals (also i8, u16, ...).

​

​

0xBEEF, 0o777, 0b1001

Hexadecimal (0x), octal (0o) and binary (0b) integer literals.

​

​

r#foo

A raw identifier for edition compatibility.

​

​

x;

Statement terminator, c. expressions

​

​

Example

Explanation

&S

Shared reference (space for holding any &s).

&[S]

Special slice reference that contains (address, length).

&str

Special string reference that contains (address, length).

&mut S

Exclusive reference to allow mutability (also &mut [S], &mut dyn S, ...)

&dyn T

Special trait object reference that contains (address, vtable).

*const S

Immutable raw pointer type w/o memory safety.

*mut S

Mutable raw pointer type w/o memory safety.

&s

Shared borrow (e.g., address, len, vtable, ... of this s, like 0x1234).

&mut s

Exclusive borrow that allows mutability.

ref s

Bind by reference.

let ref r = s;

Equivalent to let r = &s.

let S { ref mut x } = s;

Mutable ref binding (let x = &mut s.x), shorthand destructuring version.

*r

Dereference a reference r to access what it points to.

*r = s;

If r is a mutable reference, move or copy s to target memory.

s = *r;

Make s a copy of whatever r references, if that is Copy.

s = *my_box;

​Special case for Box that can also move out Box'ed content if it isn't Copy.

'a

A lifetime parameter,, duration of a flow in static analysis.

&'a S

Only accepts a s with an address that lives 'a or longer.

&'a mut S

Same, but allow content of address to be changed.

struct S<'a> {}

Signals S will contain address with lifetime 'a. Creator of S decides 'a.

trait T<'a> {}

Signals a S which impl T for S might contain address.

fn f<'a>(t: &'a T)

Same, for function. Caller decides 'a.

'static

Special lifetime lasting the entire program execution.

Example

Explanation

type T = S;

Create a type alias, i.e., another name for S.

Self

Type alias for implementing type, e.g. fn new() -> Self.

self

Method subject in fn f(self) {}, same as fn f(self: Self) {}.

&self

Same, but refers to self as borrowed, same as f(self: &Self)

&mut self

Same, but mutably borrowed, same as f(self: &mut Self)

self: Box

​Arbitrary self type, add methods to smart pointers (my_box.f_of_self()).

S as T

Disambiguate type S as trait T, e.g., ::f().

S as R

In use of symbol, import S as R, e.g., use a::S as R.

x as u32

Primitive cast, may truncate and be a bit surprising.

Example

Explanation

​

​

trait T {}

Define a trait; common behavior others can implement.

​

​

trait T : R {}

T is subtrait of supertrait R. Any S must impl R before it can impl T.

​

​

impl S {}

Implementation of functionality for a type S, e.g., methods.

​

​

impl T for S {}

Implement trait T for type S.

​

​

impl !T for S {}

Disable an automatically derived auto trait .

​

​

fn f() {}

Definition of a function; or associated function if inside impl.

​

​

fn f() -> S {}

Same, returning a value of type S.

​

​

fn f(&self) {}

Define a method, e.g., within an impl S {}.

​

​

const fn f() {}

Constant fn usable at compile time, e.g., const X: u32 = f(Y).

​

​

async fn f() {}

Async function transformation, makes f return an impl Future.

​

​

async fn f() -> S {}

Same, but make f return an impl Future.

​

​

async { x }

Used within a function, make { x } an impl Future.

​

​

fn() -> S

Function pointers,, memory holding address of a callable.

​

​

Fn() -> S

Callable Trait, (also FnMut, FnOnce), implemented by closures, fn's ...

​

​

`

​

{}`

A closure that borrows its captures.

`

x

{}`

Closure with a bound parameter x.

`

x

x + x`

Closure without block expression; may only consist of single expression.

`move

x

x + y`

Closure taking ownership of its captures.

`return

​

true`

Closures sometimes look like logical ORs (here: return a closure).

unsafe

If you enjoy debugging segfaults Friday night; unsafe code.

​

​

unsafe f() {}

Sort-of means "can cause UB, YOU must check requirements".

​

​

unsafe {}

Guarantees to compiler "*I have checked requirements, trust me*".

​

​

Example

Explanation

while x {}

Loop, run while expression x is true.

loop {}

Loop infinitely until break. Can yield value with break x.

for x in iter {}

Syntactic sugar to loop over iterators.

if x {} else {}

Conditional branch if expression is true.

'label: loop {}

Loop label, useful for flow control in nested loops.

break

Break expression to exit a loop.

break x

Same, but make x value of the loop expression (only in actual loop).

break 'label

Exit not only this loop, but the enclosing one marked with 'label.

continue

Continue expression to the next loop iteration of this loop.

continue 'label

Same, but instead of enclosing loop marked with 'label.

x?

If x is Err or None, return and propagate.

x.await

Only works inside async. Yield flow until Future or Stream x ready.

return x

Early return from function. More idiomatic way is to end with expression.

f()

Invoke callable f (e.g., a function, closure, function pointer, Fn, ...).

x.f()

Call member function, requires f takes self, &self, ... as first argument.

X::f(x)

Same as x.f(). Unless impl Copy for X {}, f can only be called once.

X::f(&x)

Same as x.f().

X::f(&mut x)

Same as x.f().

S::f(&x)

Same as x.f() if X derefs to S, i.e., x.f() finds methods of S.

T::f(&x)

Same as x.f() if X impl T, i.e., x.f() finds methods of T if in scope.

X::f()

Call associated function, e.g., X::new().

::f()

Call trait method T::f() implemented for X.

Example

Explanation

match m {}

Initiate pattern matching, then use match arms, c. next table.

let S(x) = get();

Notably, let also destructures similar to the table below.

let S { x } = s;

Only x will be bound to value s.x.

let (_, b, _) = abc;

Only b will be bound to value abc.1.

let (a, ..) = abc;

Ignoring 'the rest' also works.

let (.., a, b) = (1, 2);

Specific bindings take precedence over 'the rest', here a is 1, b is 2.

let Some(x) = get();

Won't work if pattern can be refuted, use if let instead.

if let Some(x) = get() {}

Branch if pattern can be assigned (e.g., enum variant), syntactic sugar.

fn f(S { x }: S)

Function parameters also work like let, here x bound to s.x of f(s).

Match Arm

Explanation

​

E::A => {}

Match enum variant A, c. pattern matching.

​

E::B ( .. ) => {}

Match enum tuple variant B, wildcard any index.

​

E::C { .. } => {}

Match enum struct variant C, wildcard any field.

​

S { x: 0, y: 1 } => {}

Match struct with specific values (only accepts s with s.x of 0 and s.y of 1).

​

S { x: a, y: b } => {}

Match struct with any(!) values and bind s.x to a and s.y to b.

​

S { x, y } => {}

Same, but shorthand with s.x and s.y bound as x and y respectively.

​

S { .. } => {}

Match struct with any values.

​

D => {}

Match enum variant E::D if D in use.

​

D => {}

Match anything, bind D; possibly false friend of E::D if D not in use.

​

_ => {}

Proper wildcard that matches anything / "all the rest".

​

(a, 0) => {}

Match tuple with any value for a and 0 for second.

​

[a, 0] => {}

Slice pattern, match array with any value for a and 0 for second.

​

[1, ..] => {}

Match array starting with 1, any value for rest; subslice pattern.

​

[2, .., 5] => {}

Match array starting with 1, ending with 5.

​

[2, x @ .., 5] => {}

Same, but also bind x to slice representing middle (c. next entry).

​

x @ 1..=5 => {}

Bind matched to x; pattern binding, here x would be 1, 2, ... or 5.

​

`0

1 => {}`

Pattern alternatives (or-patterns).

`E::A

E::Z`

Same, but on enum variants.

`E::C {x}

E::D {x}`

Same, but bind x if all variants have it.

S { x } if x > 10 => {}

Pattern match guards, condition must be true as well to match.

​

Example

Explanation

m!()

Macro invocation, also m!{}, m![] (depending on macro).

#[attr]

Outer attribute., annotating the following item.

#![attr]

Inner attribute, annotating the surrounding item.

Within Macros

Explanation

$x:ty

Macro capture, with the ty part being:

$x:item

An item, like a function, struct, module, etc.

$x:block

A block {} of statements or expressions, e.g., { let x = 5; }

$x:stmt

A statement, e.g., let x = 1 + 1;, String::new(); or vec![];

$x:expr

An expression, e.g., x, 1 + 1, String::new() or vec![]

$x:pat

A pattern, e.g., Some(t), (17, 'a') or _.

$x:ty

A type, e.g., String, usize or Vec.

$x:ident

An identifier, for example in let x = 0; the identifier is x.

$x:path

A path (e.g. foo, ::std::mem::replace, transmute::<_, int>, …).

$x:literal

A literal (e.g. 3, "foo", b"bar", etc.).

$x:lifetime

A lifetime (e.g. 'a, 'static, etc.).

$x:meta

A meta item; the things that go inside #[...] and #![...] attributes.

$x:vis

A visibility modifier; pub, pub(crate), etc.

$x:tt

A single token tree, see here for more details.

$x

Macro substitution, e.g., use the captured $x:ty from above.

$(x),*

Macro repetition "zero or more times" in macros by example.

$(x),?

Same, but "zero or one time".

$(x),+

Same, but "one or more times".

$(x)<<+

In fact separators other than , are also accepted. Here: <<.

$crate

Special hygiene variable, crate where macros is defined.

Example

Explanation

S

A generic type with a type parameter (T is placeholder name here).

S

Type short hand trait bound specification (R must be actual trait).

T: R, P: S

Independent trait bounds (here one for T and one for P).

T: R, S

Compile error, you probably want compound bound R + S below.

T: R + S

Compound trait bound, T must fulfill R and S.

T: R + 'a

Same, but w. lifetime. T must fulfill R, if T has lifetimes, must outlive 'a.

T: ?Sized

Opt out of a pre-defined trait bound, here Sized.

T: 'a

Type lifetime bound ; if T has references, they must outlive 'a.

T: 'static

Same; does esp. not mean value t will live 'static, only that it could.

'b: 'a

Lifetime 'b must live at least as long as (i.e., outlive) 'a bound.

S where T: R

Same as S but more pleasant to read for longer bounds.

S

Default type parameter for associated type.

S<'_>

Inferred anonymous lifetime; asks compiler to 'figure it out' if obvious.

S<_>

Inferred anonymous type, e.g., as let x: Vec<_> = iter.collect()

S::

Turbofish call site type disambiguation, e.g. f::().

trait T {}

A trait generic over X. Can have multiple impl T for S (one per X).

trait T { type X; }

Defines associated type X. Only one impl T for S possible.

type X = R;

Set associated type within impl T for S { type X = R; }.

impl S {}

Implement functionality for any T in S.

impl S {}

Implement functionality for exactly S (e.g., S).

fn f() -> impl T

Existential types, returns an unknown-to-caller S that impl T.

fn f(x: &impl T)

Trait bound,"impl traits", somewhat similar to fn f(x: &S).

fn f(x: &dyn T)

Marker for dynamic dispatch, f will not be monomorphized.

fn f() where Self: R;

In trait T {}, make f accessible only on types known to also impl R.

fn f() where Self: R {}

Esp. useful w. default methods (non dflt. would need be impl'ed anyway).

for<'a>

Higher-ranked trait bounds.

trait T: for<'a> R<'a> {}

Any S that impl T would also have to fulfill R for any lifetime.

Example

Explanation

mod m {}

Define a module, get definition from inside {}.

mod m;

Define a module, get definition from m.rs or m/mod.rs.

a::b

Namespace path to element b within a (mod, enum, ...).

::b

Search b relative to crate root.

crate::b

Search b relative to crate root.

self::b

Search b relative to current module.

super::b

Search b relative to parent module.

use a::b;

Use b directly in this scope without requiring a anymore.

use a::{b, c};

Same, but bring b and c into scope.

use a::b as x;

Bring b into scope but name x, like use std::error::Error as E.

use a::b as _;

Bring b anonymously into scope, useful for traits with conflicting names.

use a::*;

Bring everything from a into scope.

pub use a::b;

Bring a::b into scope and reexport from here.

pub T

"Public if parent path is public" visibility for T.

pub(crate) T

Visible at most in current crate.

pub(self) T

Visible at most in current module.

pub(super) T

Visible at most in parent.

pub(in a::b) T

Visible at most in a::b.

extern crate a;

Declare dependency on external crate ; just use a::b in .

extern "C" {}

Declare external dependencies and ABI (e.g., "C") from FFI.

extern "C" fn f() {}

Define function to be exported with ABI (e.g., "C") to FFI.

Example

Explanation

"..."

String literal, UTF-8, will interpret \n as line break 0xA, ...

r"..."

Raw string literal. UTF-8, won't interpret \n, ...

r#"..."#

Raw string literal, UTF-8, but can also contain ". Number of # can vary.

b"..."

Byte string literal; constructs ASCII [u8], not a string.

br"...", br#"..."#

Raw byte string literal, ASCII [u8], combination of the above.

'🦀'

Character literal, fixed 4 byte unicode 'char'.

b'x'

ASCII byte literal.