Rust Core Stdlib Overview

rust-core-stdlib-overview

A tour of the Rust standard library. This skill is a map, not a tutorial: it tells you which std module provides which capability, what the prelude auto-imports, how core / alloc / std are layered, and when to drop to no_std. Deep mechanics live in cross-referenced skills.

Cross-references: [[rust-impl-no-std]] [[rust-impl-concurrency]] [[rust-impl-channels]] [[rust-core-async-runtime]] [[rust-impl-async-tokio]]

When to use this skill

• User asks "is there a standard library type for X" or "do I need a crate for this"
• User asks "what does the prelude import", "what is std::prelude::v1"
• User asks "what is the difference between core, alloc, and std"
• User asks "how do I make my crate no_std" at the map level (mechanics live in rust-impl-no-std)
• User confused about which std::sync primitive to pick at the catalogue level
• User asks "which std::collections type should I use" at the catalogue level
• User asks "where is X in std" and you need the module location

For deep mechanics of any module (lock poisoning, async runtimes, lifetime rules of &Path), refer to the cross-referenced skills.

Layering: core, alloc, std

std is built on two lower layers. ALWAYS understand which layer you depend on before writing portable code.

ALWAYS note: HashMap and HashSet are in std, NOT in alloc, because they depend on RandomState for hash-DoS resilience which is seeded from the OS RNG. NEVER assume you can use HashMap on no_std; use the hashbrown crate directly with a manual hasher.

ALWAYS note: std::collections re-exports the alloc::collections types (BTreeMap, BTreeSet, VecDeque, BinaryHeap, LinkedList) plus the std-only types (HashMap, HashSet). Switching to no_std + alloc loses the hash-based types.

The prelude

The prelude is the set of names automatically imported into every module of every crate. Edition 2024 adds two items.

ALWAYS access the prelude as std::prelude::v1 (or core::prelude::v1 / alloc::prelude::v1 for the layered preludes). NEVER assume non-prelude items like std::collections::HashMap are auto-imported; you must use them.

Decision table: I need X to do Y, which std module

ALWAYS check this table before reaching for an external crate. NEVER add a dependency for capabilities that std already provides at acceptable quality.

std::collections at a glance

std::collections is the catalogue of generic containers. Selection rules:

• ALWAYS default to Vec<T> for sequences. It is the most efficient choice for almost every use case.
• ALWAYS prefer HashMap<K, V> for unordered key-value lookup when keys implement Hash + Eq.
• ALWAYS use BTreeMap<K, V> when you need ordered iteration, range queries, or deterministic iteration order (HashMap iteration order is intentionally randomised).
• ALWAYS use VecDeque<T> for FIFO queues; Vec::remove(0) is O(n), VecDeque::pop_front is O(1).
• ALWAYS use BinaryHeap<T> for priority queues; it is a max-heap, use std::cmp::Reverse for a min-heap.
• NEVER reach for LinkedList<T>; its only honest use case is constant-time splicing of large lists, which is almost never the bottleneck. Vec or VecDeque is faster in practice due to cache locality.

HashMap and hash-DoS resilience

HashMap uses RandomState as its default hasher. RandomState is seeded from the OS RNG at creation time. This is a deliberate hash-DoS protection: an attacker who can choose keys cannot force pathological O(n) collisions in the table.

Consequences:

• ALWAYS expect iteration order to differ between runs and between insertions. NEVER rely on HashMap iteration order for any logic.
• For deterministic order, use BTreeMap or wrap with IndexMap (external crate indexmap).
• For maximum speed when keys are trusted (internal benchmark, fixed dataset), use HashMap with a non-random hasher such as FxHashMap (external crate rustc-hash) or AHashMap (external crate ahash). ALWAYS document the threat model when removing DoS protection.
• The underlying implementation of HashMap is the hashbrown crate, which is the Swiss-table design used by ABSL. In no_std + alloc you depend on hashbrown directly.

std::sync at a glance

std::sync collects the synchronization primitives.

