Cratestd

Expand description

§The Rust Standard Library

The Rust Standard Library is the foundation of portable Rust software, aset of minimal and battle-tested shared abstractions for thebroader Rustecosystem. It offers core types, likeVec<T> andOption<T>, library-definedoperations on languageprimitives,standard macros,I/O andmultithreading, amongmany other things.

std is available to all Rust crates by default. Therefore, thestandard library can be accessed inuse statements through the pathstd, as inuse std::env.

§How to read this documentation

If you already know the name of what you are looking for, the fastest way tofind it is to use thesearchbutton at the top of the page.

Otherwise, you may want to jump to one of these useful sections:

If this is your first time, the documentation for the standard library iswritten to be casually perused. Clicking on interesting things shouldgenerally lead you to interesting places. Still, there are important bitsyou don’t want to miss, so read on for a tour of the standard library andits documentation!

Once you are familiar with the contents of the standard library you maybegin to find the verbosity of the prose distracting. At this stage in yourdevelopment 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 sourcecode and you are encouraged to read it. The standard library source isgenerally high quality and a peek behind the curtains isoften enlightening.

§What is in the standard library documentation?

First of all, The Rust Standard Library is divided into a number of focusedmodules,all listed further down this page. These modules arethe bedrock upon which all of Rust is forged, and they have mighty nameslikestd::slice andstd::cmp. Modules’ documentation typicallyincludes an overview of the module along with examples, and are a smartplace to start familiarizing yourself with the library.

Second, implicit methods onprimitive types are documented here. This canbe a source of confusion for two reasons:

While primitives are implemented by the compiler, the standard libraryimplements methods directly on the primitive types (and it is the onlylibrary that does so), which aredocumented in the section onprimitives.
The standard library exports many moduleswith the same name asprimitive types. These define additional items related to the primitivetype, but not the all-important methods.

So for example there is apage for the primitive typechar that lists all the methods that can be called oncharacters (very useful), and there is apage for the modulestd::char that documents iterator and error types created by these methods(rarely useful).

Note the documentation for the primitivesstr and[T] (alsocalled ‘slice’). Many method calls onString andVec<T> are actuallycalls to methods onstr and[T] respectively, viaderefcoercions.

Third, the standard library definesThe Rust Prelude, a small collectionof items - mostly traits - that are imported into every module of everycrate. The traits in the prelude are pervasive, making the preludedocumentation a good entry point to learning about the library.

And finally, the standard library exports a number of standard macros, andlists them on this page (technically, not all of the standardmacros are defined by the standard library - some are defined by thecompiler - but they are documented here the same). Like the prelude, thestandard macros are imported by default into all crates.

§Contributing changes to the documentation

Check out the Rust contribution guidelineshere.The source for this documentation can be found onGitHub in the ‘library/std/’ directory.To contribute changes, make sure you read the guidelines first, then submitpull-requests for your suggested changes.

Contributions are appreciated! If you see a part of the docs that can beimproved, submit a PR, or chat with us first onZulip#docs.

§A Tour of The Rust Standard Library

The rest of this crate documentation is dedicated to pointing out notablefeatures of The Rust Standard Library.

§Containers and collections

Theoption andresult modules define optional and error-handlingtypes,Option<T> andResult<T, E>. Theiter module definesRust’s iterator trait,Iterator, which works with thefor loop toaccess collections.

The standard library exposes three common ways to deal with contiguousregions of memory:

Vec<T> - A heap-allocatedvector that is resizable at runtime.
[T; N] - An inlinearray with a fixed size at compile time.
[T] - A dynamically sizedslice into any other kind of contiguousstorage, whether heap-allocated or not.

Slices can only be handled through some kind ofpointer, and as such comein many flavors such as:

&[T] -shared slice
&mut [T] -mutable slice
Box<[T]> -owned slice

str, a UTF-8 string slice, is a primitive type, and the standard librarydefines many methods for it. Ruststrs are typically accessed asimmutable references:&str. Use the ownedString for building andmutating strings.

