9/4/23, 10:22 AM The Rust Reference

Introduction
This book is the primary reference for the Rust programming language. It provides three
kinds of material:

Chapters that informally describe each language construct and their use.
Chapters that informally describe the memory model, concurrency model, runtime
services, linkage model, and debugging facilities.
Appendix chapters providing rationale and references to languages that influenced the
design.

⚠️ Warning: This book is incomplete. Documenting everything takes a while. See the
GitHub issues for what is not documented in this book.

Rust releases
Rust has a new language release every six weeks. The first stable release of the language
was Rust 1.0.0, followed by Rust 1.1.0 and so on. Tools ( rustc , cargo , etc.) and
documentation (Standard library, this book, etc.) are released with the language release.

The latest release of this book, matching the latest Rust version, can always be found at
https://doc.rust-lang.org/reference/. Prior versions can be found by adding the Rust version
before the "reference" directory. For example, the Reference for Rust 1.49.0 is located at
https://doc.rust-lang.org/1.49.0/reference/.

What The Reference is not

This book does not serve as an introduction to the language. Background familiarity with the
language is assumed. A separate book is available to help acquire such background
familiarity.

This book also does not serve as a reference to the standard library included in the language
distribution. Those libraries are documented separately by extracting documentation
attributes from their source code. Many of the features that one might expect to be
language features are library features in Rust, so what you're looking for may be there, not
here.

Similarly, this book does not usually document the specifics of rustc as a tool or of Cargo.
rustc has its own book. Cargo has a book that contains a reference. There are a few pages

https://doc.rust-lang.org/reference/print.html 1/428
9/4/23, 10:22 AM The Rust Reference

such as linkage that still describe how rustc works.

This book also only serves as a reference to what is available in stable Rust. For unstable
features being worked on, see the Unstable Book.

Rust compilers, including rustc , will perform optimizations. The reference does not specify
what optimizations are allowed or disallowed. Instead, think of the compiled program as a
black box. You can only probe by running it, feeding it input and observing its output.
Everything that happens that way must conform to what the reference says.

Finally, this book is not normative. It may include details that are specific to rustc itself, and
should not be taken as a specification for the Rust language. We intend to produce such a
book someday, and until then, the reference is the closest thing we have to one.

How to use this book

This book does not assume you are reading this book sequentially. Each chapter generally
can be read standalone, but will cross-link to other chapters for facets of the language they
refer to, but do not discuss.

There are two main ways to read this document.

The first is to answer a specific question. If you know which chapter answers that question,
you can jump to that chapter in the table of contents. Otherwise, you can press s or click
the magnifying glass on the top bar to search for keywords related to your question. For
example, say you wanted to know when a temporary value created in a let statement is
dropped. If you didn't already know that the lifetime of temporaries is defined in the
expressions chapter, you could search "temporary let" and the first search result will take
you to that section.

The second is to generally improve your knowledge of a facet of the language. In that case,
just browse the table of contents until you see something you want to know more about,
and just start reading. If a link looks interesting, click it, and read about that section.

That said, there is no wrong way to read this book. Read it however you feel helps you best.

Conventions

Like all technical books, this book has certain conventions in how it displays information.
These conventions are documented here.

Statements that define a term contain that term in italics. Whenever that term is used
outside of that chapter, it is usually a link to the section that has this definition.

An example term is an example of a term being defined.

https://doc.rust-lang.org/reference/print.html 2/428
9/4/23, 10:22 AM The Rust Reference

Differences in the language by which edition the crate is compiled under are in a
blockquote that start with the words "Edition Differences:" in bold.

Edition Differences: In the 2015 edition, this syntax is valid that is disallowed as
of the 2018 edition.

Notes that contain useful information about the state of the book or point out useful,
but mostly out of scope, information are in blockquotes that start with the word
"Note:" in bold.

Note: This is an example note.

Warnings that show unsound behavior in the language or possibly confusing

interactions of language features are in a special warning box.

⚠️ Warning: This is an example warning.

Code snippets inline in the text are inside <code> tags.

Longer code examples are in a syntax highlighted box that has controls for copying,
executing, and showing hidden lines in the top right corner.

fn main() {
println!("This is a code example");
}

All examples are written for the latest edition unless otherwise stated.

The grammar and lexical structure is in blockquotes with either "Lexer" or "Syntax" in
bold superscript as the first line.

Syntax

ExampleGrammar:
      ~ Expression
   | box Expression

See Notation for more detail.

https://doc.rust-lang.org/reference/print.html 3/428
9/4/23, 10:22 AM The Rust Reference

Contributing
We welcome contributions of all kinds.

You can contribute to this book by opening an issue or sending a pull request to the Rust
Reference repository. If this book does not answer your question, and you think its answer is
in scope of it, please do not hesitate to file an issue or ask about it in the t-lang/doc
stream on Zulip. Knowing what people use this book for the most helps direct our attention
to making those sections the best that they can be. We also want the reference to be as
normative as possible, so if you see anything that is wrong or is non-normative but not
specifically called out, please also file an issue.

