From 3121c0b68b136f7847176e579aea2ccb9a6f6693 Mon Sep 17 00:00:00 2001 From: Julien THILLARD Date: Thu, 19 Mar 2026 12:01:04 +0100 Subject: [PATCH] Add more from the std --- crates/std/src/io/buffered/bufreader.rs | 15 +- crates/std/src/lib.rs | 438 +++++++++++++++++++++--- 2 files changed, 396 insertions(+), 57 deletions(-) diff --git a/crates/std/src/io/buffered/bufreader.rs b/crates/std/src/io/buffered/bufreader.rs index 40441dc..95876ec 100644 --- a/crates/std/src/io/buffered/bufreader.rs +++ b/crates/std/src/io/buffered/bufreader.rs @@ -100,7 +100,10 @@ impl BufReader { /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn with_capacity(capacity: usize, inner: R) -> BufReader { - BufReader { inner, buf: Buffer::with_capacity(capacity) } + BufReader { + inner, + buf: Buffer::with_capacity(capacity), + } } } @@ -373,7 +376,10 @@ impl Read for BufReader { // generation for the common path where the buffer has enough bytes to fill the passed-in // buffer. fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<()> { - if self.buf.consume_with(buf.len(), |claimed| buf.copy_from_slice(claimed)) { + if self + .buf + .consume_with(buf.len(), |claimed| buf.copy_from_slice(claimed)) + { return Ok(()); } @@ -381,7 +387,10 @@ impl Read for BufReader { } fn read_buf_exact(&mut self, mut cursor: BorrowedCursor<'_>) -> io::Result<()> { - if self.buf.consume_with(cursor.capacity(), |claimed| cursor.append(claimed)) { + if self + .buf + .consume_with(cursor.capacity(), |claimed| cursor.append(claimed)) + { return Ok(()); } diff --git a/crates/std/src/lib.rs b/crates/std/src/lib.rs index 1520667..085206e 100644 --- a/crates/std/src/lib.rs +++ b/crates/std/src/lib.rs @@ -1,15 +1,251 @@ -#![unstable(feature = "custom_std", issue = "none")] +//! # The Rust Standard Library +//! +//! 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][crates.io]. It offers core types, like [`Vec`] and +//! [`Option`], library-defined [operations on language +//! primitives](#primitives), [standard macros](#macros), [I/O] and +//! [multithreading], among [many other things][other]. +//! +//! `std` is available to all Rust crates by default. Therefore, the +//! standard library can be accessed in [`use`] statements through the path +//! `std`, as in [`use std::env`]. +//! +//! # How to read this documentation +//! +//! If you already know the name of what you are looking for, the fastest way to +//! find it is to use the search +//! button at the top of the page. +//! +//! Otherwise, you may want to jump to one of these useful sections: +//! +//! * [`std::*` modules](#modules) +//! * [Primitive types](#primitives) +//! * [Standard macros](#macros) +//! * [The Rust Prelude] +//! +//! If this is your first time, the documentation for the standard library is +//! written to be casually perused. Clicking on interesting things should +//! generally lead you to interesting places. Still, there are important bits +//! you don't want to miss, so read on for a tour of the standard library and +//! its documentation! +//! +//! Once you are familiar with the contents of the standard library you may +//! begin to find the verbosity of the prose distracting. At this stage in your +//! development you may want to press the +//! " Summary" +//! button near the top of the page to collapse it into a more skimmable view. +//! +//! While you are looking at the top of the page, also notice the +//! "Source" link. Rust's API documentation comes with the source +//! code and you are encouraged to read it. The standard library source is +//! generally high quality and a peek behind the curtains is +//! often enlightening. +//! +//! # What is in the standard library documentation? +//! +//! First of all, The Rust Standard Library is divided into a number of focused +//! modules, [all listed further down this page](#modules). These modules are +//! the bedrock upon which all of Rust is forged, and they have mighty names +//! like [`std::slice`] and [`std::cmp`]. Modules' documentation typically +//! includes an overview of the module along with examples, and are a smart +//! place to start familiarizing yourself with the library. +//! +//! Second, implicit methods on [primitive types] are documented here. This can +//! be a source of confusion for two reasons: +//! +//! 1. While primitives are implemented by the compiler, the standard library +//! implements methods directly on the primitive types (and it is the only +//! library that does so), which are [documented in the section on +//! primitives](#primitives). +//! 2. The standard library exports many modules *with the same name as +//! primitive types*. These define additional items related to the primitive +//! type, but not the all-important methods. +//! +//! So for example there is a [page for the primitive type +//! `char`](primitive::char) that lists all the methods that can be called on +//! characters (very useful), and there is a [page for the module +//! `std::char`](crate::char) that documents iterator and error types created by these methods +//! (rarely useful). +//! +//! Note the documentation for the primitives [`str`] and [`[T]`][prim@slice] (also +//! called 'slice'). Many method calls on [`String`] and [`Vec`] are actually +//! calls to methods on [`str`] and [`[T]`][prim@slice] respectively, via [deref +//! coercions][deref-coercions]. +//! +//! Third, the standard library defines [The Rust Prelude], a small collection +//! of items - mostly traits - that are imported into every module of every +//! crate. The traits in the prelude are pervasive, making the prelude +//! documentation a good entry point to learning about the library. +//! +//! And finally, the standard library exports a number of standard macros, and +//! [lists them on this page](#macros) (technically, not all of the standard +//! macros are defined by the standard library - some are defined by the +//! compiler - but they are documented here the same). Like the prelude, the +//! standard macros are imported by default into all crates. +//! +//! # Contributing changes to the documentation +//! +//! Check out the Rust contribution guidelines [here]( +//! https://rustc-dev-guide.rust-lang.org/contributing.html#writing-documentation). +//! The source for this documentation can be found on +//! [GitHub](https://github.com/rust-lang/rust) in the 'library/std/' directory. +//! To contribute changes, make sure you read the guidelines first, then submit +//! pull-requests for your suggested changes. +//! +//! Contributions are appreciated! If you see a part of the docs that can be +//! improved, submit a PR, or chat with us first on [Zulip][rust-zulip] +//! #docs. +//! +//! # A Tour of The Rust Standard Library +//! +//! The rest of this crate documentation is dedicated to pointing out notable +//! features of The Rust Standard Library. +//! +//! ## Containers and collections +//! +//! The [`option`] and [`result`] modules define optional and error-handling +//! types, [`Option`] and [`Result`]. The [`iter`] module defines +//! Rust's iterator trait, [`Iterator`], which works with the [`for`] loop to +//! access collections. +//! +//! The standard library exposes three common ways to deal with contiguous +//! regions of memory: +//! +//! * [`Vec`] - A heap-allocated *vector* that is resizable at runtime. +//! * [`[T; N]`][prim@array] - An inline *array* with a fixed size at compile time. +//! * [`[T]`][prim@slice] - A dynamically sized *slice* into any other kind of contiguous +//! storage, whether heap-allocated or not. +//! +//! Slices can only be handled through some kind of *pointer*, and as such come +//! in many flavors such as: +//! +//! * `&[T]` - *shared slice* +//! * `&mut [T]` - *mutable slice* +//! * [`Box<[T]>`][owned slice] - *owned slice* +//! +//! [`str`], a UTF-8 string slice, is a primitive type, and the standard library +//! defines many methods for it. Rust [`str`]s are typically accessed as +//! immutable references: `&str`. Use the owned [`String`] for building and +//! mutating strings. +//! +//! For converting to strings use the [`format!`] macro, and for converting from +//! strings use the [`FromStr`] trait. +//! +//! Data may be shared by placing it in a reference-counted box or the [`Rc`] +//! type, and if further contained in a [`Cell`] or [`RefCell`], may be mutated +//! as well as shared. Likewise, in a concurrent setting it is common to pair an +//! atomically-reference-counted box, [`Arc`], with a [`Mutex`] to get the same +//! effect. +//! +//! The [`collections`] module defines maps, sets, linked lists and other +//! typical collection types, including the common [`HashMap`]. +//! +//! ## Platform abstractions and I/O +//! +//! Besides basic data types, the standard library is largely concerned with +//! abstracting over differences in common platforms, most notably Windows and +//! Unix derivatives. +//! +//! Common types of I/O, including [files], [TCP], and [UDP], are defined in +//! the [`io`], [`fs`], and [`net`] modules. +//! +//! The [`thread`] module contains Rust's threading abstractions. [`sync`] +//! contains further primitive shared memory types, including [`atomic`], [`mpmc`] and +//! [`mpsc`], which contains the channel types for message passing. +//! +//! # Use before and after `main()` +//! +//! Many parts of the standard library are expected to work before and after `main()`; +//! but this is not guaranteed or ensured by tests. It is recommended that you write your own tests +//! and run them on each platform you wish to support. +//! This means that use of `std` before/after main, especially of features that interact with the +//! OS or global state, is exempted from stability and portability guarantees and instead only +//! provided on a best-effort basis. Nevertheless bug reports are appreciated. +//! +//! On the other hand `core` and `alloc` are most likely to work in such environments with +//! the caveat that any hookable behavior such as panics, oom handling or allocators will also +//! depend on the compatibility of the hooks. +//! +//! Some features may also behave differently outside main, e.g. stdio could become unbuffered, +//! some panics might turn into aborts, backtraces might not get symbolicated or similar. +//! +//! Non-exhaustive list of known limitations: +//! +//! - after-main use of thread-locals, which also affects additional features: +//! - [`thread::current()`] +//! - under UNIX, before main, file descriptors 0, 1, and 2 may be unchanged +//! (they are guaranteed to be open during main, +//! and are opened to /dev/null O_RDWR if they weren't open on program start) +//! +//! +//! [I/O]: io +//! [TCP]: net::TcpStream +//! [The Rust Prelude]: prelude +//! [UDP]: net::UdpSocket +//! [`Arc`]: sync::Arc +//! [owned slice]: boxed +//! [`Cell`]: cell::Cell +//! [`FromStr`]: str::FromStr +//! [`HashMap`]: collections::HashMap +//! [`Mutex`]: sync::Mutex +//! [`Option`]: option::Option +//! [`Rc`]: rc::Rc +//! [`RefCell`]: cell::RefCell +//! [`Result`]: result::Result +//! [`Vec`]: vec::Vec +//! [`atomic`]: sync::atomic +//! [`for`]: ../book/ch03-05-control-flow.html#looping-through-a-collection-with-for +//! [`str`]: prim@str +//! [`mpmc`]: sync::mpmc +//! [`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-zulip]: https://rust-lang.zulipchat.com/ +//! [array]: prim@array +//! [slice]: prim@slice + +#![cfg_attr(not(restricted_std), stable(feature = "rust1", since = "1.0.0"))] +#![cfg_attr( + restricted_std, + unstable( + feature = "restricted_std", + issue = "none", + reason = "You have attempted to use a standard library built for a platform that it doesn't \ + know how to support. Consider building it for a known environment, disabling it with \ + `#![no_std]` or overriding this warning by enabling this feature." + ) +)] +#![rustc_preserve_ub_checks] +#![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))) +)] +#![doc(rust_logo)] +#![doc(auto_cfg(hide(no_global_oom_handling)))] +// Don't link to std. We are std. #![no_std] +// Tell the compiler to link to either panic_abort or panic_unwind +// #![needs_panic_runtime] // // Lints: #![warn(deprecated_in_future)] -// #![warn(missing_docs)] -// #![warn(missing_debug_implementations)] +#![warn(missing_docs)] +#![warn(missing_debug_implementations)] #![allow(explicit_outlives_requirements)] #![allow(unused_lifetimes)] #![allow(internal_features)] #![deny(fuzzy_provenance_casts)] -#![allow(fuzzy_provenance_casts)] #![deny(unsafe_op_in_unsafe_fn)] #![allow(rustdoc::redundant_explicit_links)] #![warn(rustdoc::unescaped_backticks)] @@ -56,7 +292,6 @@ #![feature(ffi_const)] #![feature(formatting_options)] #![feature(funnel_shifts)] -#![feature(if_let_guard)] #![feature(intra_doc_pointers)] #![feature(iter_advance_by)] #![feature(iter_next_chunk)] @@ -77,10 +312,12 @@ #![feature(staged_api)] #![feature(stmt_expr_attributes)] #![feature(strict_provenance_lints)] +#![feature(target_feature_inline_always)] #![feature(thread_local)] #![feature(try_blocks)] #![feature(try_trait_v2)] #![feature(type_alias_impl_trait)] +#![feature(uint_carryless_mul)] // tidy-alphabetical-end // // Library features (core): @@ -88,12 +325,12 @@ #![feature(bstr)] #![feature(bstr_internals)] #![feature(cast_maybe_uninit)] -#![feature(cfg_select)] #![feature(char_internals)] #![feature(clone_to_uninit)] #![feature(const_convert)] #![feature(core_intrinsics)] #![feature(core_io_borrowed_buf)] +#![feature(cstr_display)] #![feature(drop_guard)] #![feature(duration_constants)] #![feature(error_generic_member_access)] @@ -102,7 +339,7 @@ #![feature(exclusive_wrapper)] #![feature(extend_one)] #![feature(float_algebraic)] -// #![feature(float_gamma)] +#![feature(float_gamma)] #![feature(float_minimum_maximum)] #![feature(fmt_internals)] #![feature(fn_ptr_trait)] @@ -135,7 +372,6 @@ // // Library features (alloc): // tidy-alphabetical-start -#![feature(alloc_layout_extra)] #![feature(allocator_api)] #![feature(clone_from_ref)] #![feature(get_mut_unchecked)] @@ -155,12 +391,11 @@ // // Library features (std_detect): // tidy-alphabetical-start -// #![feature(stdarch_internal)] +#![feature(stdarch_internal)] // tidy-alphabetical-end // // Only for re-exporting: // tidy-alphabetical-start -#![feature(assert_matches)] #![feature(async_iterator)] #![feature(c_variadic)] #![feature(cfg_accessible)] @@ -182,64 +417,137 @@ #![feature(io_const_error)] // tidy-alphabetical-end // -#![feature(c_size_t, unsafe_binders)] -#![allow(clippy::doc_lazy_continuation, clippy::all)] -#![allow( - stable_features, - incomplete_features, - unexpected_cfgs, - unfulfilled_lint_expectations, - private_interfaces -)] -#![allow(unused)] +#![default_lib_allocator] +// The Rust prelude +// The compiler expects the prelude definition to be defined before its use statement. +pub mod prelude; + +// Explicitly import the prelude. The compiler uses this same unstable attribute +// to import the prelude implicitly when building crates that depend on std. +#[prelude_import] +#[allow(unused)] +use prelude::rust_2024::*; + +// Access to Bencher, etc. +#[cfg(test)] +extern crate test; + +#[allow(unused_imports)] // macros from `alloc` are not used on all platforms #[macro_use] extern crate alloc as alloc_crate; +// FIXME: #94122 this extern crate definition only exist here to stop +// miniz_oxide docs leaking into std docs. Find better way to do it. +// Remove exclusion from tidy platform check when this removed. +#[doc(masked)] +#[allow(unused_extern_crates)] +#[cfg(all( + not(all(windows, target_env = "msvc", not(target_vendor = "uwp"))), + feature = "miniz_oxide" +))] +extern crate miniz_oxide; + +// During testing, this crate is not actually the "real" std library, but rather +// it links to the real std library, which was compiled from this same source +// code. So any lang items std defines are conditionally excluded (or else they +// would generate duplicate lang item errors), and any globals it defines are +// _not_ the globals used by "real" std. So this import, defined only during +// testing gives test-std access to real-std lang items and globals. See #2912 +#[cfg(test)] +extern crate std as realstd; + +// The standard macros that are not built-in to the compiler. +#[macro_use] +#[doc(hidden)] +#[unstable(feature = "std_internals", issue = "none")] +pub mod macros; + +// The runtime entry point and a few unstable public functions used by the +// compiler +#[macro_use] +pub mod rt; + +#[stable(feature = "rust1", since = "1.0.0")] pub use core::any; +#[stable(feature = "core_array", since = "1.35.0")] pub use core::array; +#[unstable(feature = "async_iterator", issue = "79024")] pub use core::async_iter; +#[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; +#[unstable(feature = "field_projections", issue = "145383")] +pub use core::field; +#[stable(feature = "futures_api", since = "1.36.0")] pub use core::future; +#[stable(feature = "core_hint", since = "1.27.0")] pub use core::hint; +#[stable(feature = "rust1", since = "1.0.0")] #[allow(deprecated, deprecated_in_future)] pub use core::i8; +#[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 = "i128", since = "1.26.0")] #[allow(deprecated, deprecated_in_future)] pub use core::i128; +#[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; +#[unstable(feature = "new_range_api", issue = "125687")] pub use core::range; +#[stable(feature = "rust1", since = "1.0.0")] pub use core::result; +#[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::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 = "i128", since = "1.26.0")] #[allow(deprecated, deprecated_in_future)] pub use core::u128; +#[unstable(feature = "unsafe_binders", issue = "130516")] pub use core::unsafe_binder; +#[stable(feature = "rust1", since = "1.0.0")] #[allow(deprecated, deprecated_in_future)] pub use core::usize; @@ -262,51 +570,67 @@ pub use alloc_crate::string; #[stable(feature = "rust1", since = "1.0.0")] pub use alloc_crate::vec; -use io_crate::IoBase; -pub use std_detect::is_x86_feature_detected; +#[path = "num/f128.rs"] +pub mod f128; +#[path = "num/f16.rs"] +pub mod f16; +#[path = "num/f32.rs"] +pub mod f32; +#[path = "num/f64.rs"] +pub mod f64; -#[stable(feature = "builtin_macro_prelude", since = "1.38.0")] -pub use core::{ - assert, cfg, column, compile_error, concat, const_format_args, env, file, format_args, - format_args_nl, include, include_bytes, include_str, line, log_syntax, module_path, option_env, - stringify, trace_macros, unimplemented, -}; +#[macro_use] +pub mod thread; +pub mod ascii; +pub mod backtrace; +#[unstable(feature = "bstr", issue = "134915")] +pub mod bstr; +pub mod collections; +pub mod env; +pub mod error; +pub mod ffi; +pub mod fs; +pub mod hash; +pub mod io; +pub mod net; +pub mod num; +pub mod os; +pub mod panic; +#[unstable(feature = "pattern_type_macro", issue = "123646")] +pub mod pat; +pub mod path; +pub mod process; +#[unstable(feature = "random", issue = "130703")] +pub mod random; +pub mod sync; +pub mod time; +#[unstable(feature = "custom_std", issue = "none")] #[rustc_std_internal_symbol] pub unsafe fn __rust_start_panic(_payload: &mut dyn core::panic::PanicPayload) -> u32 { todo!() } -pub mod error; -pub mod ffi; -pub mod hash; -pub mod io; -pub mod num; -pub mod path; -pub mod prelude; -pub mod process; -#[macro_use] -pub mod rt; +#[unstable(feature = "custom_std", issue = "none")] +pub use core::format_args_nl; +#[unstable(feature = "custom_std", issue = "none")] +pub use core::unimplemented; +#[unstable(feature = "custom_std", issue = "none")] +pub use std_detect::is_x86_feature_detected; pub mod alloc; -pub mod ascii; -pub mod backtrace; -pub mod bstr; -pub mod collections; -pub mod env; -pub mod fs; -pub mod keyword_docs; -pub mod macros; -pub mod net; -pub mod os; -pub mod panic; +#[unstable(feature = "custom_std", issue = "none")] pub mod panicking; -pub mod pat; -pub mod sync; +#[unstable(feature = "custom_std", issue = "none")] pub mod sys; -pub mod thread; -pub mod time; #[path = "../crates/backtrace-rs/src/lib.rs"] +#[allow( + dead_code, + unused_attributes, + fuzzy_provenance_casts, + unsafe_op_in_unsafe_fn +)] +#[unstable(feature = "custom_std", issue = "none")] mod backtrace_rs; #[prelude_import] @@ -322,7 +646,9 @@ mod sealed { pub trait Sealed {} } +#[unstable(feature = "custom_std", issue = "none")] pub use shared::fs as other_fs; +#[unstable(feature = "custom_std", issue = "none")] pub use shared::syscall; use crate::io::Stdin; @@ -345,10 +671,14 @@ use crate::io::Stdin; // }; // } -impl IoBase for Stdin { +#[allow(ineffective_unstable_trait_impl)] +#[unstable(feature = "custom_std", issue = "none")] +impl io_crate::IoBase for Stdin { type Error = (); } +#[allow(ineffective_unstable_trait_impl)] +#[unstable(feature = "custom_std", issue = "none")] impl io_crate::Read for Stdin { fn read(&mut self, buf: &mut [u8]) -> core::result::Result { unsafe { crate::other_fs::File::from_raw_fd(0).read(buf) }