For converting to strings use theformat! macro, and for converting fromstrings use theFromStr trait.

Data may be shared by placing it in a reference-counted box or theRctype, and if further contained in aCell orRefCell, may be mutatedas well as shared. Likewise, in a concurrent setting it is common to pair anatomically-reference-counted box,Arc, with aMutex to get the sameeffect.

Thecollections module defines maps, sets, linked lists and othertypical collection types, including the commonHashMap<K, V>.

§Platform abstractions and I/O

Besides basic data types, the standard library is largely concerned withabstracting over differences in common platforms, most notably Windows andUnix derivatives.

Common types of I/O, includingfiles,TCP, andUDP, are defined intheio,fs, andnet modules.

Thethread module contains Rust’s threading abstractions.synccontains further primitive shared memory types, includingatomic,mpmc andmpsc, 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 aftermain();but this is not guaranteed or ensured by tests. It is recommended that you write your own testsand run them on each platform you wish to support.This means that use ofstd before/after main, especially of features that interact with theOS or global state, is exempted from stability and portability guarantees and instead onlyprovided on a best-effort basis. Nevertheless bug reports are appreciated.

On the other handcore andalloc are most likely to work in such environments withthe caveat that any hookable behavior such as panics, oom handling or allocators will alsodepend 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)

Primitive Types§

array: A fixed-size array, denoted[T; N], for the element type,T, and thenon-negative compile-time constant size,N.
bool: The boolean type.
char: A character type.
f32: A 32-bit floating-point type (specifically, the “binary32” type defined in IEEE 754-2008).
f64: A 64-bit floating-point type (specifically, the “binary64” type defined in IEEE 754-2008).
fn: Function pointers, likefn(usize) -> bool.
i8: The 8-bit signed integer type.
i16: The 16-bit signed integer type.
i32: The 32-bit signed integer type.
i64: The 64-bit signed integer type.
i128: The 128-bit signed integer type.
isize: The pointer-sized signed integer type.
pointer: Raw, unsafe pointers,*const T, and*mut T.
reference: References,&T and&mut T.
slice: A dynamically-sized view into a contiguous sequence,[T].
str: String slices.
tuple: A finite heterogeneous sequence,(T, U, ..).
u8: The 8-bit unsigned integer type.
u16: The 16-bit unsigned integer type.
u32: The 32-bit unsigned integer type.
u64: The 64-bit unsigned integer type.
u128: The 128-bit unsigned integer type.
unit: The() type, also called “unit”.
usize: The pointer-sized unsigned integer type.
f16Experimental: A 16-bit floating-point type (specifically, the “binary16” type defined in IEEE 754-2008).
f128Experimental: A 128-bit floating-point type (specifically, the “binary128” type defined in IEEE 754-2008).
neverExperimental: The! type, also called “never”.

Modules§

