Crate std

Rust 标准库

Rust 标准库是可移植 Rust 软件的基础，这是一组针对 更广泛的 Rust 生态系统 的最小且经过实战测试的共享抽象。 它提供了核心类型，例如 Vec<T> 和 Option<T>，库定义的对 语言原语 的操作，标准库宏，I/O 和 多线程，以及许多 其他 东西。

默认情况下，std 可用于所有 Rust crates。因此，可以通过 use 语句使用路径 std 来访问标准库，就像在 use std::env 中一样。

如何阅读本文档

如果您已经知道要查找的内容的名称，找到它的最快方法是使用页面顶部的 search bar。

否则，您可能想跳转到以下有用的部分之一：

• std::* modules
• Primitive types
• Standard macros
• The Rust Prelude

如果这是您第一次来，那么标准库的文档可以被随意的阅读。点击有趣的东西通常会把您带到有趣的地方。 尽管如此，您还是不想错过一些重要的内容，因此请继续阅读标准库及其文档！

一旦您熟悉了标准库的内容，您可能会发现冗长的描述会使人分心。在开发阶段，您可能需要按页面顶部附近的 [-] 按钮，将其折叠为更易于阅读的视图。

当您查看 [-] 按钮时，还请注意 source 链接。Rust 的 API 文档附带了源代码，我们鼓励您阅读它。 标准库的资源通常是高质量的，通常可以启发人们对幕后的了解。

标准库文档中有什么？

首先，Rust 标准库分为多个重点 模块，所有的这些模块都会在本页下方列出。这些模块是所有 Rust 锻造的基础，它们具有强大的名称，如 std::slice 和 std::cmp。 模块的文档通常包括模块的概述和示例，是开始熟悉库的好地方。

其次，此处记录了 原始类型 上的隐式方法。造成混淆的原因有两个：

1. 虽然原语是由编译器实现的，但标准库是直接在原始类型上实现方法 (而且它是唯一一个这样做的库)。在 原语 部分中对此进行了说明。
2. 标准库导出了许多模块，这些模块的名称和原始类型的名称相同。它们定义了与原始类型有关的其他项，但没有定义所有重要的方法。

例如，有一个 原始类型为 i32 的页面列出了可以调用的所有方法 32 位整数 (非常有用)，并且有一个 std::i32 模块的页面 记录了常量值 MIN 和 MAX (很少有用)。

请注意原始 str 和 [T] (也称为 ‘slice’) 的文档。String 和 Vec<T> 上许多方法的调用实际上都是通过 解引用强制多态 分别对 str 和 [T] 上的方法的调用。

第三，标准库还定义了 Rust Prelude，这是一小部分项目 - 主要是 traits - 导入到每个 crate 的每个模块中。 prelude 中的 traits 无处不在，这使 prelude 文档成为了解该库的一个很好的切入点。

最后，标准库导出了许多标准宏，并且在 此页面 上列出了它们 (从技术上讲，并不是所有的标准宏都由标准库定义的 - 有些是由编译器定义的 - 但它们在这里的文档是相同的)。

与 prelude 一样，默认情况下会将标准宏导入到所有 crates 中。

对文档的更改做出贡献

在 这里 查看 Rust 贡献指南。 该文档的源代码可以在 GitHub 上找到。 要贡献更改，请确保您先阅读指南，然后为您建议的更改提交拉取请求。

感谢您的贡献！ 如果您看到可以改进的部分文档，请提交 PR，或者先在 Discord #docs 上与我们聊天。

Rust 标准库之旅

crate 文档的其余部分致力于指出 Rust 标准库的显著特性。

容器和集合

option 和 result 模块定义了可选和错误处理类型 Option<T> 和 Result<T, E>。iter 模块定义了 Rust 的迭代器 Iterator trait，它与 for 循环一起工作来访问集合。

标准库公开了三种处理连续内存区域的常用方法：

• Vec<T> - 在运行时可调整大小的堆分配的 vector。
• [T; N] - 在编译时具有固定大小的内联数组。
• [T] - 一个动态大小的切片放入到任何其他类型的连续存储中，无论是否为堆分配。

切片只能通过某种 指针 来处理，因此具有多种形式，例如：

• &[T]- 共享切片
• &mut [T]- 可变切片
• Box<[T]> - 拥有所有权的切片

str，一个 UTF-8 字符串切片，是一种原始类型，标准库为它定义了很多方法。Rust str 通常作为不可变引用来访问: &str。使用拥有所有权的 String 来创建和修改字符串。

要转换为字符串，请使用 format! 宏; 要从字符串转换，请使用 FromStr trait。

可以通过将数据放在引用计数的 Box 或 Rc 类型中来共享数据，并且，如果进一步包含在 Cell 或 RefCell 中，则可以对其进行可变的和共享。 同样，在并发设置中，通常将原子引用计数的 Box Arc 与 Mutex 配合以获得相同的效果。

collections 模块定义了 Map，Set，链表和其他典型的集合类型，包括常见的 HashMap<K, V>。

平台抽象和 I/O

除了基本的数据类型外，标准库还主要关注对通用平台差异的抽象 (尤其是 Windows 和 Unix 派生平台)。

