Crate `core`

The Rust Core Library

The Rust Core Library is the dependency-free¹ 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 to strlen. Their signatures are the same as found in C, but there are extra assumptions about their semantics: For memcpy, memmove, memset, memcmp, and bcmp, if the n 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 as ptr::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. The lang attribute is called eh_personality.

Strictly speaking, there are some symbols which are needed but they aren't always necessary. ↩

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.
assert_matches Unstable module containing the unstable assert_matches macro.
async_iter Composable asynchronous iteration.
autodiff Unstable module containing the unstable autodiff macro.
borrow Utilities for working with borrowed data.
bstr The ByteStr type and trait implementations.
cell Shareable mutable containers.
char Utilities for the char primitive type.
clone The Clone trait for types that cannot be 'implicitly copied'.
cmp Utilities for comparing and ordering values.
contracts Unstable module containing the unstable contracts lang items and attribute macros.
convert Traits for conversions between types.
default The Default trait for types with a default value.
error Interfaces for working with Errors.
f128 Constants for the f128 quadruple-precision floating point type.
f16 Constants for the f16 half-precision floating point type.
f32 Constants for the f32 single-precision floating point type.
f64 Constants for the f64 double-precision floating point type.
ffi Platform-specific types, as defined by C.
fmt Utilities for formatting and printing strings.
from Unstable module containing the unstable From derive macro.
future Asynchronous basic functionality.
hash Generic hashing support.
hint Hints to compiler that affects how code should be emitted or optimized.
index Helper types for indexing slices.
intrinsics Compiler intrinsics.
io Traits, helpers, and type definitions for core I/O functionality.
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 IP communication.
num Numeric traits and functions for the built-in numeric types.
ops Overloadable operators.
option Optional values.
os OS-specific functionality.
panic Panic support in the standard library.
panicking Panic support for core
pat Helper module for exporting the pattern_type macro
pin Types that pin data to a location in memory.
prelude The core prelude
primitive This module reexports the primitive types to allow usage that is not possibly shadowed by other declared types.
profiling Profiling markers for compiler instrumentation.
ptr Manually manage memory through raw pointers.
random Random value generation.
range
Experimental replacement range types
result Error handling with the Result type.
simd Portable SIMD module.
slice Slice management and manipulation.
str String manipulation.
sync Synchronization primitives
task Types and Traits for working with asynchronous tasks.
time Temporal quantification.
ub_checks Provides the assert_unsafe_precondition macro as well as some utility functions that cover common preconditions.
unsafe_binder Operators used to turn types into unsafe binders and back.

Macros

assert Asserts that a boolean expression is true at runtime.
assert_eq Asserts that two expressions are equal to each other (using PartialEq).
assert_ne Asserts that two expressions are not equal to each other (using PartialEq).
assert_unsafe_precondition Checks that the preconditions of an unsafe function are followed.
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.
concat_bytes Concatenates literals into a byte slice.
const_format_args Same as format_args, but can be used in some const contexts.
debug_assert Asserts that a boolean expression is true 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.
file Expands to the file name in which it was invoked.
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.
line Expands to the line number on which it was invoked.
log_syntax Prints passed tokens into the standard output.
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.

pattern_type

Creates a pattern type.

type Positive = std::pat::pattern_type!(i32 is 1..);

stringify Stringifies its arguments.
todo Indicates unfinished code.
trace_macros Enables or disables tracing functionality used for debugging other macros.
try Unwraps a result or propagates its error.

[raw-identifier syntax][ris]: r#try. [propagating-errors]: https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html#a-shortcut-for-propagating-errors-the--operator [ris]: https://doc.rust-lang.org/nightly/rust-by-example/compatibility/raw_identifiers.html
unimplemented Indicates unimplemented code by panicking with a message of "not implemented".
unreachable Indicates unreachable code.
write Writes formatted data into a buffer.
writeln Writes formatted data into a buffer, with a newline appended.

The Rust Core Library

How to use the core library

Modules

Experimental replacement range types

Macros