alloc: Memory allocation APIs.
any: Utilities for dynamic typing or type reflection.
arch: SIMD and vendor intrinsics module.
array: Utilities for the array primitive type.
ascii: Operations on ASCII strings and characters.
backtrace: Support for capturing a stack backtrace of an OS thread
borrow: A module for working with borrowed data.
boxed: TheBox<T> type for heap allocation.
cell: Shareable mutable containers.
char: Utilities for thechar primitive type.
clone: TheClone trait for types that cannot be ‘implicitly copied’.
cmp: Utilities for comparing and ordering values.
collections: Collection types.
convert: Traits for conversions between types.
default: TheDefault trait for types with a default value.
env: Inspection and manipulation of the process’s environment.
error: Interfaces for working with Errors.
f32: Constants for thef32 single-precision floating point type.
f64: Constants for thef64 double-precision floating point type.
ffi: Utilities related to FFI bindings.
fmt: Utilities for formatting and printingStrings.
fs: Filesystem manipulation operations.
future: Asynchronous basic functionality.
hash: Generic hashing support.
hint: Hints to compiler that affects how code should be emitted or optimized.
i8Deprecation planned: Redundant constants module for thei8 primitive type.
i16Deprecation planned: Redundant constants module for thei16 primitive type.
i32Deprecation planned: Redundant constants module for thei32 primitive type.
i64Deprecation planned: Redundant constants module for thei64 primitive type.
i128Deprecation planned: Redundant constants module for thei128 primitive type.
io: Traits, helpers, and type definitions for core I/O functionality.
isizeDeprecation planned: Redundant constants module for theisize primitive type.
iter: Composable external iteration.
marker: Primitive traits and types representing basic properties of types.
mem: Basic functions for dealing with memory.
net: Networking primitives for TCP/UDP communication.
num: Additional functionality for numerics.
ops: Overloadable operators.
option: Optional values.
os: OS-specific functionality.
panic: Panic support in the standard library.
path: Cross-platform path manipulation.
pin: Types that pin data to a location in memory.
prelude: The Rust Prelude
primitive: This module reexports the primitive types to allow usage that is notpossibly shadowed by other declared types.
process: A module for working with processes.
ptr: Manually manage memory through raw pointers.
rc: Single-threaded reference-counting pointers. ‘Rc’ stands for ‘ReferenceCounted’.
result: Error handling with theResult type.
slice: Utilities for the slice primitive type.
str: Utilities for thestr primitive type.
string: A UTF-8–encoded, growable string.
sync: Useful synchronization primitives.
task: Types and Traits for working with asynchronous tasks.
thread: Native threads.
time: Temporal quantification.
u8Deprecation planned: Redundant constants module for theu8 primitive type.
u16Deprecation planned: Redundant constants module for theu16 primitive type.
u32Deprecation planned: Redundant constants module for theu32 primitive type.
u64Deprecation planned: Redundant constants module for theu64 primitive type.
u128Deprecation planned: Redundant constants module for theu128 primitive type.
usizeDeprecation planned: Redundant constants module for theusize primitive type.
vec: A contiguous growable array type with heap-allocated contents, writtenVec<T>.
assert_matchesExperimental: Unstable module containing the unstableassert_matches macro.
async_iterExperimental: Composable asynchronous iteration.
autodiffExperimental: This module provides support for automatic differentiation.
bstrExperimental: TheByteStr andByteString types and trait implementations.
f16Experimental: Constants for thef16 half-precision floating point type.
f128Experimental: Constants for thef128 quadruple-precision floating point type.
fromExperimental: Unstable module containing the unstableFrom derive macro.
intrinsicsExperimental: Compiler intrinsics.
patExperimental: Helper module for exporting thepattern_type macro
randomExperimental: Random value generation.
rangeExperimental: Experimental replacement range types
simdExperimental: Portable SIMD module.
unsafe_binderExperimental: Operators used to turn types into unsafe binders and back.

Macros§

assert: Asserts that a boolean expression istrue at runtime.
assert_eq: Asserts that two expressions are equal to each other (usingPartialEq).
assert_ne: Asserts that two expressions are not equal to each other (usingPartialEq).
cfg: Evaluates boolean combinations of configuration flags at compile-time.
column: Expands to the column number at which it was invoked.
compile_error: Causes compilation to fail with the given error message when encountered.
concat: Concatenates literals into a static string slice.
dbg: Prints and returns the value of a given expression for quick and dirtydebugging.
debug_assert: Asserts that a boolean expression istrue at runtime.
debug_assert_eq: Asserts that two expressions are equal to each other.
debug_assert_ne: Asserts that two expressions are not equal to each other.
env: Inspects an environment variable at compile time.
eprint: Prints to the standard error.
eprintln: Prints to the standard error, with a newline.
file: Expands to the file name in which it was invoked.
format: Creates aString using interpolation of runtime expressions.
format_args: Constructs parameters for the other string-formatting macros.
include: Parses a file as an expression or an item according to the context.
include_bytes: Includes a file as a reference to a byte array.
include_str: Includes a UTF-8 encoded file as a string.
is_x86_feature_detected: A macro to test atruntime whether a CPU feature is available onx86/x86-64 platforms.
line: Expands to the line number on which it was invoked.
matches: Returns whether the given expression matches the provided pattern.
module_path: Expands to a string that represents the current module path.
option_env: Optionally inspects an environment variable at compile time.
panic: Panics the current thread.
print: Prints to the standard output.
println: Prints to the standard output, with a newline.
stringify: Stringifies its arguments.
thread_local: Declare a new thread local storage key of typestd::thread::LocalKey.
todo: Indicates unfinished code.
tryDeprecated: Unwraps a result or propagates its error.
unimplemented: Indicates unimplemented code by panicking with a message of “not implemented”.
unreachable: Indicates unreachable code.
vec: Creates aVec containing the arguments.
write: Writes formatted data into a buffer.
writeln: Writes formatted data into a buffer, with a newline appended.
cfg_selectExperimental: Selects code at compile-time based oncfg predicates.
concat_bytesExperimental: Concatenates literals into a byte slice.
const_format_argsExperimental: Same asformat_args, but can be used in some const contexts.
log_syntaxExperimental: Prints passed tokens into the standard output.
trace_macrosExperimental: Enables or disables tracing functionality used for debugging other macros.

Keywords§

SelfTy: The implementing type within atrait orimpl block, or the current type within a typedefinition.
as: Cast between types, rename an import, or qualify paths to associated items.
async: Returns aFuture instead of blocking the current thread.
await: Suspend execution until the result of aFuture is ready.
become: Perform a tail-call of a function.
break: Exit early from a loop or labelled block.
const: Compile-time constants, compile-time blocks, compile-time evaluable functions, and raw pointers.
continue: Skip to the next iteration of a loop.
crate: A Rust binary or library.
dyn: dyn is a prefix of atrait object’s type.
else: What expression to evaluate when anif condition evaluates tofalse.
enum: A type that can be any one of several variants.
extern: Link to or import external code.
false: A value of typebool representing logicalfalse.
fn: A function or function pointer.
for: Iteration within, trait implementation withimpl, orhigher-ranked trait bounds(for<'a>).
if: Evaluate a block if a condition holds.
impl: Implementations of functionality for a type, or a type implementing some functionality.
in: Iterate over a series of values withfor.
let: Bind a value to a variable.
loop: Loop indefinitely.
match: Control flow based on pattern matching.
mod: Organize code intomodules.
move: Capture aclosure’s environment by value.
mut: A mutable variable, reference, or pointer.
pub: Make an item visible to others.
ref: Bind by reference during pattern matching.
return: Returns a value from a function.
self: The receiver of a method, or the current module.
static: A static item is a value which is valid for the entire duration of yourprogram (a'static lifetime).
struct: A type that is composed of other types.
super: The parent of the currentmodule.
trait: A common interface for a group of types.
true: A value of typebool representing logicaltrue.
type: Define analias for an existing type.
union: TheRust equivalent of a C-style union.
unsafe: Code or interfaces whosememory safety cannot be verified by the typesystem.
use: Import or rename items from other crates or modules, use values under ergonomic clonessemantic, or specify precise capturing withuse<..>.
where: Add constraints that must be upheld to use an item.
while: Loop while a condition is upheld.

Movatterモバイル変換

Crate std

Cratestd

§The Rust Standard Library

§How to read this documentation

§What is in the standard library documentation?

§Contributing changes to the documentation

§A Tour of The Rust Standard Library

§Containers and collections

§Platform abstractions and I/O

§Use before and after`main()`

Primitive Types§

Modules§

Macros§

Keywords§

Movatterモバイル変換

Crate std

Cratestd Copy item path

§The Rust Standard Library

§How to read this documentation

§What is in the standard library documentation?

§Contributing changes to the documentation

§A Tour of The Rust Standard Library

§Containers and collections

§Platform abstractions and I/O

§Use before and aftermain()

Primitive Types§

Modules§

Macros§

Keywords§

Cratestd

§Use before and after`main()`