https://doc.rust-lang.org/reference/print.html 4/428
9/4/23, 10:22 AM The Rust Reference

Notation

Grammar
The following notations are used by the Lexer and Syntax grammar snippets:

Notation Examples Meaning

KW_IF,
CAPITAL A token produced by the lexer
INTEGER_LITERAL
ItalicCamelCase LetStatement, Item A syntactical production
string x , while , * The exact character(s)
The character represented by this
\x \n, \r, \t, \0
escape

x? pub ? An optional item

x* OuterAttribute* 0 or more of x

x+ MacroMatch+ 1 or more of x

xa..b HEX_DIGIT1..6 a to b repetitions of x

| u8 | u16 , Block | Item Either one or another
[] [b B] Any of the characters listed
[-] [a-z] Any of the characters in the range
~[ ] ~[ b B ] Any characters, except those listed
~ string ~ \n , ~ */ Any characters, except this sequence
() ( , Parameter)? Groups items

String table productions

Some rules in the grammar — notably unary operators, binary operators, and keywords —
are given in a simplified form: as a listing of printable strings. These cases form a subset of
the rules regarding the token rule, and are assumed to be the result of a lexical-analysis
phase feeding the parser, driven by a DFA, operating over the disjunction of all such string
table entries.

When such a string in monospace font occurs inside the grammar, it is an implicit reference
to a single member of such a string table production. See tokens for more information.

https://doc.rust-lang.org/reference/print.html 5/428
9/4/23, 10:22 AM The Rust Reference

Lexical structure

https://doc.rust-lang.org/reference/print.html 6/428
9/4/23, 10:22 AM The Rust Reference

Input format
Rust input is interpreted as a sequence of Unicode code points encoded in UTF-8.

https://doc.rust-lang.org/reference/print.html 7/428
9/4/23, 10:22 AM The Rust Reference

Keywords
Rust divides keywords into three categories:

strict
reserved
weak

Strict keywords
These keywords can only be used in their correct contexts. They cannot be used as the
names of:

Items
Variables and function parameters
Fields and variants
Type parameters
Lifetime parameters or loop labels
Macros or attributes
Macro placeholders
Crates

Lexer:

KW_AS : as
KW_BREAK : break
KW_CONST : const
KW_CONTINUE : continue
KW_CRATE : crate
KW_ELSE : else
KW_ENUM : enum
KW_EXTERN : extern
KW_FALSE : false
KW_FN : fn
KW_FOR : for
KW_IF : if
KW_IMPL : impl
KW_IN : in
KW_LET : let
KW_LOOP : loop
KW_MATCH : match

https://doc.rust-lang.org/reference/print.html 8/428
9/4/23, 10:22 AM The Rust Reference

KW_MOD : mod
KW_MOVE : move
KW_MUT : mut
KW_PUB : pub
KW_REF : ref
KW_RETURN : return
KW_SELFVALUE : self
KW_SELFTYPE : Self
KW_STATIC : static
KW_STRUCT : struct
KW_SUPER : super
KW_TRAIT : trait
KW_TRUE : true
KW_TYPE : type
KW_UNSAFE : unsafe
KW_USE : use
KW_WHERE : where
KW_WHILE : while

The following keywords were added beginning in the 2018 edition.

Lexer 2018+

KW_ASYNC : async
KW_AWAIT : await
KW_DYN : dyn

Reserved keywords
These keywords aren't used yet, but they are reserved for future use. They have the same
restrictions as strict keywords. The reasoning behind this is to make current programs
forward compatible with future versions of Rust by forbidding them to use these keywords.

Lexer

KW_ABSTRACT : abstract
KW_BECOME : become
KW_BOX : box
KW_DO : do
KW_FINAL : final
KW_MACRO : macro
https://doc.rust-lang.org/reference/print.html 9/428
9/4/23, 10:22 AM The Rust Reference

KW_OVERRIDE : override
KW_PRIV : priv
KW_TYPEOF : typeof
KW_UNSIZED : unsized
KW_VIRTUAL : virtual
KW_YIELD : yield

The following keywords are reserved beginning in the 2018 edition.

Lexer 2018+

KW_TRY : try

Weak keywords
These keywords have special meaning only in certain contexts. For example, it is possible to
declare a variable or method with the name union .

macro_rules is used to create custom macros.

union is used to declare a union and is only a keyword when used in a union
declaration.

'static is used for the static lifetime and cannot be used as a generic lifetime
parameter or loop label

// error[E0262]: invalid lifetime parameter name: `'static`

fn invalid_lifetime_parameter<'static>(s: &'static str) -> &'static str { s
}

In the 2015 edition, dyn is a keyword when used in a type position followed by a path
that does not start with :: .

Beginning in the 2018 edition, dyn has been promoted to a strict keyword.

Lexer

KW_MACRO_RULES : macro_rules
KW_UNION : union
KW_STATICLIFETIME : 'static

https://doc.rust-lang.org/reference/print.html 10/428