Expand description
Utilities for safe zero-copy parsing and serialization.
This crate provides utilities which make it easy to perform zero-copy parsing and serialization by allowing zero-copy conversion to/from byte slices.
This is enabled by four core marker traits, each of which can be derived
(e.g., #[derive(FromBytes)]
):
FromZeroes
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 sequenceAsBytes
indicates that a type may safely be converted to a byte sequenceUnaligned
indicates that a type’s alignment requirement is 1
Types which implement a subset of these traits can then be converted to/from byte sequences with little to no runtime overhead.
Note that these traits are ignorant of byte order. For byte order-aware
types, see the byteorder
module.
Features
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.
byteorder
(enabled by default): Adds the byteorder
module and a
dependency on the byteorder
crate. The byteorder
module provides byte
order-aware equivalents of the multi-byte primitive numerical types. Unlike
their primitive equivalents, the types in this module have no alignment
requirement and support byte order conversions. This can be useful in
handling file formats, network packet layouts, etc which don’t provide
alignment guarantees and which may use a byte order different from that of
the execution platform.
simd
: When the simd
feature is enabled, FromZeroes
, FromBytes
, and
AsBytes
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.
Re-exports
pub use crate::byteorder::*;
Modules
- Byte order-aware numeric primitives.
Macros
- Safely transmutes a value of one type to a value of another type of the same size.
Structs
- A typed reference derived from a byte slice.
- A type with no alignment requirement.
Traits
- Types which are safe to treat as an immutable byte slice.
- A mutable or immutable reference to a byte slice.
- A mutable reference to a byte slice.
- Types for which any byte pattern is valid.
- Types for which a sequence of bytes all set to zero represents a valid instance of the type.
- Types with no alignment requirement.