Rust Documentation

Welcome to an overview of the documentation provided by the Rust project. All of these projects are managed by the Docs Team; there are other unofficial documentation resources as well!

欢迎阅读Rust项目提供的文档概述。所有这些项目均由文档小组管理; 还有其他非官方的文档资源！

Many of these resources take the form of "books"; we collectively call these "The Rust Bookshelf." Some are large, some are small.

其中许多资源采用书籍的形式; 我们统称这些Rust书架。有些很大，有些很小。

1 Learn Rust

If you'd like to learn Rust, this is the spot for you! All of these resources assume that you have programmed before, but not in any specific language:

如果您想学习Rust，这是您的最佳选择！所有这些资源都假定您之前编程过，但没有使用任何特定语言。

1.1 The Rust Programming Language

Affectionately nicknamed "the book," The Rust Programming Language will give you an overview of the language from first principles. You'll build a few projects along the way, and by the end, you'll have a solid grasp of the language.

亲切地昵称为基础书 ，Rust编程语言将从第一原理为您提供语言概述。您将在此过程中构建一些项目，最后，您将对语言有一个扎实的掌握。

The 2018 edition of the book is an online "living version" of the book; based on the second edition. This online book is updated as Rust updates. If you're not sure what edition of the book to read, you should prefer this edition.

You can find the 2018 edition here.

该书的2018年版是该书的在线生活版本，基于第二版。此在线书籍更新为Rust更新。如果你不确定要阅读哪本书的版本，你应该更喜欢这个版本。

1.2 Rust By Example

If reading multiple hundreds of pages about a language isn't your style, then Rust By Example has you covered. While the book talks about code with a lot of words, RBE shows off a bunch of code, and keeps the talking to a minimum. It also includes exercises!

如果阅读有关某种语言的数百页不是你的风格，那么 Rust By Example就可以了。虽然这本书谈论了很多基础的代码，但RBE展示了一堆代码，并将谈话保持在最低限度，它还包括练习！

Rust is a modern systems programming language focusing on safety, speed, and concurrency. It accomplishes these goals by being memory safe without using garbage collection. Rust by Example (RBE) is a collection of runnable examples that illustrate various Rust concepts and standard libraries. To get even more out of these examples, don't forget to install Rust locally and check out the official docs. Additionally for the curious, you can also check out the source code for this site.

Rust是一种现代系统编程语言，专注于安全性，速度和并发性。它通过保持内存安全而不使用垃圾收集来实现这些目标。Rust by Example（RBE）是一个可运行的示例集合，用于说明各种Rust概念和标准库。要从这些示例中获得更多信息，请不要忘记在本地安装Rust并查看官方文档。此外，对于好奇，您还可以查看此站点的源代码。

2 Use Rust

Once you've gotten familliar with the language, these resources can help you when you're actually using it day-to-day.

一旦你熟悉了这门语言，这些资源可以帮助你在日常实际使用它时。

2.1 The Standard Library

Rust's standard library has extensive API documentation, with explanations of how to use various things, as well as example code for accomplishing various tasks.

Rust的标准库具有丰富的API文档，包含如何使用各种内容的说明，以及用于完成各种任务的示例代码。

The Rust Standard Library is the foundation of portable Rust software, a set of minimal and battle-tested shared abstractions for the broader Rust ecosystem. It offers core types, like Vec and Option, library-defined operations on language primitives, standard macros, I/O and multithreading, among many other things.

std is available to all Rust crates by default, just as if each one contained an extern crate std; import at the crate root. Therefore the standard library can be accessed in use statements through the path std, as in use std::env, or in expressions through the absolute path::std, as in::std::env::args.

Rust标准库是便携式Rust软件的基础，这是一套针对更广泛的Rust生态系统的最小和经过实战考验的共享抽象。它提供了核心类型，如Vec <T>和Option <T>，语言基元上的库定义操作，标准宏，I/O和多线程等等。

std默认情况下可用于所有Rust包，就好像每个文件开始包含一个extern crate std。因此，可以通过路径std在use语句中访问标准库，如使用std::env，或通过absolute path::std在表达式中访问，和in::std::env::args一样效果。

Primitive Types

name	instruction
array	A fixed-size array, denoted [T; N], for the element type, T, and the non-negative compile-time constant size, N.
bool	The boolean type.
char	A character type.
f32	The 32-bit floating point type.
f64	The 64-bit floating point type.
fn	Function pointers, like fn(usize) -> bool.
i8	The 8-bit signed integer type.
i16	The 16-bit signed integer type.
i32	The 32-bit signed integer type.
i64	The 64-bit signed integer type.
i128	The 128-bit signed integer type.
isize	The pointer-sized signed integer type.
never	The ! type, also called "never".
pointer	Raw, unsafe pointers, *const T, and *mut T.
reference	References, both shared and mutable.
slice	A dynamically-sized view into a contiguous sequence, [T].
str	String slices.
tuple	A finite heterogeneous sequence, (T, U, ..).
u8	The 8-bit unsigned integer type.
u16	The 16-bit unsigned integer type.
u32	The 32-bit unsigned integer type.
u64	The 64-bit unsigned integer type.
u128	The 128-bit unsigned integer type.
unit	The () type, sometimes called "unit" or "nil".
usize	The pointer-sized unsigned integer type.

