//! # Rust 标准库
//!
//! Rust 标准库是可移植 Rust 软件的基础，这是一组针对 [更广泛的 Rust 生态系统][crates.io] 的最小且经过实战测试的共享抽象。
//! 它提供了核心类型，例如 [`Vec<T>`] 和 [`Option<T>`]，库定义的对 [语言原语](#primitives) 的操作，[标准库宏](#macros)，[I/O] 和 [多线程][multithreading]，以及许多 [其他][other] 东西。
//!
//! `std` 默认情况下可用于所有的 Rust crates。因此，可以通过 [`use`] 语句使用路径 `std` 来访问标准库，就像在 [`use std::env`] 中一样。
//!
//! # 如何阅读本文档
//!
//! 如果您已经知道要查找的内容的名称，最快的查找方法是使用页面顶部的 <a href="#" onclick="focusSearchBar();">搜索栏</a>。
//!
//! 否则，您可能想跳转到以下有用的部分之一:
//!
//! * [`std::*` modules](#modules)
//! * [Primitive types](#primitives)
//! * [Standard macros](#macros)
//! * [The Rust Prelude]
//!
//! 如果这是您第一次来，那么标准库的文档可以被随意的阅读。点击有趣的东西通常会把您带到有趣的地方。
//! 尽管如此，您还是不想错过一些重要的内容，因此请继续阅读标准库及其文档!
//!
//! 一旦您熟悉了标准库的内容，您可能会发现冗长的描述会使人分心。在开发阶段，您可能需要按页面顶部附近的 `[-]` 按钮，将其折叠为更易于阅读的视图。
//!
//! 当您看到 `[-]` 按钮的时候，也请注意 `[src]` 按钮。Rust 的 API 文档附带了源代码，我们鼓励您阅读它。
//! 标准库的资源通常是高质量的，通常可以启发人们对幕后的了解。
//!
//! # 标准库文档中有什么?
//!
//! 首先，Rust 标准库分为多个重点 [模块](#modules)，所有的这些模块都会在本页下方列出。这些模块是所有 Rust 锻造的基础，它们具有强大的名称，如 [`std::slice`] 和 [`std::cmp`]。
//! 模块的文档通常包括模块的概述和示例，是开始熟悉库的好地方。
//!
//! 其次，此处记录了 [primitive types] 上的隐式方法。造成混淆的原因有两个:
//!
//! 1. 虽然原语是由编译器实现的，但标准库是直接在原语类型上实现方法 (而且它是唯一一个这样做的库)。在 [原语](#primitives) 部分中对此进行了说明。
//! 2. 标准库导出了许多模块，这些模块的名称和原始类型的名称相同。它们定义了与原始类型有关的其他项，但没有定义所有重要的方法。
//!
//! 例如，有一个 [基本类型为 `i32`](primitive::i32) 的页面列出了可以调用的所有方法
//! 32 位整数 (非常有用)，并且有一个 [page for the module `std::i32`] 记录了常量值 [`MIN`] 和 [`MAX`] (很少有用)。
//!
//! 请注意原始 [`str`] 和 [`[T]`][prim@slice] (也称为 'slice') 的文档。[`String`] 和 [`Vec<T>`] 上许多方法的调用实际上都是通过 [解引用强制多态][deref-coercions] 分别对 [`str`] 和 [`[T]`][prim@slice] 上的方法的调用。
//!
//! 第三，标准库还定义了 [The Rust Prelude]，这是一小部分项目 - 主要是 traits - 导入到每个 crate 的每个模块中。
//! prelude 中的 traits 无处不在，这使 prelude 文档成为了解该库的一个很好的切入点。
//!
//! 最后，标准库导出了许多标准宏，并且在 [此页面](#macros) 上列出了它们 (从技术上讲，并不是所有的标准宏都由标准库定义的 - 有些是由编译器定义的 - 但它们在这里的文档是相同的)。
//!
//! 与 prelude 一样，默认情况下会将标准宏导入到所有 crates 中。
//!
//! # 对文档的更改做出贡献
//!
//! 在 [这里](https://rustc-dev-guide.rust-lang.org/contributing.html#writing-documentation) 查看 Rust 贡献指南。
//! 该文档的源代码可以在 [GitHub](https://github.com/rust-lang/rust) 上找到。
//! 要贡献更改，请确保您先阅读指南，然后为您建议的更改提交拉取请求。
//!
//! 感谢您的贡献! 如果您看到可以改进的部分文档，请提交 PR，或者先在 [Discord][rust-discord] #docs 上与我们聊天。
//!
//! # Rust 标准库之旅
//!
//! crate 文档的其余部分致力于指出 Rust 标准库的显著特性。
//!
//! ## 容器和集合
//!
//! [`option`] 和 [`result`] 模块定义了可选和错误处理类型 [`Option<T>`] 和 [`Result<T, E>`]。[`iter`] 模块定义了 Rust 的迭代器 trait [`Iterator`]，它与 [`for`] 循环一起工作来访问集合。
//!
//! 标准库公开了三种处理连续内存区域的常用方法:
//!
//! * [`Vec<T>`] - 在运行时可调整大小的堆分配的 *vector*。
//! * [`[T; N]`][prim@array] - 在编译时具有固定大小的内联 *数组*。
//! * [`[T]`][prim@slice] - 动态调整大小的 *切片* 到任何其他类型的连续存储中，无论是否进行了堆分配。
//!
//! 切片只能通过某种 *指针* 来处理，因此具有多种形式，例如:
//!
//! * `&[T]` - *共享切片*
//! * `&mut [T]` - *可变切片*
//! * [`Box<[T]>`][owned slice] - *拥有 (所有权) 的切片*
//!
//! [`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`]，其中包含用于消息传递的通道类型。
//!
//! [I/O]: io
//! [`MIN`]: i32::MIN
//! [`MAX`]: i32::MAX
//! [page for the module `std::i32`]: crate::i32
//! [TCP]: net::TcpStream
//! [The Rust Prelude]: prelude
//! [UDP]: net::UdpSocket
//! [`Arc`]: sync::Arc
//! [owned slice]: boxed
//! [`Cell`]: cell::Cell
//! [`FromStr`]: str::FromStr
//! [`HashMap<K, V>`]: collections::HashMap
//! [`Mutex`]: sync::Mutex
//! [`Option<T>`]: option::Option
//! [`Rc`]: rc::Rc
//! [`RefCell`]: cell::RefCell
//! [`Result<T, E>`]: result::Result
//! [`Vec<T>`]: vec::Vec
//! [`atomic`]: sync::atomic
//! [`for`]: ../book/ch03-05-control-flow.html#looping-through-a-collection-with-for
//! [`str`]: prim@str
//! [`mpsc`]: sync::mpsc
//! [`std::cmp`]: cmp
//! [`std::slice`]: mod@slice
//! [`use std::env`]: env/index.html
//! [`use`]: ../book/ch07-02-defining-modules-to-control-scope-and-privacy.html
//! [crates.io]: https://crates.io
//! [deref-coercions]: ../book/ch15-02-deref.html#implicit-deref-coercions-with-functions-and-methods
//! [files]: fs::File
//! [multithreading]: thread
//! [other]: #what-is-in-the-standard-library-documentation
//! [primitive types]: ../book/ch03-02-data-types.html
//! [rust-discord]: https://discord.gg/rust-lang
//! [array]: prim@array
//! [slice]: prim@slice
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
#![cfg_attr(not(feature = "restricted-std"), stable(feature = "rust1", since = "1.0.0"))]
#![cfg_attr(feature = "restricted-std", unstable(feature = "restricted_std", issue = "none"))]
#![doc(
    html_playground_url = "https://play.rust-lang.org/",
    issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/",
    test(no_crate_inject, attr(deny(warnings))),
    test(attr(allow(dead_code, deprecated, unused_variables, unused_mut)))
)]
// 不要链接到 std。我们是 std。
#![no_std]
#![warn(deprecated_in_future)]
#![warn(missing_docs)]
#![warn(missing_debug_implementations)]
#![allow(explicit_outlives_requirements)]
#![allow(unused_lifetimes)]
// 告诉编译器链接到 panic_abort 或 panic_unwind
#![needs_panic_runtime]
// std 可能以特定于平台的方式使用特性
#![allow(unused_features)]
#![feature(rustc_allow_const_fn_unstable)]
#![cfg_attr(
    test,
    feature(internal_output_capture, print_internals, update_panic_count, thread_local_const_init)
)]
#![cfg_attr(
    all(target_vendor = "fortanix", target_env = "sgx"),
    feature(slice_index_methods, coerce_unsized, sgx_platform)
)]
#![deny(rustc::existing_doc_keyword)]
// std 实现了不稳定的特性，其中许多是永远不会稳定的内部编译器细节
//
// NB: 对下面的列表排序是为了最大限度地减少合并冲突。
#![feature(alloc_error_handler)]
#![feature(alloc_layout_extra)]
#![feature(allocator_api)]
#![feature(allocator_internals)]
#![feature(allow_internal_unsafe)]
#![feature(allow_internal_unstable)]
#![feature(arbitrary_self_types)]
#![feature(array_error_internals)]
#![feature(asm)]
#![feature(assert_matches)]
#![feature(associated_type_bounds)]
#![feature(async_stream)]
#![feature(atomic_mut_ptr)]
#![feature(auto_traits)]
#![feature(bench_black_box)]
#![feature(box_syntax)]
#![feature(c_variadic)]
#![feature(cfg_accessible)]
#![feature(cfg_eval)]
#![feature(cfg_target_has_atomic)]
#![feature(cfg_target_thread_local)]
#![feature(char_error_internals)]
#![feature(char_internals)]
#![feature(concat_idents)]
#![feature(const_cstr_unchecked)]
#![feature(const_fn_floating_point_arithmetic)]
#![feature(const_fn_fn_ptr_basics)]
#![feature(const_fn_transmute)]
#![feature(const_io_structs)]
#![feature(const_ip)]
#![feature(const_ipv4)]
#![feature(const_ipv6)]
#![feature(const_raw_ptr_deref)]
#![feature(const_socketaddr)]
#![feature(container_error_extra)]
#![feature(core_intrinsics)]
#![feature(custom_test_frameworks)]
#![feature(decl_macro)]
#![feature(doc_cfg)]
#![feature(doc_keyword)]
#![feature(doc_masked)]
#![feature(doc_notable_trait)]
#![feature(dropck_eyepatch)]
#![feature(duration_checked_float)]
#![feature(duration_constants)]
#![feature(edition_panic)]
#![feature(exact_size_is_empty)]
#![feature(exhaustive_patterns)]
#![feature(extend_one)]
#![feature(float_interpolation)]
#![feature(fn_traits)]
#![feature(format_args_nl)]
#![feature(gen_future)]
#![feature(generator_trait)]
#![feature(get_mut_unchecked)]
#![feature(global_asm)]
#![feature(hashmap_internals)]
#![feature(int_error_internals)]
#![feature(integer_atomics)]
#![feature(int_log)]
#![feature(into_future)]
#![feature(intra_doc_pointers)]
#![feature(iter_zip)]
#![feature(lang_items)]
#![feature(linkage)]
#![feature(llvm_asm)]
#![feature(log_syntax)]
#![feature(map_try_insert)]
#![feature(maybe_uninit_extra)]
#![feature(maybe_uninit_slice)]
#![feature(maybe_uninit_uninit_array)]
#![feature(min_specialization)]
#![feature(needs_panic_runtime)]
#![feature(negative_impls)]
#![feature(never_type)]
#![feature(new_uninit)]
#![feature(nll)]
#![feature(nonnull_slice_from_raw_parts)]
#![feature(once_cell)]
#![feature(panic_info_message)]
#![feature(panic_internals)]
#![feature(panic_unwind)]
#![feature(pin_static_ref)]
#![feature(prelude_import)]
#![feature(ptr_internals)]
#![feature(ready_macro)]
#![feature(rustc_attrs)]
#![feature(rustc_private)]
#![feature(shrink_to)]
#![feature(slice_concat_ext)]
#![feature(slice_internals)]
#![feature(slice_ptr_get)]
#![feature(slice_ptr_len)]
#![feature(staged_api)]
#![feature(std_internals)]
#![feature(stdsimd)]
#![feature(stmt_expr_attributes)]
#![feature(str_internals)]
#![feature(test)]
#![feature(thread_local)]
#![feature(thread_local_internals)]
#![feature(toowned_clone_into)]
#![feature(total_cmp)]
#![feature(trace_macros)]
#![feature(try_blocks)]
#![feature(try_reserve)]
#![feature(unboxed_closures)]
#![feature(unsafe_cell_raw_get)]
#![feature(unwind_attributes)]
#![feature(unwrap_infallible)]
#![feature(vec_into_raw_parts)]
#![feature(vec_spare_capacity)]
// NB: 对上面的列表排序是为了最大限度地减少合并冲突。
#![default_lib_allocator]

