Expand description
Need more out of zerocopy? Submit a customer request issue!
Fast, safe, compile error. Pick two.
Zerocopy makes zero-cost memory manipulation effortless. We write unsafe
so you don’t have to.
Thanks for using zerocopy 0.8! For an overview of what changes from 0.7, check out our release notes, which include a step-by-step guide for upgrading from 0.7.
Have questions? Need help? Ask the maintainers on GitHub or on Discord!
§Overview
§Conversion Traits
Zerocopy provides four derivable traits for zero-cost conversions:
TryFromBytes
indicates that a type may safely be converted from certain byte sequences (conditional on runtime checks)FromZeros
indicates that a sequence of zero bytes represents a valid instance of a typeFromBytes
indicates that a type may safely be converted from an arbitrary byte sequenceIntoBytes
indicates that a type may safely be converted to a byte sequence
These traits support sized types, slices, and slice DSTs.
§Marker Traits
Zerocopy provides three derivable marker traits that do not provide any functionality themselves, but are required to call certain methods provided by the conversion traits:
KnownLayout
indicates that zerocopy can reason about certain layout qualities of a typeImmutable
indicates that a type is free from interior mutability, except by ownership or an exclusive (&mut
) borrowUnaligned
indicates that a type’s alignment requirement is 1
You should generally derive these marker traits whenever possible.
§Conversion Macros
Zerocopy provides six macros for safe casting between types:
- (
try_
)transmute
(conditionally) converts a value of one type to a value of another type of the same size - (
try_
)transmute_mut
(conditionally) converts a mutable reference of one type to a mutable reference of another type of the same size - (
try_
)transmute_ref
(conditionally) converts a mutable or immutable reference of one type to an immutable reference of another type of the same size
These macros perform compile-time size and alignment checks, meaning that unconditional casts have zero cost at runtime. Conditional casts do not need to validate size or alignment runtime, but do need to validate contents.
These macros cannot be used in generic contexts. For generic conversions, use the methods defined by the conversion traits.
§Byteorder-Aware Numerics
Zerocopy provides byte-order aware integer types that support these
conversions; see the byteorder
module. These types are especially useful
for network parsing.
§Cargo Features
-
alloc
By default,zerocopy
isno_std
. When thealloc
feature is enabled, thealloc
crate is added as a dependency, and some allocation-related functionality is added. -
std
By default,zerocopy
isno_std
. When thestd
feature is enabled, thestd
crate is added as a dependency (ie,no_std
is disabled), and support for somestd
types is added.std
impliesalloc
. -
derive
Provides derives for the core marker traits via thezerocopy-derive
crate. These derives are re-exported fromzerocopy
, so it is not necessary to depend onzerocopy-derive
directly.However, you may experience better compile times if you instead directly depend on both
zerocopy
andzerocopy-derive
in yourCargo.toml
, since doing so will allow Rust to compile these crates in parallel. To do so, do not enable thederive
feature, and list both dependencies in yourCargo.toml
with the same leading non-zero version number; e.g:[dependencies] zerocopy = "0.X" zerocopy-derive = "0.X"
To avoid the risk of duplicate import errors if one of your dependencies enables zerocopy’s
derive
feature, import derives asuse zerocopy_derive::*
rather than by name (e.g.,use zerocopy_derive::FromBytes
). -
simd
When thesimd
feature is enabled,FromZeros
,FromBytes
, andIntoBytes
impls are emitted for all stable SIMD types which exist on the target platform. Note that the layout of SIMD types is not yet stabilized, so these impls may be removed in the future if layout changes make them invalid. For more information, see the Unsafe Code Guidelines Reference page on the layout of packed SIMD vectors. -
simd-nightly
Enables thesimd
feature and adds support for SIMD types which are only available on nightly. Since these types are unstable, support for any type may be removed at any point in the future.
§Security Ethos
Zerocopy is expressly designed for use in security-critical contexts. We strive to ensure that that zerocopy code is sound under Rust’s current memory model, and any future memory model. We ensure this by:
- …not ‘guessing’ about Rust’s semantics.
We annotate
unsafe
code with a precise rationale for its soundness that cites a relevant section of Rust’s official documentation. When Rust’s documented semantics are unclear, we work with the Rust Operational Semantics Team to clarify Rust’s documentation. - …rigorously testing our implementation. We run tests using Miri, ensuring that zerocopy is sound across a wide array of supported target platforms of varying endianness and pointer width, and across both current and experimental memory models of Rust.
- …formally proving the correctness of our implementation. We apply formal verification tools like Kani to prove zerocopy’s correctness.
For more information, see our full soundness policy.
§Relationship to Project Safe Transmute
Project Safe Transmute is an official initiative of the Rust Project to develop language-level support for safer transmutation. The Project consults with crates like zerocopy to identify aspects of safer transmutation that would benefit from compiler support, and has developed an experimental, compiler-supported analysis which determines whether, for a given type, any value of that type may be soundly transmuted into another type. Once this functionality is sufficiently mature, zerocopy intends to replace its internal transmutability analysis (implemented by our custom derives) with the compiler-supported one. This change will likely be an implementation detail that is invisible to zerocopy’s users.
Project Safe Transmute will not replace the need for most of zerocopy’s
higher-level abstractions. The experimental compiler analysis is a tool for
checking the soundness of unsafe
code, not a tool to avoid writing
unsafe
code altogether. For the foreseeable future, crates like zerocopy
will still be required in order to provide higher-level abstractions on top
of the building block provided by Project Safe Transmute.
§MSRV
See our MSRV policy.
§Changelog
Zerocopy uses GitHub Releases.
Re-exports§
pub use crate::byte_slice::*;
pub use crate::byteorder::*;
pub use crate::error::*;
Modules§
- Traits for types that encapsulate a
[u8]
. - Byte order-aware numeric primitives.
- Types related to error reporting.
Macros§
- Includes a file and safely transmutes it to a value of an arbitrary type.
- Safely transmutes a value of one type to a value of another type of the same size.
- Safely transmutes a mutable reference of one type to a mutable reference of another type of the same size and compatible alignment.
- Safely transmutes a mutable or immutable reference of one type to an immutable reference of another type of the same size and compatible alignment.
- Conditionally transmutes a value of one type to a value of another type of the same size.
- Conditionally transmutes a mutable reference of one type to a mutable reference of another type of the same size and compatible alignment.
- Conditionally transmutes a mutable or immutable reference of one type to an immutable reference of another type of the same size and compatible alignment.
Structs§
- A typed reference derived from a byte slice.
- A type with no alignment requirement.
Traits§
- Types for which any bit pattern is valid.
- Types for which a sequence of bytes all set to zero represents a valid instance of the type.
- Types which are free from interior mutability.
- Types that can be converted to an immutable slice of initialized bytes.
- Indicates that zerocopy can reason about certain aspects of a type’s layout.
- Types for which some bit patterns are valid.
- Types with no alignment requirement.
Derive Macros§
- From
Bytes derive
Analyzes whether a type isFromBytes
. - From
Zeros derive
Analyzes whether a type isFromZeros
. - Immutable
derive
Analyzes whether a type isImmutable
. - Into
Bytes derive
Analyzes whether a type isIntoBytes
. - Known
Layout derive
ImplementsKnownLayout
. - TryFrom
Bytes derive
ImplementsTryFromBytes
. - Unaligned
derive
Analyzes whether a type isUnaligned
.