• Arc<T> : atomic reference count, thread-safe shared ownership. ALWAYS use Arc, NEVER Rc, when sharing across threads.
• Mutex<T> : exclusive lock. Returns LockResult<MutexGuard<T>>; Err indicates poisoning from a panic while locked. ALWAYS handle poisoning explicitly or call .unwrap() only when the panic is unrecoverable.
• RwLock<T> : many readers OR one writer. ALWAYS prefer Mutex for write-heavy workloads; RwLock overhead beats Mutex only when reads dominate.
• atomic (AtomicUsize, AtomicBool, AtomicPtr, AtomicI32, etc.) : lock-free integer / pointer operations with explicit Ordering. ALWAYS pick Ordering::Relaxed for counters with no cross-thread observation requirements; Ordering::Acquire / Ordering::Release for synchronization; Ordering::SeqCst only when you have proven a need.
• Once : run a closure exactly once across threads. Legacy; ALWAYS prefer OnceLock or LazyLock for new code.
• OnceLock<T> (since 1.70) : one-time initialization that returns &T. Replaces lazy_static for non-closure cases.
• LazyLock<T, F> (since 1.80) : static lazily initialized by a closure on first access. Replaces lazy_static for closure cases.
• Barrier : block N threads until all arrive.
• Condvar : condition variable, used with Mutex<bool> or Mutex<Queue> for "wait until predicate holds" patterns.
• mpsc (sub-module): multi-producer, single-consumer channel. channel() returns (Sender<T>, Receiver<T>); sync_channel(bound) for bounded backpressure.

NEVER use std::sync::Mutex inside async code (holding the guard across .await blocks the runtime worker). Use tokio::sync::Mutex or similar runtime-specific async locks. See [[rust-core-async-runtime]].

std::io at a glance

std::io defines the I/O traits and helpers. Almost all Read / Write consumers are generic over the trait, not concrete types.

ALWAYS check the return of Write::write: a partial write is legal. Use write_all to loop until done, or handle the partial yourself.

NEVER call stdout().write_all(...) in a tight loop without locking once via stdout().lock(); each stdout() call acquires the lock and is significantly slower.

std::fs and std::path at a glance

std::fs covers filesystem operations; std::path covers cross-platform path manipulation.

Key items:

• File::open(path) opens read-only; File::create(path) opens write-only-truncate; OpenOptions::new().read(true).write(true).create(true).append(true).open(path) for full control.
• fs::read_to_string(path) reads an entire file into a String; fs::write(path, contents) writes a slice or string.
• fs::metadata(path) returns Metadata (file size, mtime, permissions).
• fs::create_dir, fs::create_dir_all, fs::remove_file, fs::remove_dir, fs::remove_dir_all, fs::rename, fs::copy.
• fs::read_dir(path) returns an iterator of io::Result<DirEntry>.

Path is the borrowed unsized type (analogous to &str); PathBuf is the owned growable type (analogous to String).

• ALWAYS accept &Path (or generically impl AsRef<Path>) in function parameters, NEVER &PathBuf.
• ALWAYS use Path::join, Path::with_extension, Path::file_name, Path::components for manipulation; NEVER concatenate strings.
• NEVER assume paths are valid UTF-8; on Unix they are arbitrary bytes, on Windows they are arbitrary UTF-16. Use Path::display() for human output and OsStr for byte-level work.

NEVER use blocking std::fs calls inside an async runtime (Tokio, async-std, smol); the runtime worker stalls. Use tokio::fs or wrap in tokio::task::spawn_blocking. See [[rust-impl-async-tokio]].

std::process at a glance

std::process::Command is the builder for spawning subprocesses.

use std::process::{Command, Stdio};

let output = Command::new("ls")
    .arg("-la")
    .arg("/tmp")
    .env("LC_ALL", "C")
    .stdout(Stdio::piped())
    .output()?; // io::Result<Output>

assert!(output.status.success());
let stdout = String::from_utf8_lossy(&output.stdout);

Key API:

• Command::new(program) ; chained .arg, .args, .env, .env_clear, .env_remove, .current_dir, .stdin, .stdout, .stderr.
• .output() runs to completion and collects Output { status, stdout, stderr }.
• .status() runs to completion and returns only the exit status.
• .spawn() returns Child for streaming I/O; ALWAYS call .wait() or .wait_with_output() to reap the process.
• process::exit(code) terminates the current process without unwinding (Drop is NOT run).
• process::abort() aborts (no destructors, signal SIGABRT on Unix).

NEVER pass user-controlled strings through a shell. ALWAYS use Command::arg per argument; arguments are passed directly to the OS without shell interpretation.

std::thread at a glance

std::thread is the OS-thread API.