// 显式导入 prelude。
// 在构建依赖于 std 的 crates 时，编译器使用此不稳定属性来隐式导入 prelude。
#[prelude_import]
#[allow(unused)]
use prelude::v1::*;

// 访问 Bencher 等
#[cfg(test)]
extern crate test;

#[allow(unused_imports)] // 并非所有平台都使用来自 `alloc` 的宏
#[macro_use]
extern crate alloc as alloc_crate;
#[doc(masked)]
#[allow(unused_extern_crates)]
extern crate libc;

// 当前，我们总是需要一个 unwinder 来回溯
#[doc(masked)]
#[allow(unused_extern_crates)]
extern crate unwind;

// 在测试期间，此 crate 实际上不是 "真正的" std 库，而是链接到实际的 std 库，该库是从相同的源代码编译而成的。
// 因此，std 定义的任何 lang 项都被有条件地排除 (否则它们将生成重复的 lang 项错误)，并且它定义的任何全局变量都不是真实 std 中使用的全局变量。
//
// 所以这个仅在测试期间定义的导入使 test-std 可以访问 real-std lang 项和全局变量。
// 请参见 #2912
//
#[cfg(test)]
extern crate std as realstd;

// 编译器未内置的标准宏。
#[macro_use]
mod macros;

// Rust prelude
pub mod prelude;

