Crate core

1.6.0 · Source

Expand description

§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. ↩

Re-exports§

pub use crate::macros::assert_matches;
pub use crate::macros::debug_assert_matches;
pub use crate::macros::cfg_select;
pub use legacy_int_modules::i8;Deprecation planned
pub use legacy_int_modules::i16;Deprecation planned
pub use legacy_int_modules::i32;Deprecation planned
pub use legacy_int_modules::i64;Deprecation planned
pub use legacy_int_modules::isize;Deprecation planned
pub use legacy_int_modules::u8;Deprecation planned
pub use legacy_int_modules::u16;Deprecation planned
pub use legacy_int_modules::u32;Deprecation planned
pub use legacy_int_modules::u64;Deprecation planned
pub use legacy_int_modules::usize;Deprecation planned
pub use legacy_int_modules::i128;Deprecation planned
pub use legacy_int_modules::u128;Deprecation planned
pub use crate::macros::builtin::derive;

Primitive Types§

array: A fixed-size array, denoted [T; N], for the element type, T, and the non-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, like fn(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
allow_attribute 🔒: The allow attribute suppresses lint diagnostics that would otherwise produce warnings or errors. It can be used on any lint or lint group (except those set to forbid).
any: Utilities for dynamic typing or type reflection.
arch: SIMD and vendor intrinsics module.
array: Utilities for the array primitive type.
as_keyword 🔒: Cast between types, rename an import, or qualify paths to associated items.
ascii: Operations on ASCII strings and characters.
async_keyword 🔒: Returns a Future instead of blocking the current thread.
await_keyword 🔒: Suspend execution until the result of a Future is ready.
become_keyword 🔒: Perform a tail-call of a function.
bool 🔒: impl bool {}
borrow: Utilities for working with borrowed data.
break_keyword 🔒: Exit early from a loop or labelled block.
cell: Shareable mutable containers.
cfg_attribute 🔒: Used for conditional compilation.
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.
cold_attribute 🔒: Hint to the compiler that a function is unlikely to be called.
const_keyword 🔒: Compile-time constants, compile-time blocks, compile-time evaluable functions, and raw pointers.
continue_keyword 🔒: Skip to the next iteration of a loop.
convert: Traits for conversions between types.
core_arch 🔒: core_arch
crate_keyword 🔒: A Rust binary or library.
default: The Default trait for types with a default value.
deny_attribute 🔒: Emits an error, preventing the compilation from finishing, when a lint check has failed. This is useful for enforcing rules or preventing certain patterns:
deprecated_attribute 🔒: Emits a warning during compilation when an item with this attribute is used. since and note are optional fields giving more detail about why the item is deprecated.
dyn_keyword 🔒: dyn is a prefix of a trait object’s type.
else_keyword 🔒: What expression to evaluate when an if condition evaluates to false.
enum_keyword 🔒: A type that can be any one of several variants.
error: Interfaces for working with Errors.
escape 🔒: Helper code for character escaping.
extern_keyword 🔒: Link to or import external code.
f32: Constants for the f32 single-precision floating point type.
f64: Constants for the f64 double-precision floating point type.
false_keyword 🔒: A value of type bool representing logical false.
ffi: Platform-specific types, as defined by C.
fmt: Utilities for formatting and printing strings.
fn_keyword 🔒: A function or function pointer.
for_keyword 🔒: Iteration with in, trait implementation with impl, or higher-ranked trait bounds (for<'a>).
forbid_attribute 🔒: Emits an error, preventing the compilation from finishing, when a lint check has failed.
future: Asynchronous basic functionality.
hash: Generic hashing support.
hint: Hints to compiler that affects how code should be emitted or optimized.
if_keyword 🔒: Evaluate a block if a condition holds.
impl_keyword 🔒: Implementations of functionality for a type, or a type implementing some functionality.
in_keyword 🔒: Iterate over a series of values with for.
inline_attribute 🔒: Suggest that the compiler inline a function at its call sites.
internal_macros 🔒
iter: Composable external iteration.
legacy_int_modules 🔒👻
let_keyword 🔒: Bind a value to a variable.
loop_keyword 🔒: Loop indefinitely.
macros 🔒
marker: Primitive traits and types representing basic properties of types.
match_keyword 🔒: Control flow based on pattern matching.
mem: Basic functions for dealing with memory, values, and types.
mod_keyword 🔒: Organize code into modules.
move_keyword 🔒: Capture a closure’s environment by value.
must_use_attribute 🔒: Warn when a value is ignored.
mut_keyword 🔒: A mutable variable, reference, or pointer.
net: Networking primitives for IP communication.
no_std_attribute 🔒: Prevents automatically linking the standard library.
num: Numeric traits and functions for the built-in numeric types.
ops: Overloadable operators.
option: Optional values.
panic: Panic support in core.
pin: Types that pin data to a location in memory.
prelude: The core prelude
prim_array 🔒: A fixed-size array, denoted [T; N], for the element type, T, and the non-negative compile-time constant size, N.
prim_bool 🔒: The boolean type.
prim_char 🔒: A character type.
prim_f32 🔒: A 32-bit floating-point type (specifically, the “binary32” type defined in IEEE 754-2008).
prim_f64 🔒: A 64-bit floating-point type (specifically, the “binary64” type defined in IEEE 754-2008).
prim_fn 🔒: Function pointers, like fn(usize) -> bool.
prim_i8 🔒: The 8-bit signed integer type.
prim_i16 🔒: The 16-bit signed integer type.
prim_i32 🔒: The 32-bit signed integer type.
prim_i64 🔒: The 64-bit signed integer type.
prim_i128 🔒: The 128-bit signed integer type.
prim_isize 🔒: The pointer-sized signed integer type.
prim_pointer 🔒: Raw, unsafe pointers, *const T, and *mut T.
prim_ref 🔒: References, &T and &mut T.
prim_slice 🔒: A dynamically-sized view into a contiguous sequence, [T].
prim_str 🔒: String slices.
prim_tuple 🔒: A finite heterogeneous sequence, (T, U, ..).
prim_u8 🔒: The 8-bit unsigned integer type.
prim_u16 🔒: The 16-bit unsigned integer type.
prim_u32 🔒: The 32-bit unsigned integer type.
prim_u64 🔒: The 64-bit unsigned integer type.
prim_u128 🔒: The 128-bit unsigned integer type.
prim_unit 🔒: The () type, also called “unit”.
prim_usize 🔒: The pointer-sized unsigned integer type.
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.
pub_keyword 🔒: Make an item visible to others.
range: Replacement range types
ref_keyword 🔒: Bind by reference during pattern matching.
result: Error handling with the Result type.
return_keyword 🔒: Returns a value from a function.
self_keyword 🔒: The receiver of a method, or the current module.
self_upper_keyword 🔒: The implementing type within a trait or impl block, or the current type within a type definition.
slice: Slice management and manipulation.
static_keyword 🔒: A static item is a value which is valid for the entire duration of your program (a 'static lifetime).
str: String manipulation.
struct_keyword 🔒: A type that is composed of other types.
super_keyword 🔒: The parent of the current module.
sync: Synchronization primitives
task: Types and Traits for working with asynchronous tasks.
time: Temporal quantification.
track_caller_attribute 🔒: Make a function report the location of its caller instead of its own.
trait_keyword 🔒: A common interface for a group of types.
true_keyword 🔒: A value of type bool representing logical true.
tuple 🔒
type_keyword 🔒: Define an alias for an existing type.
union_keyword 🔒: The Rust equivalent of a C-style union.
unit 🔒
unsafe_keyword 🔒: Code or interfaces whose memory safety cannot be verified by the type system.
use_keyword 🔒: Import or rename items from other crates or modules, use values under ergonomic clones semantic, or specify precise capturing with use<..>.
warn_attribute 🔒: Emits a warning during compilation when a lint check failed.
where_keyword 🔒: Add constraints that must be upheld to use an item.
while_keyword 🔒: Loop while a condition is upheld.
asserting 👻 Experimental
async_iterExperimental: Composable asynchronous iteration.
autodiffExperimental: This module provides support for automatic differentiation. For precise information on differences between the autodiff_forward and autodiff_reverse macros and how to use them, see their respective documentation.
bstrExperimental: The ByteStr type and trait implementations.
contractsExperimental: Unstable module containing the unstable contracts lang items and attribute macros.
core_simd 🔒 Experimental
f16Experimental: Constants for the f16 half-precision floating point type.
f128Experimental: Constants for the f128 quadruple-precision floating point type.
fieldExperimental: Field Reflection
fromExperimental: Unstable module containing the unstable From derive macro.
indexExperimental: Helper types for indexing slices.
intrinsicsExperimental: Compiler intrinsics.
ioExperimental: Traits, helpers, and type definitions for core I/O functionality.
offloadExperimental: This module provides support for gpu offloading. For technical details regarding the offload_kernel and how to use it, see their respective documentation.
osExperimental: OS-specific functionality.
panickingExperimental: Panic support for core
patExperimental: Helper module for exporting the pattern_type macro
prim_f16 🔒 Experimental: A 16-bit floating-point type (specifically, the “binary16” type defined in IEEE 754-2008).
prim_f128 🔒 Experimental: A 128-bit floating-point type (specifically, the “binary128” type defined in IEEE 754-2008).
prim_never 🔒 Experimental: The ! type, also called “never”.
processExperimental: A module for working with processes.
profilingExperimental: Profiling markers for compiler instrumentation.
randomExperimental: Random value generation.
simdExperimental: Portable SIMD module.
ub_checksExperimental: Provides the assert_unsafe_precondition macro as well as some utility functions that cover common preconditions.
unicode 👻 Experimental: Unicode internals used in liballoc and libstd. Not public API.
unsafe_binderExperimental: Operators used to turn types into unsafe binders and back.
viewExperimental: Helpers module for exporting the view_types macro.
wtf8 👻 Experimental: Implementation of the WTF-8 encoding.

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).
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.
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 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.
stringify: Stringifies its arguments.
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.
write: Writes formatted data into a buffer.
writeln: Writes formatted data into a buffer, with a newline appended.
assert_unsafe_preconditionExperimental: Checks that the preconditions of an unsafe function are followed.
concat_bytesExperimental: Concatenates literals into a byte slice.
const_format_argsExperimental: Same as format_args, but can be used in some const contexts.
direct_const_argExperimental: Creates a new style directly represented const argument.
format_args_nl 👻 Experimental: Same as format_args, but adds a newline in the end.
impl_partial_eq 👻 Experimental
impl_partial_eq_n 👻 Experimental
impl_partial_eq_ord 👻 Experimental
log_syntaxExperimental: Prints passed tokens into the standard output.
pattern_typeExperimental: Creates a pattern type.
trace_macrosExperimental: Enables or disables tracing functionality used for debugging other macros.
view_typeExperimental: Creates a view type.

Keywords§

SelfTy: The implementing type within a trait or impl block, or the current type within a type definition.
as: Cast between types, rename an import, or qualify paths to associated items.
async: Returns a Future instead of blocking the current thread.
await: Suspend execution until the result of a Future 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 a trait object’s type.
else: What expression to evaluate when an if condition evaluates to false.
enum: A type that can be any one of several variants.
extern: Link to or import external code.
false: A value of type bool representing logical false.
fn: A function or function pointer.
for: Iteration with in, trait implementation with impl, or higher-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 with for.
let: Bind a value to a variable.
loop: Loop indefinitely.
match: Control flow based on pattern matching.
mod: Organize code into modules.
move: Capture a closure’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 your program (a 'static lifetime).
struct: A type that is composed of other types.
super: The parent of the current module.
trait: A common interface for a group of types.
true: A value of type bool representing logical true.
type: Define an alias for an existing type.
union: The Rust equivalent of a C-style union.
unsafe: Code or interfaces whose memory safety cannot be verified by the type system.
use: Import or rename items from other crates or modules, use values under ergonomic clones semantic, or specify precise capturing with use<..>.
where: Add constraints that must be upheld to use an item.
while: Loop while a condition is upheld.

Attributes§

allow: The allow attribute suppresses lint diagnostics that would otherwise produce warnings or errors. It can be used on any lint or lint group (except those set to forbid).
cfg: Used for conditional compilation.
cold: Hint to the compiler that a function is unlikely to be called.
deny: Emits an error, preventing the compilation from finishing, when a lint check has failed. This is useful for enforcing rules or preventing certain patterns:
deprecated: Emits a warning during compilation when an item with this attribute is used. since and note are optional fields giving more detail about why the item is deprecated.
forbid: Emits an error, preventing the compilation from finishing, when a lint check has failed.
inline: Suggest that the compiler inline a function at its call sites.
must_use: Warn when a value is ignored.
no_std: Prevents automatically linking the standard library.
track_caller: Make a function report the location of its caller instead of its own.
warn: Emits a warning during compilation when a lint check failed.

Crate core

Crate core Copy item path

§The Rust Core Library

§How to use the core library

Re-exports§

Primitive Types§

Modules§

Macros§

Keywords§

Attributes§

Crate core