Modules

name	instruction
alloc	Memory allocation APIs
any	This module implements the Any trait, which enables dynamic typing of any 'static type through runtime reflection.
arch	SIMD and vendor intrinsics module.
ascii	Operations on ASCII strings and characters.
borrow	A module for working with borrowed data.
boxed	A pointer type for heap allocation.
cell	Shareable mutable containers.
char	A character type.
clone	The Clone trait for types that cannot be 'implicitly copied'.
cmp	Functionality for ordering and comparison.
collections	Collection types.
convert	Traits for conversions between types.
default	The Default trait for types which may have meaningful default values.
env	Inspection and manipulation of the process's environment.
error	Traits for working with Errors.
f32	This module provides constants which are specific to the implementation of the f32 floating point data type.
f64	This module provides constants which are specific to the implementation of the f64 floating point data type.
ffi	Utilities related to FFI bindings.
fmt	Utilities for formatting and printing Strings.
fs	Filesystem manipulation operations.
hash	Generic hashing support.
hint	Hints to compiler that affects how code should be emitted or optimized.
i8	The 8-bit signed integer type.
i16	The 16-bit signed integer type.
i32	The 32-bit signed integer type.
i64	The 64-bit signed integer type.
i128	The 128-bit signed integer type.
io	Traits, helpers, and type definitions for core I/O functionality.
isize	The pointer-sized signed integer type.
iter	Composable external iteration.
marker	Primitive traits and types representing basic properties of types.
mem	Basic functions for dealing with memory.
net	Networking primitives for TCP/UDP communication.
num	Additional functionality for numerics.
ops	Overloadable operators.
option	Optional values.
os	OS-specific functionality.
panic	Panic support in the standard library.
path	Cross-platform path manipulation.
prelude	The Rust Prelude.
process	A module for working with processes.
ptr	Raw, unsafe pointers, *const T, and *mut T.
rc	Single-threaded reference-counting pointers. 'Rc' stands for 'Reference Counted'.
result	Error handling with the Result type.
slice	A dynamically-sized view into a contiguous sequence, [T].
str	Unicode string slices.
string	A UTF-8 encoded, growable string.
sync	Useful synchronization primitives.
thread	Native threads.
time	Temporal quantification.
u8	The 8-bit unsigned integer type.
u16	The 16-bit unsigned integer type.
u32	The 32-bit unsigned integer type.
u64	The 64-bit unsigned integer type.
u128	The 128-bit unsigned integer type.
usize	The pointer-sized unsigned integer type.
vec	A contiguous growable array type with heap-allocated contents, written Vec.
future	[Experimental] Asynchronous values.
intrinsics	[Experimental] rustc compiler intrinsics.
raw	[Experimental] Contains struct definitions for the layout of compiler built-in types.
task	[Experimental] Types and Traits for working with asynchronous tasks.

Macros

name	instruction
assert	Ensure that a boolean expression is true at runtime.
assert_eq	Asserts that two expressions are equal to each other (using PartialEq).
assert_ne	Asserts that two expressions are not equal to each other (using PartialEq).
cfg	Boolean evaluation of configuration flags, at compile-time.
column	A macro which expands to the column number on which it was invoked.
compile_error	Unconditionally causes compilation to fail with the given error message when encountered.
concat	Concatenates literals into a static string slice.
debug_assert	Ensure that a boolean expression is true at runtime.
debug_assert_eq	Asserts that two expressions are equal to each other.
debug_assert_ne	Asserts that two expressions are not equal to each other.
env	Inspect an environment variable at compile time.
eprint	Macro for printing to the standard error.
eprintln	Macro for printing to the standard error, with a newline.
file	A macro which expands to the file name from which it was invoked.
format	Creates a String using interpolation of runtime expressions.
format_args	The core macro for formatted string creation & output.
include	Parse a file as an expression or an item according to the context.
include_bytes	Includes a file as a reference to a byte array.
include_str	Includes a utf8-encoded file as a string.
is_x86_feature_detected	A macro to test at runtime whether a CPU feature is available on x86/x86-64 platforms.
line	A macro which expands to the line number on which it was invoked.
module_path	Expands to a string that represents the current module path.
option_env	Optionally inspect an environment variable at compile time.
panic	The entry point for panic of Rust threads.
print	Macro for printing to the standard output.
println	Macro for printing to the standard output, with a newline.
stringify	A macro which stringifies its arguments.
thread_local	Declare a new thread local storage key of type std::thread::LocalKey.
try	Helper macro for reducing boilerplate code for matching Result together with converting downstream errors.
unimplemented	A standardized placeholder for marking unfinished code.
unreachable	A utility macro for indicating unreachable code.
vec	Creates a Vec containing the arguments.
write	Write formatted data into a buffer.
writeln	Write formatted data into a buffer, with a newline appended.
await	[Experimental]
concat_idents	[Experimental] Concatenate identifiers into one identifier.
is_aarch64_feature_detected	[Experimental]
is_arm_feature_detected	[Experimental]
is_mips64_feature_detected	[Experimental]
is_mips_feature_detected	[Experimental]
is_powerpc64_feature_detected	[Experimental]
is_powerpc_feature_detected	[Experimental]
select	[Experimental] A macro to select an event from a number of receivers.