// 公共模块声明和重导出
#[stable(feature = "rust1", since = "1.0.0")]
pub use alloc_crate::borrow;
#[stable(feature = "rust1", since = "1.0.0")]
pub use alloc_crate::boxed;
#[stable(feature = "rust1", since = "1.0.0")]
pub use alloc_crate::fmt;
#[stable(feature = "rust1", since = "1.0.0")]
pub use alloc_crate::format;
#[stable(feature = "rust1", since = "1.0.0")]
pub use alloc_crate::rc;
#[stable(feature = "rust1", since = "1.0.0")]
pub use alloc_crate::slice;
#[stable(feature = "rust1", since = "1.0.0")]
pub use alloc_crate::str;
#[stable(feature = "rust1", since = "1.0.0")]
pub use alloc_crate::string;
#[stable(feature = "rust1", since = "1.0.0")]
pub use alloc_crate::vec;
#[stable(feature = "rust1", since = "1.0.0")]
pub use core::any;
#[stable(feature = "simd_arch", since = "1.27.0")]
// 必须提供 `no_inline` 属性，以提供所有目标的文档。
// See https://github.com/rust-lang/rust/pull/57808#issuecomment-457390549formoreinformation.
//
//
#[doc(no_inline)] // Note (#82861): 正确的文档要求
pub use core::arch;
#[stable(feature = "core_array", since = "1.36.0")]
pub use core::array;
#[stable(feature = "rust1", since = "1.0.0")]
pub use core::cell;
#[stable(feature = "rust1", since = "1.0.0")]
pub use core::char;
#[stable(feature = "rust1", since = "1.0.0")]
pub use core::clone;
#[stable(feature = "rust1", since = "1.0.0")]
pub use core::cmp;
#[stable(feature = "rust1", since = "1.0.0")]
pub use core::convert;
#[stable(feature = "rust1", since = "1.0.0")]
pub use core::default;
#[stable(feature = "futures_api", since = "1.36.0")]
pub use core::future;
#[stable(feature = "rust1", since = "1.0.0")]
pub use core::hash;
#[stable(feature = "core_hint", since = "1.27.0")]
pub use core::hint;
#[stable(feature = "i128", since = "1.26.0")]
#[allow(deprecated, deprecated_in_future)]
pub use core::i128;
#[stable(feature = "rust1", since = "1.0.0")]
#[allow(deprecated, deprecated_in_future)]
pub use core::i16;
#[stable(feature = "rust1", since = "1.0.0")]
#[allow(deprecated, deprecated_in_future)]
pub use core::i32;
#[stable(feature = "rust1", since = "1.0.0")]
#[allow(deprecated, deprecated_in_future)]
pub use core::i64;
#[stable(feature = "rust1", since = "1.0.0")]
#[allow(deprecated, deprecated_in_future)]
pub use core::i8;
#[stable(feature = "rust1", since = "1.0.0")]
pub use core::intrinsics;
#[stable(feature = "rust1", since = "1.0.0")]
#[allow(deprecated, deprecated_in_future)]
pub use core::isize;
#[stable(feature = "rust1", since = "1.0.0")]
pub use core::iter;
#[stable(feature = "rust1", since = "1.0.0")]
pub use core::marker;
#[stable(feature = "rust1", since = "1.0.0")]
pub use core::mem;
#[stable(feature = "rust1", since = "1.0.0")]
pub use core::ops;
#[stable(feature = "rust1", since = "1.0.0")]
pub use core::option;
#[stable(feature = "pin", since = "1.33.0")]
pub use core::pin;
#[stable(feature = "rust1", since = "1.0.0")]
pub use core::ptr;
#[stable(feature = "rust1", since = "1.0.0")]
pub use core::result;
#[unstable(feature = "async_stream", issue = "79024")]
pub use core::stream;
#[stable(feature = "i128", since = "1.26.0")]
#[allow(deprecated, deprecated_in_future)]
pub use core::u128;
#[stable(feature = "rust1", since = "1.0.0")]
#[allow(deprecated, deprecated_in_future)]
pub use core::u16;
#[stable(feature = "rust1", since = "1.0.0")]
#[allow(deprecated, deprecated_in_future)]
pub use core::u32;
#[stable(feature = "rust1", since = "1.0.0")]
#[allow(deprecated, deprecated_in_future)]
pub use core::u64;
#[stable(feature = "rust1", since = "1.0.0")]
#[allow(deprecated, deprecated_in_future)]
pub use core::u8;
#[stable(feature = "rust1", since = "1.0.0")]
#[allow(deprecated, deprecated_in_future)]
pub use core::usize;

