Rust-CheatSheet

Rust CheatSheet 是对于 Rust 学习/实践过程中的语法与技巧进行盘点,其属于 Awesome CheatSheet 系列,致力于提升学习速度与研发效能,即可以将其当做速查手册,也可以作为轻量级的入门学习资料。本文参考了许多优秀的文章与代码示范,统一声明在了 Awesome Rust List;如果希望深入了解某方面的内容,可以继续阅读Rust-Series,或者前往 rust-examples 查看使用 Rust 解决常见的数据结构与算法、设计模式、业务功能方面的代码实现。

Rust 语法速览、实践技巧与开源工具清单

Rust 是为工业应用而生,并不拘泥于遵循某个范式(Paradigm),笔者认为其最核心的特性为 Ownership 与 Lifetime;能够在没有 GC 与 Runtime 的情况下,防止近乎所有的段错误,并且保证线程安全(prevents nearly all segfaults, and guarantees thread safety)。Rust 为每个引用与指针设置了 Lifetime,对象则不允许在同一时间有两个和两个以上的可变引用,并且在编译阶段即进行了内存分配(栈或者堆);Rust 还提供了 Closure 等函数式编程语言的特性、编译时多态(Compile-time Polymorphism)、衍生的错误处理机制、灵活的模块系统等。

对于 Rust 的语法速览可以参考本目录下的 rust-snippets

Cheats.rs

Hello World

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

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

Variables

通过关键字定义的数据类型和存储位置。

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.

绑定变量(Bound Variables)存在于堆栈中,用于同步代码。在 async {} 代码中,它们成为异步状态机的一部分,可能驻留在堆上。从技术上讲,可变性和不变性是误称。不可变的绑定或共享引用可能仍包含 Cell,从而提供内部可变性。创建和访问数据结构;以及其他一些西语类型。

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

References & Pointers

授予对未拥有的内存的访问权限。另请参见“泛型和约束”部分。

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.

Types

类型的简写名称,以及将一种类型转换为另一种类型的方法。

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.

Functions & Behavior

定义代码单元及其抽象。

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*".

Control Flow

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.

Pattern Matching

在 match 或 let 表达式或函数参数中找到的构造。

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

匹配表达式中的模式匹配臂。这些臂的左侧也可以在 let 表达式中找到。

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.

Macros & Attributes

代码生成结构在实际编译发生之前就已扩展。

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.

在声明性宏中的示例 macro_rules!实现这些工作:

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.

Generics & Constraints

Generics combine with many other constructs such as struct S, fn f(), ...

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.

Data Structures

Organizing Code

将项目分割成较小的单元,并最大程度地减少依赖性。

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.

内存结构

Basic Types

字符串

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.

TBD