I/O 的常见类型，包括 files、TCP 和 UDP，在 io、fs 和 net 模块中定义。

thread 模块包含了 Rust 的线程抽象。sync 包含更多的原始共享内存类型，包括 atomic 和 mpsc，其中包含用于消息传递的通道类型。

Primitive Types

• neverExperimental
  ! 类型，也称为 “never”。
• array
  一个固定大小的数组，表示为 [T; N]，用于元素类型 T 和非负编译时常量大小 N。
• bool
  布尔类型。
• char
  一个字符类型。
• f32
  32 位浮点类型 (特别是 IEEE 754-2008 中定义的 “binary32” 类型)。
• f64
  64 位浮点类型 (特别是 IEEE 754-2008 中定义的 “binary64” 类型)。
• fn
  函数指针，例如 fn(usize) -> bool。
• i8
  8 位带符号整数类型。
• i16
  16 位带符号整数类型。
• i32
  32 位带符号整数类型。
• i64
  64 位带符号整数类型。
• i128
  128 位带符号整数类型。
• isize
  指针大小的有符号整数类型。
• pointer
  原始的、不安全的指针 *const T 和 *mut T。
• reference
  参考，&T 和 &mut T。
• slice
  一个动态大小的视图到一个连续的序列，[T]。 这里的连续意味着元素的布局应使每个元素与其相邻元素之间的距离相同。
• str
  字符串切片。
• tuple
  一个有限异构序列，(T, U, ..)。
• u8
  8 位无符号整数类型。
• u16
  16 位无符号整数类型。
• u32
  32 位无符号整数类型。
• u64
  64 位无符号整数类型。
• u128
  128 位无符号整数类型。
• unit
  () 类型，也称为 “unit”。
• usize
  指针大小的无符号整数类型。

Modules

• assert_matchesExperimental
  Unstable 模块包含不稳定的 assert_matches 宏。
• async_iterExperimental
  可组合的异步迭代。
• intrinsicsExperimental
  编译器内部函数。
• simdExperimental
  便携式 SIMD 模块。
• alloc
  内存分配 API。
• any
  用于动态类型或类型反射的实用工具。
• arch
  SIMD 和供应商内部功能模块。
• array
  数组原始类型的实用工具。
• ascii
  对 ASCII 字符串和字符的操作。
• backtrace
  支持捕获 OS 线程的栈回溯
• borrow
  用于处理借用数据的模块。
• boxed
  用于堆分配的 Box<T> 类型。
• cell
  可共享的可变容器。
• char
  char 原始类型的实用工具。
• clone
  不能隐式复制的类型的 Clone trait。
• cmp
  用于比较和排序值的实用工具。
• collections
  集合类型。
• convert
  用于类型之间的转换 traits。
• default
  Default trait 用于具有默认值的类型。
• env
  检查和操作进程的环境。
• error
  处理错误的接口。
• f32
  f32 单精度浮点类型的常量。
• f64
  f64 双精度浮点类型的常量。
• ffi
  与 FFI 绑定有关的实用工具。
• fmt
  用于格式化和打印 Strings 的实用工具。
• fs
  文件系统操作
• future
  异步基本功能。
• hash
  通用哈希支持。
• hint
  对编译器的提示，该提示会影响应如何发出或优化代码。 提示可能是编译时或运行时。
• i8Deprecation planned
  i8 primitive type 的冗余常量模块。
• i16Deprecation planned
  i16 primitive type 的冗余常量模块。
• i32Deprecation planned
  i32 primitive type 的冗余常量模块。
• i64Deprecation planned
  i64 primitive type 的冗余常量模块。
• i128Deprecation planned
  i128 primitive type 的冗余常量模块。
• io
  核心 I/O 功能的 Traits，帮助程序和类型定义。
• isizeDeprecation planned
  isize primitive type 的冗余常量模块。
• iter
  可组合的外部迭代。
• marker
  代表类型基本属性的原始 traits 和类型。
• mem
  处理内存的基本函数。
• net
  TCP/UDP 通信的网络原语。
• num
  数字的附加功能。
• ops
  可重载的运算符。
• option
  可选值。
• os
  特定于操作系统的功能。
• panic
  标准库中的 Panic 支持。
• path
  跨平台路径操作。
• pin
  键入将数据固定到其在内存中的位置的类型。
• prelude
  Rust Prelude
• primitive
  此模块重导出原始类型，以允许使用可能不会被其他声明的类型隐藏的类型。
• process
  用于处理进程的模块。
• ptr
  通过裸指针手动管理内存。
• rc
  单线程引用计数指针。Rc 代表引用计数。
• result
  Result 类型的错误处理。
• slice
  切片原始类型的实用工具。
• str
  str 原始类型的实用工具。
• string
  一个 UTF-8 编码的可增长字符串。
• sync
  有用的同步原语。
• task
  类型和 Traits 用于处理异步任务。
• thread
  原生线程。
• time
  时间量化。
• u8Deprecation planned
  u8 primitive type 的冗余常量模块。
• u16Deprecation planned
  u16 primitive type 的冗余常量模块。
• u32Deprecation planned
  u32 primitive type 的冗余常量模块。