pub mod f32;
pub mod f64;

#[macro_use]
pub mod thread;
pub mod ascii;
pub mod backtrace;
pub mod collections;
pub mod env;
pub mod error;
pub mod ffi;
pub mod fs;
pub mod io;
pub mod net;
pub mod num;
pub mod os;
pub mod panic;
pub mod path;
pub mod process;
pub mod sync;
pub mod time;

#[unstable(feature = "once_cell", issue = "74465")]
pub mod lazy;

#[stable(feature = "futures_api", since = "1.36.0")]
pub mod task {
    //! 类型和 Traits 用于处理异步任务。

    #[doc(inline)]
    #[stable(feature = "futures_api", since = "1.36.0")]
    pub use core::task::*;

    #[doc(inline)]
    #[stable(feature = "wake_trait", since = "1.51.0")]
    pub use alloc::task::*;
}

// 平台抽象模块
#[macro_use]
mod sys_common;
mod sys;

pub mod alloc;

// private 支持模块
mod panicking;

// 运行时入口点和编译器使用的一些不稳定的公共函数
//
pub mod rt;

#[path = "../../backtrace/src/lib.rs"]
#[allow(dead_code, unused_attributes)]
mod backtrace_rs;

#[stable(feature = "simd_x86", since = "1.27.0")]
pub use std_detect::is_x86_feature_detected;
#[doc(hidden)]
#[unstable(feature = "stdsimd", issue = "48556")]
pub use std_detect::*;
#[unstable(feature = "stdsimd", issue = "48556")]
pub use std_detect::{
    is_aarch64_feature_detected, is_arm_feature_detected, is_mips64_feature_detected,
    is_mips_feature_detected, is_powerpc64_feature_detected, is_powerpc_feature_detected,
};

