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, memcmp, memset - These are core memory routines which are often generated by LLVM. Additionally, this library can make explicit calls to these functions. Their signatures are the same as found in C. These functions are often provided by the system libc, but can also be provided by the compiler-builtins crate.

• rust_begin_panic - This function takes four arguments, a fmt::Arguments, a &'static str, and two u32's. These four arguments dictate the panic message, the file at which panic was invoked, and the line and column inside the file. It is up to consumers of this core library to define this panic function; it is only required to never return. This requires a lang attribute named panic_impl.

• 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.

---

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

Modules

alloc	Memory allocation APIs
any	This module implements the Any trait, which enables dynamic typing of any 'static type through runtime reflection.
arch	SIMD and vendor intrinsics module.
array	Implementations of things like Eq for fixed-length arrays up to a certain length. Eventually, we should be able to generalize to all lengths.
ascii	Operations on ASCII strings and characters.
borrow	A module for working with borrowed data.
cell	Shareable mutable containers.
char	A character type.
clone	The Clone trait for types that cannot be 'implicitly copied'.
cmp	Functionality for ordering and comparison.
convert	Traits for conversions between types.
default	The Default trait for types which may have meaningful default values.
f32	This module provides constants which are specific to the implementation of the f32 floating point data type.
f64	This module provides constants which are specific to the implementation of the f64 floating point data type.
ffi	Utilities related to foreign function interface (FFI) bindings.
fmt	Utilities for formatting and printing strings.
future	Asynchronous values.
hash	Generic hashing support.
hint	Hints to compiler that affects how code should be emitted or optimized.
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.
iter	Composable external iteration.
marker	Primitive traits and types representing basic properties of types.
mem	Basic functions for dealing with memory.
num	Numeric traits and functions for the built-in numeric types.
ops	Overloadable operators.
option	Optional values.
panic	Panic support in the standard library.
pin	Types that pin data to its location in memory.
prelude	The libcore prelude
primitive	This module reexports the primitive types to allow usage that is not possibly shadowed by other declared types.
ptr	Manually manage memory through raw pointers.
result	Error handling with the Result type.
slice	Slice management and manipulation.
str	String manipulation.
sync	Synchronization primitives
task	Types and Traits for working with asynchronous tasks.
time	Temporal quantification.
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.
usize	The pointer-sized unsigned integer type.
intrinsics	Experimental Compiler intrinsics.
lazy	Experimental Lazy values and one-time initialization of static data.
panicking	Experimental Panic support for libcore
raw	Experimental Contains struct definitions for the layout of compiler built-in types.
unicode	Experimental

Macros

Clone	Derive macro generating an impl of the trait Clone.
Copy	Derive macro generating an impl of the trait Copy.
Debug	Derive macro generating an impl of the trait Debug.
Default	Derive macro generating an impl of the trait Default.
Eq	Derive macro generating an impl of the trait Eq.
Hash	Derive macro generating an impl of the trait Hash.
Ord	Derive macro generating an impl of the trait Ord.
PartialEq	Derive macro generating an impl of the trait PartialEq.
PartialOrd	Derive macro generating an impl of the trait PartialOrd.
RustcDecodable	Unstable implementation detail of the rustc compiler, do not use.
RustcEncodable	Unstable implementation detail of the rustc compiler, do not use.
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).
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.
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.
global_allocator	Attribute macro applied to a static to register it as a global allocator.
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.
matches	Returns whether the given expression matches any of the given patterns.
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.
stringify	Stringifies its arguments.
test	Attribute macro applied to a function to turn it into a unit test.
todo	Indicates unfinished code.
try	Deprecated Unwraps a result or propagates its error.
unimplemented	Indicates unimplemented code by panicking with a message of "not implemented".
unreachable	Indicates unreachable code.
write	Writes formatted data into a buffer.
writeln	Write formatted data into a buffer, with a newline appended.
asm	Experimental Inline assembly.
bench	Experimental Attribute macro applied to a function to turn it into a benchmark test.
cfg_accessible	Experimental Keeps the item it's applied to if the passed path is accessible, and removes it otherwise.
concat_idents	Experimental Concatenates identifiers into one identifier.
format_args_nl	Experimental Same as format_args, but adds a newline in the end.
global_asm	Experimental Module-level inline assembly.
llvm_asm	Experimental LLVM-style inline assembly.
log_syntax	Experimental Prints passed tokens into the standard output.
raw_const	Experimental Create a const raw pointer to a place, without creating an intermediate reference.
raw_mut	Experimental Create a mut raw pointer to a place, without creating an intermediate reference.
ready	Experimental Extracts the successful type of a Poll<T>.
test_case	Experimental An implementation detail of the #[test] and #[bench] macros.
trace_macros	Experimental Enables or disables tracing functionality used for debugging other macros.