• u64Deprecation planned
  u64 primitive type 的冗余常量模块。
• u128Deprecation planned
  u128 primitive type 的冗余常量模块。
• usizeDeprecation planned
  usize primitive type 的冗余常量模块。
• vec
  具有堆已分配内容的连续可增长数组类型，写为 Vec<T>。

Macros

• concat_bytesExperimental
  将字面量连接成字节切片。
• concat_identsExperimental
  将标识符串联为一个标识符。
• const_format_argsExperimental
  与 format_args 相同，但可以在某些 const 上下文中使用。
• format_args_nlExperimental
  与 format_args 相同，但最后添加了一个换行符。
• log_syntaxExperimental
  将传递的 tokens 打印到标准输出中。
• trace_macrosExperimental
  启用或禁用用于调试其他宏的跟踪功能。
• assert
  声明在运行时布尔表达式为 true。
• assert_eq
  断言两个表达式彼此相等 (使用 PartialEq)。
• assert_ne
  断言两个表达式彼此不相等 (使用 PartialEq)。
• cfg
  在编译时评估配置标志的布尔组合。
• column
  扩展到调用它的列号。
• compile_error
  导致编译失败，并遇到给定的错误消息。
• concat
  将字面量串联成一个静态字符串切片。
• dbg
  打印并返回给定表达式的值，以进行快速而肮脏的调试。
• debug_assert
  声明在运行时布尔表达式为 true。
• debug_assert_eq
  断言两个表达式彼此相等。
• debug_assert_ne
  断言两个表达式彼此不相等。
• env
  在编译时检查环境变量。
• eprint
  打印到标准错误。
• eprintln
  使用换行符打印到标准错误。
• file
  扩展为调用该文件的文件名。
• format
  使用运行时表达式的插值创建 String。
• format_args
  构造其他字符串格式宏的参数。
• include
  根据上下文将文件解析为表达式或项。
• include_bytes
  包含一个文件作为对字节数组的引用。
• include_str
  包含 UTF-8 编码的文件作为字符串。
• is_x86_feature_detectedx86 or x86-64
  一个在运行时测试 x86/x86-64 平台上是否具有 CPU 特性的宏。
• line
  扩展为在其上被调用的行号。
• matches
  返回给定表达式是否与任何给定模式匹配。
• module_path
  扩展为代表当前模块路径的字符串。
• option_env
  (可选) 在编译时检查环境变量。
• panic
  让当前线程 panics。
• print
  打印到标准输出。
• println
  使用换行符打印到标准输出。
• stringify
  对其参数进行字符串化。
• thread_local
  声明一个新的 std::thread::LocalKey 类型的线程本地存储密钥。
• todo
  表示未完成的代码。
• tryDeprecated
  解开结果或传播其错误。
• unimplemented
  通过 panic 并带有 “not implemented” 的消息来指示未实现的代码。
• unreachable
  表示无法访问的代码。
• vec
  创建一个包含参数的 Vec。
• write
  将格式化的数据写入缓冲区。
• writeln
  将格式化的数据写入到缓冲区，并追加一个换行符。

Keywords

• SelfTy
  trait 或 impl 块中的实现类型，或类型定义中的当前类型。
• as
  在类型之间进行转换，或重命名导入。
• async
  返回 Future，而不是阻塞当前线程。
• await
  暂停执行，直到 Future 的结果准备就绪为止。
• break
  从循环中提前退出。
• const
  编译时常量、编译时可评估函数和裸指针。
• continue
  跳到循环的下一个迭代。
• crate
  Rust 二进制或库。
• dyn
  dyn 是 trait 对象 类型的前缀。
• else
  if 条件评估为 false 时要评估的表达式。
• enum
  一种类型，可以是几种变体中的任何一种。
• extern
  链接到或导入外部代码。
• false
  bool 类型的值，表示逻辑 false。
• fn
  一个函数或函数指针。
• for
  使用 in 进行迭代，使用 impl 或 更高等级的 trait bounds (for<'a>) 实现 trait。
• if
  如果条件成立，则评估一个块。
• impl
  为类型实现一些功能。
• in
  使用 for 迭代一系列值。
• let
  将值绑定到变量。
• loop
  无限循环。
• match
  基于模式匹配的控制流。
• mod
  将代码整理到 模块 中。
• move
  按值捕获 闭包 的环境。
• mut
  可变变量，引用或指针。
• pub
  使项对其他人可见。
• ref
  在模式匹配期间通过引用绑定。
• return
  从函数返回一个值。
• self
  方法的接收者，或当前模块。
• static
  静态项是在程序的整个持续时间内有效的值 ('static 生命周期)。
• struct
  由其他类型组成的类型。
• super
  当前 模块 的父级。
• trait
  一组类型的通用接口。
• true
  bool 类型的值，表示逻辑 true。
• type
  为现有类型定义别名。
• union
  Rust 等价于 c 风格的 union。
• unsafe
  类型系统无法验证其 内存安全 的代码或接口。
• use
  从其他 crates 或模块导入或重命名项。
• where
  添加使用项必须坚持的约束。
• while
  保持条件时循环播放。