// 重导出 libcore 中定义的宏。
#[stable(feature = "rust1", since = "1.0.0")]
#[allow(deprecated, deprecated_in_future)]
pub use core::{
    assert_eq, assert_ne, debug_assert, debug_assert_eq, debug_assert_ne, matches, r#try, todo,
    unimplemented, unreachable, write, writeln,
};

// 重导出通过 libcore 定义的内置宏。
#[stable(feature = "builtin_macro_prelude", since = "1.38.0")]
#[allow(deprecated)]
pub use core::{
    assert, assert_matches, cfg, column, compile_error, concat, concat_idents, env, file,
    format_args, format_args_nl, include, include_bytes, include_str, line, llvm_asm, log_syntax,
    module_path, option_env, stringify, trace_macros,
};

#[stable(feature = "core_primitive", since = "1.43.0")]
pub use core::primitive;

// 包括许多私有模块，这些模块仅用于提供原始类型的 rustdoc 文档。
// 使用 `include!` 是因为 rustdoc 只在 crate 级别上查找这些模块。
//
include!("primitive_docs.rs");

// 包括许多私有模块，这些模块仅用于为现有关键字提供 rustdoc 文档。
// 使用 `include!` 是因为 rustdoc 只在 crate 级别上查找这些模块。
//
include!("keyword_docs.rs");

// 这是必需的，以避免在未启用 `restricted-std` 时产生不稳定的错误。
// #![feature(restricted_std)] 在 rustc-std-workspace-std 中的使用是无条件的，所以不稳定的特性需要在某处定义。
//
#[unstable(feature = "restricted_std", issue = "none")]
mod __restricted_std_workaround {}

mod sealed {
    /// 这个 trait 从 crate 外部无法访问，这阻止了我们扩展 trait 的外部实现。
    ///
    /// 这允许在未来添加更多 trait 方法。
    #[unstable(feature = "sealed", issue = "none")]
    pub trait Sealed {}
}