Custom derive for traits from the zerocopy crate
APACHE-2.0 License
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 your interest in zerocopy's 0.8 alpha release! For an overview of what changes from 0.7, check out our draft release notes.
Zerocopy provides four derivable traits for zero-cost conversions:
TryFromBytes
indicates that a type may safely be converted fromFromZeros
indicates that a sequence of zero bytes represents a validFromBytes
indicates that a type may safely be converted from anIntoBytes
indicates that a type may safely be converted to a byteThis traits support sized types, slices, and slice DSTs.
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 layoutImmutable
indicates that a type is free from interior mutability,&mut
) borrowUnaligned
indicates that a type's alignment requirement is 1You should generally derive these marker traits whenever possible.
Zerocopy provides four macros for safe, zero-cost casting between types:
try_
[try_transmute])transmute
(conditionally) converts a value oftry_
[try_transmute_mut])transmute_mut
(conditionally) converts atry_
[try_transmute_ref])transmute_ref
(conditionally) converts aThese macros perform compile-time alignment and size checks, but cannot be used in generic contexts. For generic conversions, use the methods defined by the conversion traits.
Zerocopy provides byte-order aware integer types that support these
conversions; see the byteorder
module. These types are especially useful
for network parsing.
alloc
By default, zerocopy
is no_std
. When the alloc
feature is enabled,
the alloc
crate is added as a dependency, and some allocation-related
functionality is added.
std
By default, zerocopy
is no_std
. When the std
feature is enabled, the
std
crate is added as a dependency (ie, no_std
is disabled), and
support for some std
types is added. std
implies alloc
.
derive
Provides derives for the core marker traits via the zerocopy-derive
crate. These derives are re-exported from zerocopy
, so it is not
necessary to depend on zerocopy-derive
directly.
However, you may experience better compile times if you instead directly
depend on both zerocopy
and zerocopy-derive
in your Cargo.toml
,
since doing so will allow Rust to compile these crates in parallel. To do
so, do not enable the derive
feature, and list both dependencies in
your Cargo.toml
with the same leading non-zero version number; e.g:
[dependencies]
zerocopy = "0.X"
zerocopy-derive = "0.X"
simd
When the simd
feature is enabled, FromZeros
, FromBytes
, and
IntoBytes
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 the simd
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.
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:
unsafe
code with a precise rationale for its soundness thatFor more information, see our full soundness policy.
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.
See our MSRV policy.
Zerocopy uses GitHub Releases.
Disclaimer: Zerocopy is not an officially supported Google product.