2.2 The Rustc Book

The Rustc Book describes the Rust compiler, rustc.

Rustc Book描述了Rust编译器rustc。

This book can help you understand what each of these options does. Additionally, while most Rustaceans use Cargo, not all do: sometimes they integrate rustc into other build systems. This book should provide a guide to all of the options you'd need to do so.

本书可以帮助您了解每个选项的作用。此外，虽然大多数Rustaceans使用Cargo。但并非所有人都这样做，有时他们将rustc整合到其他构建系统中，本书应提供您需要执行此操作的所有选项的指南。

2.3 The Cargo Book

The Cargo Book is a guide to Cargo, Rust's build tool and dependency manager.

Cargo Book是Rust的构建工具和依赖管理器的指南。

Cargo is the Rust package manager. Cargo downloads your Rust project's dependencies, compiles your project, makes packages, and upload them to crates.io, the Rust community’s package registry. You can contribute to this book on GitHub.

Cargo是Rust包管理器。 Cargo下载您的Rust项目的依赖项，编译您的项目，生成包，并将它们上传到Rust社区的包注册表crates.io。您可以在GitHub上为本书做出贡献。

2.4 The Rustdoc Book

The Rustdoc Book describes our documentation tool, rustdoc.

Rustdoc Book描述了我们的文档工具rustdoc。

The standard Rust distribution ships with a tool called rustdoc. Its job is to generate documentation for Rust projects. On a fundamental level, Rustdoc takes as an argument either a crate root or a Markdown file, and produces HTML, CSS, and JavaScript.

标准的Rust发行版附带了一个名为rustdoc的工具。它的工作是为Rust项目生成文档。在基础层面上，Rustdoc将crate root或Markdown文件作为参数，并生成HTML，CSS和JavaScript。

2.5 Extended Error Listing

Many of Rust's errors come with error codes, and you can request extended diagnostics from the compiler on those errors. You can also read them here, if you prefer to read them that way.

Rust的许多错误都带有错误代码，您可以请求编译器对这些错误进行扩展诊断。如果你喜欢直接阅读它们，你也可以在这里阅读它们E0001 -- E0702。

3 Master Rust

Once you're quite familiar with the language, you may find these advanced resources useful.

3.1 The Reference

The Reference is not a formal spec, but is more detailed and comprehensive than the book.

Reference不是一个正式的规范，但比书更详细和全面。

This document 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.

本文档是Rust编程语言的主要参考，它提供三个部分内容：

• 非正式描述每种语言结构及其用法的章节。
• 非正式描述内存模型，并发模型，运行时服务，链接模型和调试工具的章节。
• 附录章节提供了影响设计的语言的基本原理和参考。

3.2 The Rustonomicon

The Rustonomicon is your guidebook to the dark arts of unsafe Rust. It's also sometimes called "the 'nomicon."

Rustonomicon是您不安全的Rust黑暗艺术的指南。它有时也被称为'nomicon'。

Should you wish a long and happy career of writing Rust programs, you should turn back now and forget you ever saw this book. It is not necessary. However if you intend to write unsafe code — or just want to dig into the guts of the language — this book contains lots of useful information.

你是否希望在编写Rust程序方面有一个漫长而愉快的职业生涯，你现在应该回过头来忘记你曾经看过这本书，没有必要看本篇内容。但是，如果您打算编写不安全的代码 - 或者只是想深入研究语言的内容 - 本书包含许多有用的信息。

3.3 The Unstable Book

The Unstable Book has documentation for unstable features.

This book consists of a number of chapters, each one organized by a "feature flag." That is, when using an unstable feature of Rust, you must use a flag, like this:#![feature(box_syntax)]The box_syntax feature has a chapter describing how to use it.

#![feature(box_syntax)]

fn main() {
   // let five1 = Box::new(5); old use
   let five2 = box 5;// use feature
}

欢迎来到不稳定的书！本书由许多章组成，每章由特征标志组织。也就是说，当使用Rust的不稳定特性时，必须使用标志，如下所示#![feature(box_syntax)]，该box_syntax功能有一章描述了如何使用它。