• thread::spawn(|| { ... }) returns a JoinHandle<T>; closure must be 'static + Send, return type must be Send.
• thread::scope(|s| { s.spawn(|| { ... }); ... }) (since 1.63) creates scoped threads that can borrow non-'static data; all scoped threads must finish before the scope returns. ALWAYS prefer thread::scope over thread::spawn when you need to borrow stack data.
• JoinHandle::join() waits for the thread and returns Result<T, Box<dyn Any + Send>>; Err indicates the thread panicked.
• thread::Builder::new().name("worker").stack_size(8 * 1024 * 1024).spawn(...) configures a thread before spawning.
• thread::current() returns the current thread handle; thread::sleep(Duration); thread::park() / Thread::unpark().
• thread_local! macro declares per-thread static storage.

ALWAYS join spawned threads, NEVER let them detach silently unless you genuinely have a fire-and-forget background task.

std::time at a glance

thread::sleep(Duration::from_millis(100)) sleeps the current thread.

For async sleep, use tokio::time::sleep ; NEVER use thread::sleep inside an async runtime.

std::env at a glance

ALWAYS use env::args_os() when arguments may contain non-UTF-8 (filenames on Unix). NEVER mutate environment variables (set_var / remove_var) from inside a library or from a multi-threaded program without external synchronization; libc setenv is not thread-safe.

std::ffi at a glance

Two pairs of borrowed/owned string types, with different invariants.

ALWAYS use CString / CStr for FFI with C APIs (extern "C" functions that take *const c_char). NEVER pass &str directly; &str is not NUL-terminated.

ALWAYS use OsString / OsStr for paths and environment variables that may contain non-UTF-8 bytes (Unix paths, Windows UTF-16 paths).

Conversion: CString::new("hello")? returns Result<CString, NulError>; the error fires if the input contains an interior NUL byte.

See [[rust-impl-ffi-bindgen]] for full FFI mechanics.

The no_std switch

To make a crate compile without std, add #![no_std] to src/lib.rs. Consequences:

• You lose std::fs, std::io, std::net, std::process, std::thread, std::env, std::sync::Mutex, HashMap, HashSet, the standard println! macro that targets stdout.
• You keep all of core : Option, Result, Iterator, traits, atomics, formatting machinery (but no default output target).
• ALWAYS add extern crate alloc; if you want Box, Vec, String, Rc, Arc, BTreeMap. Then use alloc::vec::Vec;, etc.
• ALWAYS provide a #[panic_handler] somewhere in the crate graph (typically in the binary or board crate, not in the library).
• For hash maps without std, use the hashbrown crate directly with BuildHasherDefault<FxHasher> or a fixed seed.

See [[rust-impl-no-std]] for the full no_std workflow.

Common cross-references

• For ownership and borrowing rules used throughout the stdlib API: see [[rust-syntax-ownership]] and [[rust-syntax-borrowing]].
• For deeper async runtime semantics (when std blocking calls are forbidden): see [[rust-core-async-runtime]] and [[rust-impl-async-tokio]].
• For lock-free programming with std::sync::atomic: see [[rust-impl-concurrency]].
• For channel patterns built on std::sync::mpsc: see [[rust-impl-channels]].
• For the no_std workflow end to end: see [[rust-impl-no-std]].

Reference files

• references/methods.md : exact module item names per area, grouped by std module
• references/examples.md : minimal working example for each major area
• references/anti-patterns.md : five-plus stdlib anti-patterns and their fixes

Approved sources

• Rust Standard Library (root): https://doc.rust-lang.org/std/
• std::collections : https://doc.rust-lang.org/std/collections/index.html
• std::sync : https://doc.rust-lang.org/std/sync/index.html
• std::io : https://doc.rust-lang.org/std/io/index.html
• std::fs : https://doc.rust-lang.org/std/fs/index.html
• std::thread : https://doc.rust-lang.org/std/thread/index.html
• std::time : https://doc.rust-lang.org/std/time/index.html
• std::path : https://doc.rust-lang.org/std/path/index.html
• std::env : https://doc.rust-lang.org/std/env/index.html
• std::ffi : https://doc.rust-lang.org/std/ffi/index.html
• std::process : https://doc.rust-lang.org/std/process/index.html
• Rust 1.70 release (OnceLock) : https://blog.rust-lang.org/2023/06/01/Rust-1.70.0/
• Rust 1.80 release (LazyLock) : https://blog.rust-lang.org/2024/07/25/Rust-1.80.0/
• Rust 1.63 release (scoped threads) : https://blog.rust-lang.org/2022/08/11/Rust-1.63.0/