rust-std — Standard Library API Discovery

The standard library is the foundation. Before reaching for a crate, check whether std already provides the capability with the right semantics. This skill is a decision map, not an encyclopedia — for full API details consult std docs.

When to use

• Choosing between std types (Vec vs VecDeque, HashMap vs BTreeMap, String vs &str).
• Picking the right iterator method or combinator.
• Deciding between Option/Result APIs.
• Selecting interior mutability (Cell vs RefCell vs OnceLock vs LazyLock).
• Choosing synchronization primitives (Mutex vs RwLock vs atomics).
• Working with fs/io/path/process/net without dependencies.
• Deciding which conversion trait to implement (From/TryFrom/AsRef/Borrow/Deref).

Collections

HashMap patterns: use entry API for insert-or-update (map.entry(k).or_insert_with(...)); get returns Option<&V>; remove returns Option<V>. Iteration order is unspecified — never depend on it.

Strings and text

• String — owned, growable, UTF-8. &str — borrowed slice. Pass &str into functions, return String.
• String::with_capacity(n) when size is known; push_str to append; format! for composition.
• &str methods: split, split_whitespace, trim, starts_with/ends_with, contains, replace, parse::<T>() (via FromStr), chars, lines.
• char is a Unicode scalar value (4 bytes). Iterate grapheme clusters only with the unicode-segmentation crate.
• OsString/OsStr for OS-native paths that may not be UTF-8.

Option and Result

• Option<T> — value may be absent. Result<T, E> — operation may fail.
• Propagate with ? — works in functions returning Option or Result, and fn main() -> Result<(), E: Debug> is stable.
• Combinators: map, and_then (flatMap), or_else, map_or/map_or_else, ok_or/ok_or_else, as_deref, transpose (Option<Result> ↔ Result<Option>), flatten (Option<Option>/Result<Result>), inspect/inspect_err (1.76+, log without consuming).
• unwrap()/expect() only in tests, demos, or provably-infallible cases. unwrap_or/unwrap_or_else for defaults.
• ? also works in functions returning Option.

Iterators

Iterators are lazy — nothing happens until a consuming call. Chain transformations without intermediate collect() unless you need to reuse the result.

Consuming calls: collect, sum, count, min/max, find, any/all, fold, for_each, nth, last, position, partition.

Transformation methods: map, filter, flat_map/flatten, filter_map (map + filter in one), enumerate, zip, skip/take, skip_while/take_while, step_by, cloned/copied, scan, inspect, by_ref (for partial consumption). There is no Iterator::dedup - dedup consecutive items by collecting into a Vec and calling Vec::dedup, or use itertools.

collect targets: Vec, String (from char or &str iterators), HashMap/BTreeMap/HashSet/BTreeSet (from pairs), Result<Vec<T>, E> (fail-fast collection), Option<Vec<T>>.

Conversion and operator traits

Rule of thumb: implement From (not Into), AsRef for borrow-generic parameters, TryFrom for fallible conversions, FromStr for parsing, Display for user output.

Smart pointers and interior mutability

Decision: single-thread + Copy → Cell; single-thread + non-Copy → RefCell; multi-thread → Mutex/RwLock/Arc; one-time init → OnceLock; lazy static → LazyLock.

Synchronization (std)

• Mutex<T> — exclusive access; guard held across .await is a compile error in spawned tasks (!Send) — scope guards tightly.
• RwLock<T> — many readers or one writer; prefer Mutex unless read-heavy.
• Atomics (AtomicUsize etc.) — lock-free counters/flags; default SeqCst; see concurrency reference for ordering.
• Condvar — wait/notify on a Mutex guard; always re-check the condition in a loop (spurious wakeups).
• Barrier — rendezvous point for N threads.
• mpsc channels - std gives only std::sync::mpsc::{channel, sync_channel} (unbounded/bounded); oneshot, broadcast, and watch channels are runtime crates (tokio::sync), a justified dependency when std's single-producer multi-consumer channel does not fit.
• thread::scope (1.63+) — scoped threads can borrow stack data safely.
• thread::available_parallelism() — size thread pools to CPU count.
• Mutex poisoning: lock() returns LockResult; a panic while holding the lock poisons it. .unwrap() propagates the panic; into_inner() recovers if poisoning is acceptable.

fs, io, path

• Path/PathBuf — path manipulation (join, parent, extension, file_name); PathBuf for owned, Path for borrowed.
• fs::read_to_string, fs::read, fs::write — whole-file ops.
• File + BufReader/BufWriter — buffered streaming; BufRead::lines() for line iteration.
• OpenOptions — fine-grained open flags (read/write/append/create/truncate).
• fs::canonicalize — resolve to absolute canonical path (security checks: verify prefix after canonicalization).
• read_dir — directory iteration; DirEntry::path, file_type, metadata.
• io::ErrorKind — match on NotFound, PermissionDenied, AlreadyExists etc. for specific handling.
• stdin/stdout/stderr — io::stdin().lock() for line input.

process, env, net

• std::env — var, var_os, args, current_dir, set_var (unsafe in edition 2024), temp_dir.
• Command — spawn processes; pass args as an array (never build shell strings — argument injection); Stdio for piping; output() for captured output; status() for exit code; Child for stdin/stdout interaction.
• TcpListener/TcpStream — blocking TCP; UdpSocket for UDP; SocketAddr/SocketAddrV4/SocketAddrV6 for addresses.
• ToSocketAddrs — "host:port" parsing for connect/bind.
• For async I/O use tokio (see rust-tokio); std net is blocking.

time, panic, misc

• Duration — time spans; Instant — monotonic clock (measurements); SystemTime — wall clock (may jump; use for timestamps, not intervals).
• thread::sleep — blocking sleep (never in async).
• panic!/catch_unwind — panics unwind by default; catch_unwind for FFI boundaries or thread isolation; panic = "abort" in release profiles for no-unwind builds.
• std::any::type_name — runtime type name for diagnostics.
• std::mem — size_of/align_of, replace, take, swap, forget (leaks memory — safe but usually wrong).
• std::ffi — CString/CStr for FFI boundaries; OsString for OS strings.
• std::marker — PhantomData for unused generics/ownership hints, PhantomPinned.

Native-first rule

The decision chain: NATIVE FIRST -> VERIFY NEED -> CHOOSE DEPENDENCY -> VERIFY MAINTENANCE.

Before adding a dependency:

1. Does std (or Cargo, or rustc/rustdoc) already provide this?
2. Does std's semantics/performance suffice?
3. What does the crate add beyond std?
4. Weigh maintenance, security, MSRV, compile time, binary size, maturity, ops cost.
5. Add the dependency when it provides justified value: materially more capability, ergonomics, portability, performance, ecosystem compatibility, or domain functionality that std does not reasonably provide.

This is not "never use dependencies" - it is "understand native capabilities first, then introduce dependencies intentionally." See rust-production for the full rule.

Capability decision table

What std covers per capability, and when a dependency is the right call: