Expand description
§The Rust Core Library
The Rust Core Library is the dependency-free1 foundation of The Rust Standard Library. It is the portable glue between the language and its libraries, defining the intrinsic and primitive building blocks of all Rust code. It links to no upstream libraries, no system libraries, and no libc.
The core library is minimal: it isn’t even aware of heap allocation, nor does it provide concurrency or I/O. These things require platform integration, and this library is platform-agnostic.
§How to use the core library
Please note that all of these details are currently not considered stable.
This library is built on the assumption of a few existing symbols:
-
memcpy
,memmove
,memset
,memcmp
,bcmp
,strlen
- These are core memory routines which are generated by Rust codegen backends. Additionally, this library can make explicit calls tostrlen
. Their signatures are the same as found in C, but there are extra assumptions about their semantics: Formemcpy
,memmove
,memset
,memcmp
, andbcmp
, if then
parameter is 0, the function is assumed to not be UB, even if the pointers are NULL or dangling. (Note that making extra assumptions about these functions is common among compilers: clang and GCC do the same.) These functions are often provided by the system libc, but can also be provided by the compiler-builtins crate. Note that the library does not guarantee that it will always make these assumptions, so Rust user code directly calling the C functions should follow the C specification! The advice for Rust user code is to call the functions provided by this library instead (such asptr::copy
). -
Panic handler - This function takes one argument, a
&panic::PanicInfo
. It is up to consumers of this core library to define this panic function; it is only required to never return. You should mark your implementation using#[panic_handler]
. -
rust_eh_personality
- is used by the failure mechanisms of the compiler. This is often mapped to GCC’s personality function, but crates which do not trigger a panic can be assured that this function is never called. Thelang
attribute is calledeh_personality
.
Strictly speaking, there are some symbols which are needed but they aren’t always necessary. ↩
Modules§
- Memory allocation APIs
- Utilities for dynamic typing or type reflection.
- SIMD and vendor intrinsics module.
- Utilities for the array primitive type.
- Operations on ASCII strings and characters.
- Utilities for working with borrowed data.
- Shareable mutable containers.
- Utilities for the
char
primitive type. - The
Clone
trait for types that cannot be ‘implicitly copied’. - Utilities for comparing and ordering values.
- Traits for conversions between types.
- The
Default
trait for types with a default value. - Interfaces for working with Errors.
- Constants for the
f32
single-precision floating point type. - Constants for the
f64
double-precision floating point type. - Platform-specific types, as defined by C.
- Utilities for formatting and printing strings.
- Asynchronous basic functionality.
- Generic hashing support.
- Hints to compiler that affects how code should be emitted or optimized.
- i8
Deprecation planned Redundant constants module for thei8
primitive type. - i16
Deprecation planned Redundant constants module for thei16
primitive type. - i32
Deprecation planned Redundant constants module for thei32
primitive type. - i64
Deprecation planned Redundant constants module for thei64
primitive type. - i128
Deprecation planned Redundant constants module for thei128
primitive type. - isize
Deprecation planned Redundant constants module for theisize
primitive type. - Composable external iteration.
- Primitive traits and types representing basic properties of types.
- Basic functions for dealing with memory.
- Networking primitives for IP communication.
- Numeric traits and functions for the built-in numeric types.
- Overloadable operators.
- Optional values.
- Panic support in the standard library.
- Types that pin data to a location in memory.
- The core prelude
- This module reexports the primitive types to allow usage that is not possibly shadowed by other declared types.
- Manually manage memory through raw pointers.
- Error handling with the
Result
type. - Slice management and manipulation.
- String manipulation.
- Synchronization primitives
- Types and Traits for working with asynchronous tasks.
- Temporal quantification.
- u8
Deprecation planned Redundant constants module for theu8
primitive type. - u16
Deprecation planned Redundant constants module for theu16
primitive type. - u32
Deprecation planned Redundant constants module for theu32
primitive type. - u64
Deprecation planned Redundant constants module for theu64
primitive type. - u128
Deprecation planned Redundant constants module for theu128
primitive type. - usize
Deprecation planned Redundant constants module for theusize
primitive type. - assert_
matches Experimental Unstable module containing the unstableassert_matches
macro. - async_
iter Experimental Composable asynchronous iteration. - autodiff
Experimental Unstable module containing the unstableautodiff
macro. - f16
Experimental Constants for thef16
half-precision floating point type. - f128
Experimental Constants for thef128
quadruple-precision floating point type. - intrinsics
Experimental Compiler intrinsics. - io
Experimental Traits, helpers, and type definitions for core I/O functionality. - panicking
Experimental Panic support for core - pat
Experimental Helper module for exporting thepattern_type
macro - random
Experimental Random value generation. - range
Experimental Experimental replacement range types - simd
Experimental Portable SIMD module. - ub_
checks Experimental Provides theassert_unsafe_precondition
macro as well as some utility functions that cover common preconditions. - unicode
Experimental
Macros§
- Asserts that a boolean expression is
true
at runtime. - Asserts that two expressions are equal to each other (using
PartialEq
). - Asserts that two expressions are not equal to each other (using
PartialEq
). - Evaluates boolean combinations of configuration flags at compile-time.
- Expands to the column number at which it was invoked.
- Causes compilation to fail with the given error message when encountered.
- Concatenates literals into a static string slice.
- Asserts that a boolean expression is
true
at runtime. - Asserts that two expressions are equal to each other.
- Asserts that two expressions are not equal to each other.
- Inspects an environment variable at compile time.
- Expands to the file name in which it was invoked.
- Constructs parameters for the other string-formatting macros.
- Parses a file as an expression or an item according to the context.
- Includes a file as a reference to a byte array.
- Includes a UTF-8 encoded file as a string.
- Expands to the line number on which it was invoked.
- Returns whether the given expression matches the provided pattern.
- Expands to a string that represents the current module path.
- Optionally inspects an environment variable at compile time.
- Panics the current thread.
- Stringifies its arguments.
- Indicates unfinished code.
- try
Deprecated Unwraps a result or propagates its error. - Indicates unimplemented code by panicking with a message of “not implemented”.
- Indicates unreachable code.
- Writes formatted data into a buffer.
- Writes formatted data into a buffer, with a newline appended.
- assert_
unsafe_ precondition Experimental Checks that the preconditions of an unsafe function are followed. - cfg_
match Experimental A macro for defining#[cfg]
match-like statements. - concat_
bytes Experimental Concatenates literals into a byte slice. - concat_
idents Experimental Concatenates identifiers into one identifier. - const_
format_ args Experimental Same asformat_args
, but can be used in some const contexts. - format_
args_ nl Experimental Same asformat_args
, but adds a newline in the end. - log_
syntax Experimental Prints passed tokens into the standard output. - pattern_
type Experimental Creates a pattern type. - trace_
macros Experimental Enables or disables tracing functionality used for debugging other macros.