> for $larger_byteorder {
+ fn from(x: $name) -> $larger_byteorder {
+ $larger_byteorder::new(x.get().into())
+ }
+ }
+ )*
+
+ $(
+ impl TryFrom<$larger_byteorder_try> for $name {
+ type Error = TryFromIntError;
+ fn try_from(x: $larger_byteorder_try) -> Result<$name, TryFromIntError> {
+ x.get().try_into().map($name::new)
+ }
+ }
+ )*
+
impl AsRef<[u8; $bytes]> for $name {
fn as_ref(&self) -> &[u8; $bytes] {
&self.0
@@ -232,39 +329,130 @@ example of how it can be used for parsing UDP packets.
}
}
- impl_fmt_trait!($name, $native, Display);
- impl_fmt_trait!($name, $native, Octal);
- impl_fmt_trait!($name, $native, LowerHex);
- impl_fmt_trait!($name, $native, UpperHex);
- impl_fmt_trait!($name, $native, Binary);
+ impl_fmt_traits!($name, $native, $number_kind);
impl Debug for $name {
fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
- // This results in a format like "U16(42)"
- write!(f, concat!(stringify!($name), "({})"), self.get())
+ // This results in a format like "U16(42)".
+ f.debug_tuple(stringify!($name)).field(&self.get()).finish()
}
}
};
}
-define_type!(A, U16, u16, 16, 2, read_u16, write_u16, unsigned);
-define_type!(A, U32, u32, 32, 4, read_u32, write_u32, unsigned);
-define_type!(A, U64, u64, 64, 8, read_u64, write_u64, unsigned);
-define_type!(A, U128, u128, 128, 16, read_u128, write_u128, unsigned);
-define_type!(An, I16, i16, 16, 2, read_i16, write_i16, signed);
-define_type!(An, I32, i32, 32, 4, read_i32, write_i32, signed);
-define_type!(An, I64, i64, 64, 8, read_i64, write_i64, signed);
-define_type!(An, I128, i128, 128, 16, read_i128, write_i128, signed);
+define_type!(
+ A,
+ U16,
+ u16,
+ 16,
+ 2,
+ read_u16,
+ write_u16,
+ "unsigned integer",
+ [u32, u64, u128, usize],
+ [u32, u64, u128, usize],
+ [U32, U64, U128],
+ [U32, U64, U128]
+);
+define_type!(
+ A,
+ U32,
+ u32,
+ 32,
+ 4,
+ read_u32,
+ write_u32,
+ "unsigned integer",
+ [u64, u128],
+ [u64, u128],
+ [U64, U128],
+ [U64, U128]
+);
+define_type!(
+ A,
+ U64,
+ u64,
+ 64,
+ 8,
+ read_u64,
+ write_u64,
+ "unsigned integer",
+ [u128],
+ [u128],
+ [U128],
+ [U128]
+);
+define_type!(A, U128, u128, 128, 16, read_u128, write_u128, "unsigned integer", [], [], [], []);
+define_type!(
+ An,
+ I16,
+ i16,
+ 16,
+ 2,
+ read_i16,
+ write_i16,
+ "signed integer",
+ [i32, i64, i128, isize],
+ [i32, i64, i128, isize],
+ [I32, I64, I128],
+ [I32, I64, I128]
+);
+define_type!(
+ An,
+ I32,
+ i32,
+ 32,
+ 4,
+ read_i32,
+ write_i32,
+ "signed integer",
+ [i64, i128],
+ [i64, i128],
+ [I64, I128],
+ [I64, I128]
+);
+define_type!(
+ An,
+ I64,
+ i64,
+ 64,
+ 8,
+ read_i64,
+ write_i64,
+ "signed integer",
+ [i128],
+ [i128],
+ [I128],
+ [I128]
+);
+define_type!(An, I128, i128, 128, 16, read_i128, write_i128, "signed integer", [], [], [], []);
+define_type!(
+ An,
+ F32,
+ f32,
+ 32,
+ 4,
+ read_f32,
+ write_f32,
+ "floating point number",
+ [f64],
+ [],
+ [F64],
+ []
+);
+define_type!(An, F64, f64, 64, 8, read_f64, write_f64, "floating point number", [], [], [], []);
#[cfg(test)]
mod tests {
use byteorder::NativeEndian;
- use super::*;
- use crate::{AsBytes, FromBytes, Unaligned};
+ use {
+ super::*,
+ crate::{AsBytes, FromBytes, Unaligned},
+ };
- // A native integer type (u16, i32, etc)
- trait Native: FromBytes + AsBytes + Copy + Eq + Debug {
+ // A native integer type (u16, i32, etc).
+ trait Native: FromBytes + AsBytes + Copy + PartialEq + Debug {
const ZERO: Self;
const MAX_VALUE: Self;
@@ -323,7 +511,7 @@ mod tests {
macro_rules! impl_traits {
($name:ident, $native:ident, $bytes:expr, $sign:ident) => {
impl Native for $native {
- const ZERO: $native = 0;
+ const ZERO: $native = 0 as _;
const MAX_VALUE: $native = ::core::$native::MAX;
fn rand() -> $native {
@@ -370,6 +558,8 @@ mod tests {
impl_traits!(I32, i32, 4, signed);
impl_traits!(I64, i64, 8, signed);
impl_traits!(I128, i128, 16, signed);
+ impl_traits!(F32, f32, 4, signed);
+ impl_traits!(F64, f64, 8, signed);
macro_rules! call_for_all_types {
($fn:ident, $byteorder:ident) => {
@@ -381,6 +571,8 @@ mod tests {
$fn::>();
$fn::>();
$fn::>();
+ $fn::>();
+ $fn::>();
};
}
@@ -466,4 +658,13 @@ mod tests {
call_for_all_types!(test_non_native_endian, NonNativeEndian);
}
+
+ #[test]
+ fn test_debug_impl() {
+ // Ensure that Debug applies format options to the inner value.
+ let val = U16::::new(10);
+ assert_eq!(format!("{:?}", val), "U16(10)");
+ assert_eq!(format!("{:03?}", val), "U16(010)");
+ assert_eq!(format!("{:x?}", val), "U16(a)");
+ }
}
diff --git a/src/lib.rs b/src/lib.rs
index f14a27be72..a30c82c470 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -2,6 +2,11 @@
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
+// After updating the following doc comment, make sure to run the following
+// command to update `README.md` based on its contents:
+//
+// ./generate-readme.sh > README.md
+
//! Utilities for safe zero-copy parsing and serialization.
//!
//! This crate provides utilities which make it easy to perform zero-copy
@@ -21,8 +26,29 @@
//!
//! 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.
+//!
+//! `simd`: When the `simd` feature is enabled, `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-layout].
+//!
+//! `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.
+//!
+//! [simd-layout]: https://rust-lang.github.io/unsafe-code-guidelines/layout/packed-simd-vectors.html
+#![deny(missing_docs, clippy::indexing_slicing)]
#![cfg_attr(not(test), no_std)]
+#![cfg_attr(feature = "simd-nightly", feature(stdsimd))]
#![recursion_limit = "2048"]
pub mod byteorder;
@@ -30,21 +56,36 @@ pub mod byteorder;
pub use crate::byteorder::*;
pub use zerocopy_derive::*;
-use core::cell::{Ref, RefMut};
-use core::fmt::{self, Debug, Display, Formatter};
-use core::marker::PhantomData;
-use core::mem;
-use core::ops::{Deref, DerefMut};
-use core::slice;
-
-// This is a hack to allow derives of FromBytes, AsBytes, and Unaligned to work
-// in this crate. They assume that zerocopy is linked as an extern crate, so
-// they access items from it as `zerocopy::Xxx`. This makes that still work.
+use core::{
+ cell::{Ref, RefMut},
+ cmp::Ordering,
+ fmt::{self, Debug, Display, Formatter},
+ marker::PhantomData,
+ mem::{self, MaybeUninit},
+ num::{
+ NonZeroI128, NonZeroI16, NonZeroI32, NonZeroI64, NonZeroI8, NonZeroIsize, NonZeroU128,
+ NonZeroU16, NonZeroU32, NonZeroU64, NonZeroU8, NonZeroUsize, Wrapping,
+ },
+ ops::{Deref, DerefMut},
+ ptr, slice,
+};
+
+#[cfg(feature = "alloc")]
+extern crate alloc;
+#[cfg(feature = "alloc")]
+use {
+ alloc::boxed::Box,
+ core::{alloc::Layout, ptr::NonNull},
+};
+
+// This is a hack to allow derives of `FromBytes`, `AsBytes`, and `Unaligned` to
+// work in this crate. They assume that zerocopy is linked as an extern crate,
+// so they access items from it as `zerocopy::Xxx`. This makes that still work.
mod zerocopy {
pub use crate::*;
}
-// implement an unsafe trait for a range of container types
+// Implements an unsafe trait for a range of container types.
macro_rules! impl_for_composite_types {
($trait:ident) => {
unsafe impl $trait for PhantomData {
@@ -61,6 +102,16 @@ macro_rules! impl_for_composite_types {
{
}
}
+ // According to the `Wrapping` docs, "`Wrapping` is guaranteed to
+ // have the same layout and ABI as `T`."
+ unsafe impl $trait for Wrapping {
+ fn only_derive_is_allowed_to_implement_this_trait()
+ where
+ Self: Sized,
+ {
+ }
+ }
+ // Unit type has an empty representation.
unsafe impl $trait for () {
fn only_derive_is_allowed_to_implement_this_trait()
where
@@ -68,46 +119,64 @@ macro_rules! impl_for_composite_types {
{
}
}
- impl_for_array_sizes!($trait);
+ // Constant sized array with elements implementing `$trait`.
+ unsafe impl $trait for [T; N] {
+ fn only_derive_is_allowed_to_implement_this_trait()
+ where
+ Self: Sized,
+ {
+ }
+ }
};
}
-// implement an unsafe trait for all signed and unsigned primitive types
-macro_rules! impl_for_primitives {
- ($trait:ident) => (
- impl_for_primitives!(@inner $trait, u8, i8, u16, i16, u32, i32, u64, i64, u128, i128, usize, isize, f32, f64);
- );
- (@inner $trait:ident, $type:ty) => (
- unsafe impl $trait for $type {
- fn only_derive_is_allowed_to_implement_this_trait() where Self: Sized {}
- }
- );
- (@inner $trait:ident, $type:ty, $($types:ty),*) => (
- unsafe impl $trait for $type {
- fn only_derive_is_allowed_to_implement_this_trait() where Self: Sized {}
- }
- impl_for_primitives!(@inner $trait, $($types),*);
+/// Implements `$trait` for one or more `$type`s.
+macro_rules! impl_for_types {
+ ($trait:ident, $($types:ty),* $(,)?) => (
+ $(
+ unsafe impl $trait for $types {
+ fn only_derive_is_allowed_to_implement_this_trait() {}
+ }
+ )*
);
}
-// implement an unsafe trait for all array lengths up to 64, plus several
-// useful powers-of-two beyond that, plus lengths needed by Fuchsia with
-// an element type that implements the trait
-macro_rules! impl_for_array_sizes {
- ($trait:ident) => (
- impl_for_array_sizes!(@inner $trait, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 98, 126, 128, 236, 255, 256, 512, 1024, 2048, 4096, 8192, 16384, 32768, 65536);
- );
- (@inner $trait:ident, $n:expr) => (
- unsafe impl $trait for [T; $n] {
- fn only_derive_is_allowed_to_implement_this_trait() where Self: Sized {}
- }
- );
- (@inner $trait:ident, $n:expr, $($ns:expr),*) => (
- unsafe impl $trait for [T; $n] {
- fn only_derive_is_allowed_to_implement_this_trait() where Self: Sized {}
- }
- impl_for_array_sizes!(@inner $trait, $($ns),*);
- );
+/// Implements `$trait` for all signed and unsigned primitive types.
+macro_rules! impl_for_primitives {
+ ($trait:ident) => {
+ impl_for_types!(
+ $trait,
+ u8,
+ i8,
+ u16,
+ i16,
+ u32,
+ i32,
+ u64,
+ i64,
+ u128,
+ i128,
+ usize,
+ isize,
+ f32,
+ f64,
+ // The Rust compiler reuses `0` value to represent `None`, so
+ // `size_of::>() == size_of::()`; see
+ // `NonZeroXXX` documentation.
+ Option,
+ Option,
+ Option,
+ Option,
+ Option,
+ Option,
+ Option,
+ Option,
+ Option,
+ Option,
+ Option,
+ Option,
+ );
+ };
}
/// Types for which any byte pattern is valid.
@@ -166,12 +235,154 @@ macro_rules! impl_for_array_sizes {
/// Whether a struct is soundly `FromBytes` therefore solely depends on whether
/// its fields are `FromBytes`.
pub unsafe trait FromBytes {
- // NOTE: The Self: Sized bound makes it so that FromBytes is still object
+ // The `Self: Sized` bound makes it so that `FromBytes` is still object
// safe.
#[doc(hidden)]
fn only_derive_is_allowed_to_implement_this_trait()
where
Self: Sized;
+
+ /// Reads a copy of `Self` from `bytes`.
+ ///
+ /// If `bytes.len() != size_of::()`, `read_from` returns `None`.
+ fn read_from(bytes: B) -> Option
+ where
+ Self: Sized,
+ {
+ let lv = LayoutVerified::<_, Unalign>::new_unaligned(bytes)?;
+ Some(lv.read().into_inner())
+ }
+
+ /// Reads a copy of `Self` from the prefix of `bytes`.
+ ///
+ /// `read_from_prefix` reads a `Self` from the first `size_of::()`
+ /// bytes of `bytes`. If `bytes.len() < size_of::()`, it returns
+ /// `None`.
+ fn read_from_prefix(bytes: B) -> Option
+ where
+ Self: Sized,
+ {
+ let (lv, _suffix) = LayoutVerified::<_, Unalign>::new_unaligned_from_prefix(bytes)?;
+ Some(lv.read().into_inner())
+ }
+
+ /// Reads a copy of `Self` from the suffix of `bytes`.
+ ///
+ /// `read_from_suffix` reads a `Self` from the last `size_of::()`
+ /// bytes of `bytes`. If `bytes.len() < size_of::()`, it returns
+ /// `None`.
+ fn read_from_suffix(bytes: B) -> Option
+ where
+ Self: Sized,
+ {
+ let (_prefix, lv) = LayoutVerified::<_, Unalign>::new_unaligned_from_suffix(bytes)?;
+ Some(lv.read().into_inner())
+ }
+
+ /// Creates an instance of `Self` from zeroed bytes.
+ fn new_zeroed() -> Self
+ where
+ Self: Sized,
+ {
+ unsafe {
+ // SAFETY: `FromBytes` says all bit patterns (including zeroes) are
+ // legal.
+ mem::zeroed()
+ }
+ }
+
+ /// Creates a `Box` from zeroed bytes.
+ ///
+ /// This function is useful for allocating large values on the heap and
+ /// zero-initializing them, without ever creating a temporary instance of
+ /// `Self` on the stack. For example, `<[u8; 1048576]>::new_box_zeroed()`
+ /// will allocate `[u8; 1048576]` directly on the heap; it does not require
+ /// storing `[u8; 1048576]` in a temporary variable on the stack.
+ ///
+ /// On systems that use a heap implementation that supports allocating from
+ /// pre-zeroed memory, using `new_box_zeroed` (or related functions) may
+ /// have performance benefits.
+ ///
+ /// Note that `Box` can be converted to `Arc` and other
+ /// container types without reallocation.
+ ///
+ /// # Panics
+ ///
+ /// Panics if allocation of `size_of::()` bytes fails.
+ #[cfg(feature = "alloc")]
+ fn new_box_zeroed() -> Box
+ where
+ Self: Sized,
+ {
+ // If `T` is a ZST, then return a proper boxed instance of it. There is
+ // no allocation, but `Box` does require a correct dangling pointer.
+ let layout = Layout::new::();
+ if layout.size() == 0 {
+ return Box::new(Self::new_zeroed());
+ }
+
+ unsafe {
+ let ptr = alloc::alloc::alloc_zeroed(layout) as *mut Self;
+ if ptr.is_null() {
+ alloc::alloc::handle_alloc_error(layout);
+ }
+ Box::from_raw(ptr)
+ }
+ }
+
+ /// Creates a `Box<[Self]>` (a boxed slice) from zeroed bytes.
+ ///
+ /// This function is useful for allocating large values of `[Self]` on the
+ /// heap and zero-initializing them, without ever creating a temporary
+ /// instance of `[Self; _]` on the stack. For example,
+ /// `u8::new_box_slice_zeroed(1048576)` will allocate the slice directly on
+ /// the heap; it does not require storing the slice on the stack.
+ ///
+ /// On systems that use a heap implementation that supports allocating from
+ /// pre-zeroed memory, using `new_box_slice_zeroed` may have performance
+ /// benefits.
+ ///
+ /// If `Self` is a zero-sized type, then this function will return a
+ /// `Box<[Self]>` that has the correct `len`. Such a box cannot contain any
+ /// actual information, but its `len()` property will report the correct
+ /// value.
+ ///
+ /// # Panics
+ ///
+ /// * Panics if `size_of::() * len` overflows.
+ /// * Panics if allocation of `size_of::() * len` bytes fails.
+ #[cfg(feature = "alloc")]
+ fn new_box_slice_zeroed(len: usize) -> Box<[Self]>
+ where
+ Self: Sized,
+ {
+ // TODO(#2): Use `Layout::repeat` when `alloc_layout_extra` is
+ // stabilized.
+ //
+ // This will intentionally panic if it overflows.
+ unsafe {
+ // SAFETY: `from_size_align_unchecked` is sound because
+ // slice_len_bytes is guaranteed to be properly aligned (we just
+ // multiplied it by `size_of::()`, which is guaranteed to be
+ // aligned).
+ let layout = Layout::from_size_align_unchecked(
+ mem::size_of::().checked_mul(len).unwrap(),
+ mem::align_of::(),
+ );
+ if layout.size() != 0 {
+ let ptr = alloc::alloc::alloc_zeroed(layout) as *mut Self;
+ if ptr.is_null() {
+ alloc::alloc::handle_alloc_error(layout);
+ }
+ Box::from_raw(slice::from_raw_parts_mut(ptr, len))
+ } else {
+ // `Box<[T]>` does not allocate when `T` is zero-sized or when
+ // `len` is zero, but it does require a non-null dangling
+ // pointer for its allocation.
+ Box::from_raw(slice::from_raw_parts_mut(NonNull::::dangling().as_ptr(), len))
+ }
+ }
+ }
}
/// Types which are safe to treat as an immutable byte slice.
@@ -228,25 +439,26 @@ pub unsafe trait FromBytes {
///
/// [Rust Reference]: https://doc.rust-lang.org/reference/type-layout.html
pub unsafe trait AsBytes {
+ // The `Self: Sized` bound makes it so that `AsBytes` is still object safe.
#[doc(hidden)]
fn only_derive_is_allowed_to_implement_this_trait()
where
Self: Sized;
- /// Get the bytes of this value.
+ /// Gets the bytes of this value.
///
/// `as_bytes` provides access to the bytes of this value as an immutable
/// byte slice.
fn as_bytes(&self) -> &[u8] {
unsafe {
- // NOTE: This function does not have a Self: Sized bound.
- // size_of_val works for unsized values too.
+ // Note that this method does not have a `Self: Sized` bound;
+ // `size_of_val` works for unsized values too.
let len = mem::size_of_val(self);
slice::from_raw_parts(self as *const Self as *const u8, len)
}
}
- /// Get the bytes of this value mutably.
+ /// Gets the bytes of this value mutably.
///
/// `as_bytes_mut` provides access to the bytes of this value as a mutable
/// byte slice.
@@ -255,16 +467,81 @@ pub unsafe trait AsBytes {
Self: FromBytes,
{
unsafe {
- // NOTE: This function does not have a Self: Sized bound.
- // size_of_val works for unsized values too.
+ // Note that this method does not have a `Self: Sized` bound;
+ // `size_of_val` works for unsized values too.
let len = mem::size_of_val(self);
slice::from_raw_parts_mut(self as *mut Self as *mut u8, len)
}
}
+
+ /// Writes a copy of `self` to `bytes`.
+ ///
+ /// If `bytes.len() != size_of_val(self)`, `write_to` returns `None`.
+ fn write_to(&self, mut bytes: B) -> Option<()> {
+ if bytes.len() != mem::size_of_val(self) {
+ return None;
+ }
+
+ bytes.copy_from_slice(self.as_bytes());
+ Some(())
+ }
+
+ /// Writes a copy of `self` to the prefix of `bytes`.
+ ///
+ /// `write_to_prefix` writes `self` to the first `size_of_val(self)` bytes
+ /// of `bytes`. If `bytes.len() < size_of_val(self)`, it returns `None`.
+ fn write_to_prefix(&self, mut bytes: B) -> Option<()> {
+ let size = mem::size_of_val(self);
+ bytes.get_mut(..size)?.copy_from_slice(self.as_bytes());
+ Some(())
+ }
+
+ /// Writes a copy of `self` to the suffix of `bytes`.
+ ///
+ /// `write_to_suffix` writes `self` to the last `size_of_val(self)` bytes of
+ /// `bytes`. If `bytes.len() < size_of_val(self)`, it returns `None`.
+ fn write_to_suffix(&self, mut bytes: B) -> Option<()> {
+ let start = bytes.len().checked_sub(mem::size_of_val(self))?;
+ bytes
+ .get_mut(start..)
+ .expect("`start` should be in-bounds of `bytes`")
+ .copy_from_slice(self.as_bytes());
+ Some(())
+ }
}
-// Special case for bool
-unsafe impl AsBytes for bool {
+// Special case for `AsBytes`-only types (they are not included in
+// `impl_for_primitives!`).
+impl_for_types!(
+ AsBytes,
+ bool,
+ char,
+ str,
+ // `NonZeroXxx` is `AsBytes`, but not `FromBytes`.
+ //
+ // SAFETY: `NonZeroXxx` has the same layout as its associated primitive.
+ // Since it is the same size, this guarantees it has no padding - integers
+ // have no padding, and there's no room for padding if it can represent all
+ // of the same values except 0.
+ NonZeroU8,
+ NonZeroU16,
+ NonZeroU32,
+ NonZeroU64,
+ NonZeroU128,
+ NonZeroUsize,
+ NonZeroI8,
+ NonZeroI16,
+ NonZeroI32,
+ NonZeroI64,
+ NonZeroI128,
+ NonZeroIsize,
+);
+
+// `MaybeUninit` is `FromBytes`, but never `AsBytes` since it may contain
+// uninitialized bytes.
+//
+// SAFETY: `MaybeUninit` has no restrictions on its contents.
+unsafe impl FromBytes for MaybeUninit {
fn only_derive_is_allowed_to_implement_this_trait()
where
Self: Sized,
@@ -291,7 +568,7 @@ impl_for_composite_types!(AsBytes);
/// is marked as `Unaligned` which violates this contract, it may cause
/// undefined behavior.
pub unsafe trait Unaligned {
- // NOTE: The Self: Sized bound makes it so that Unaligned is still object
+ // The `Self: Sized` bound makes it so that `Unaligned` is still object
// safe.
#[doc(hidden)]
fn only_derive_is_allowed_to_implement_this_trait()
@@ -299,21 +576,280 @@ pub unsafe trait Unaligned {
Self: Sized;
}
-unsafe impl Unaligned for u8 {
- fn only_derive_is_allowed_to_implement_this_trait()
- where
- Self: Sized,
- {
+impl_for_types!(Unaligned, u8, i8, bool);
+impl_for_composite_types!(Unaligned);
+
+// SIMD support
+//
+// Per the Unsafe Code Guidelines Reference [1]:
+//
+// Packed SIMD vector types are `repr(simd)` homogeneous tuple-structs
+// containing `N` elements of type `T` where `N` is a power-of-two and the
+// size and alignment requirements of `T` are equal:
+//
+// ```rust
+// #[repr(simd)]
+// struct Vector(T_0, ..., T_(N - 1));
+// ```
+//
+// ...
+//
+// The size of `Vector` is `N * size_of::()` and its alignment is an
+// implementation-defined function of `T` and `N` greater than or equal to
+// `align_of::()`.
+//
+// ...
+//
+// Vector elements are laid out in source field order, enabling random access
+// to vector elements by reinterpreting the vector as an array:
+//
+// ```rust
+// union U {
+// vec: Vector,
+// arr: [T; N]
+// }
+//
+// assert_eq!(size_of::>(), size_of::<[T; N]>());
+// assert!(align_of::>() >= align_of::<[T; N]>());
+//
+// unsafe {
+// let u = U { vec: Vector(t_0, ..., t_(N - 1)) };
+//
+// assert_eq!(u.vec.0, u.arr[0]);
+// // ...
+// assert_eq!(u.vec.(N - 1), u.arr[N - 1]);
+// }
+// ```
+//
+// Given this background, we can observe that:
+// - The size and bit pattern requirements of a SIMD type are equivalent to the
+// equivalent array type. Thus, for any SIMD type whose primitive `T` is
+// `FromBytes`, that SIMD type is also `FromBytes`. The same holds for
+// `AsBytes`.
+// - Since no upper bound is placed on the alignment, no SIMD type can be
+// guaranteed to be `Unaligned`.
+//
+// Also per [1]:
+//
+// This chapter represents the consensus from issue #38. The statements in
+// here are not (yet) "guaranteed" not to change until an RFC ratifies them.
+//
+// See issue #38 [2]. While this behavior is not technically guaranteed, the
+// likelihood that the behavior will change such that SIMD types are no longer
+// `FromBytes` or `AsBytes` is next to zero, as that would defeat the entire
+// purpose of SIMD types. Nonetheless, we put this behavior behind the `simd`
+// Cargo feature, which requires consumers to opt into this stability hazard.
+//
+// [1] https://rust-lang.github.io/unsafe-code-guidelines/layout/packed-simd-vectors.html
+// [2] https://github.com/rust-lang/unsafe-code-guidelines/issues/38
+#[cfg(feature = "simd")]
+mod simd {
+ /// Defines a module which implements `FromBytes` and `AsBytes` for a set of
+ /// types from a module in `core::arch`.
+ ///
+ /// `$arch` is both the name of the defined module and the name of the
+ /// module in `core::arch`, and `$typ` is the list of items from that module
+ /// to implement `FromBytes` and `AsBytes` for.
+ #[allow(unused_macros)] // `allow(unused_macros)` is needed because some
+ // target/feature combinations don't emit any impls
+ // and thus don't use this macro.
+ macro_rules! simd_arch_mod {
+ ($arch:ident, $($typ:ident),*) => {
+ mod $arch {
+ use core::arch::$arch::{$($typ),*};
+
+ use crate::*;
+
+ impl_for_types!(FromBytes, $($typ),*);
+ impl_for_types!(AsBytes, $($typ),*);
+ }
+ };
+ }
+
+ #[cfg(target_arch = "x86")]
+ simd_arch_mod!(x86, __m128, __m128d, __m128i, __m256, __m256d, __m256i);
+ #[cfg(target_arch = "x86_64")]
+ simd_arch_mod!(x86_64, __m128, __m128d, __m128i, __m256, __m256d, __m256i);
+ #[cfg(target_arch = "wasm32")]
+ simd_arch_mod!(wasm32, v128);
+ #[cfg(all(feature = "simd-nightly", target_arch = "powerpc"))]
+ simd_arch_mod!(
+ powerpc,
+ vector_bool_long,
+ vector_double,
+ vector_signed_long,
+ vector_unsigned_long
+ );
+ #[cfg(all(feature = "simd-nightly", target_arch = "powerpc64"))]
+ simd_arch_mod!(
+ powerpc64,
+ vector_bool_long,
+ vector_double,
+ vector_signed_long,
+ vector_unsigned_long
+ );
+ #[cfg(all(feature = "simd-nightly", target_arch = "aarch64"))]
+ #[rustfmt::skip]
+ simd_arch_mod!(
+ aarch64, float32x2_t, float32x4_t, float64x1_t, float64x2_t, int8x8_t, int8x8x2_t,
+ int8x8x3_t, int8x8x4_t, int8x16_t, int8x16x2_t, int8x16x3_t, int8x16x4_t, int16x4_t,
+ int16x8_t, int32x2_t, int32x4_t, int64x1_t, int64x2_t, poly8x8_t, poly8x8x2_t, poly8x8x3_t,
+ poly8x8x4_t, poly8x16_t, poly8x16x2_t, poly8x16x3_t, poly8x16x4_t, poly16x4_t, poly16x8_t,
+ poly64x1_t, poly64x2_t, uint8x8_t, uint8x8x2_t, uint8x8x3_t, uint8x8x4_t, uint8x16_t,
+ uint8x16x2_t, uint8x16x3_t, uint8x16x4_t, uint16x4_t, uint16x8_t, uint32x2_t, uint32x4_t,
+ uint64x1_t, uint64x2_t
+ );
+ #[cfg(all(feature = "simd-nightly", target_arch = "arm"))]
+ #[rustfmt::skip]
+ simd_arch_mod!(arm, int8x4_t, uint8x4_t);
+}
+
+/// A type with no alignment requirement.
+///
+/// A `Unalign` wraps a `T`, removing any alignment requirement. `Unalign`
+/// has the same size and ABI as `T`, but not necessarily the same alignment.
+/// This is useful if a type with an alignment requirement needs to be read from
+/// a chunk of memory which provides no alignment guarantees.
+///
+/// Since `Unalign` has no alignment requirement, the inner `T` may not be
+/// properly aligned in memory, and so `Unalign` provides no way of getting a
+/// reference to the inner `T`. Instead, the `T` may only be obtained by value
+/// (see [`get`] and [`into_inner`]).
+///
+/// [`get`]: Unalign::get
+/// [`into_inner`]: Unalign::into_inner
+#[derive(FromBytes, Unaligned, Copy)]
+#[repr(C, packed)]
+pub struct Unalign(T);
+
+// Note that `Unalign: Clone` only if `T: Copy`. Since the inner `T` may not be
+// aligned, there's no way to safely call `T::clone`, and so a `T: Clone` bound
+// is not sufficient to implement `Clone` for `Unalign`.
+impl Clone for Unalign {
+ fn clone(&self) -> Unalign {
+ *self
+ }
+}
+
+impl Unalign {
+ /// Constructs a new `Unalign`.
+ pub fn new(val: T) -> Unalign {
+ Unalign(val)
+ }
+
+ /// Consumes `self`, returning the inner `T`.
+ pub fn into_inner(self) -> T {
+ let Unalign(val) = self;
+ val
+ }
+
+ /// Gets an unaligned raw pointer to the inner `T`.
+ ///
+ /// # Safety
+ ///
+ /// The returned raw pointer is not necessarily aligned to
+ /// `align_of::()`. Most functions which operate on raw pointers require
+ /// those pointers to be aligned, so calling those functions with the result
+ /// of `get_ptr` will be undefined behavior if alignment is not guaranteed
+ /// using some out-of-band mechanism. In general, the only functions which
+ /// are safe to call with this pointer are those which are explicitly
+ /// documented as being sound to use with an unaligned pointer, such as
+ /// [`read_unaligned`].
+ ///
+ /// [`read_unaligned`]: core::ptr::read_unaligned
+ pub fn get_ptr(&self) -> *const T {
+ ptr::addr_of!(self.0)
+ }
+
+ /// Gets an unaligned mutable raw pointer to the inner `T`.
+ ///
+ /// # Safety
+ ///
+ /// The returned raw pointer is not necessarily aligned to
+ /// `align_of::()`. Most functions which operate on raw pointers require
+ /// those pointers to be aligned, so calling those functions with the result
+ /// of `get_ptr` will be undefined behavior if alignment is not guaranteed
+ /// using some out-of-band mechanism. In general, the only functions which
+ /// are safe to call with this pointer are those which are explicitly
+ /// documented as being sound to use with an unaligned pointer, such as
+ /// [`read_unaligned`].
+ ///
+ /// [`read_unaligned`]: core::ptr::read_unaligned
+ pub fn get_mut_ptr(&mut self) -> *mut T {
+ ptr::addr_of_mut!(self.0)
}
}
-unsafe impl Unaligned for i8 {
+
+impl Unalign {
+ /// Gets a copy of the inner `T`.
+ pub fn get(&self) -> T {
+ let Unalign(val) = *self;
+ val
+ }
+}
+
+// SAFETY: Since `T: AsBytes`, we know that it's safe to construct a `&[u8]`
+// from an aligned `&T`. Since `&[u8]` itself has no alignment requirements, it
+// must also be safe to construct a `&[u8]` from a `&T` at any address. Since
+// `Unalign` is `#[repr(C, packed)]`, everything about its layout except for
+// its alignment is the same as `T`'s layout.
+unsafe impl AsBytes for Unalign {
fn only_derive_is_allowed_to_implement_this_trait()
where
Self: Sized,
{
}
}
-impl_for_composite_types!(Unaligned);
+
+// Used in `transmute!` below.
+#[doc(hidden)]
+pub use core::mem::transmute as __real_transmute;
+
+/// Safely transmutes a value of one type to a value of another type of the same
+/// size.
+///
+/// The expression `$e` must have a concrete type, `T`, which implements
+/// `AsBytes`. The `transmute!` expression must also have a concrete type, `U`
+/// (`U` is inferred from the calling context), and `U` must implement
+/// `FromBytes`.
+///
+/// Note that the `T` produced by the expression `$e` will *not* be dropped.
+/// Semantically, its bits will be copied into a new value of type `U`, the
+/// original `T` will be forgotten, and the value of type `U` will be returned.
+#[macro_export]
+macro_rules! transmute {
+ ($e:expr) => {{
+ // NOTE: This must be a macro (rather than a function with trait bounds)
+ // because there's no way, in a generic context, to enforce that two
+ // types have the same size. `core::mem::transmute` uses compiler magic
+ // to enforce this so long as the types are concrete.
+
+ let e = $e;
+ if false {
+ // This branch, though never taken, ensures that the type of `e` is
+ // `AsBytes` and that the type of this macro invocation expression
+ // is `FromBytes`.
+ fn transmute(_t: T) -> U {
+ unreachable!()
+ }
+ transmute(e)
+ } else {
+ // `core::mem::transmute` ensures that the type of `e` and the type
+ // of this macro invocation expression have the same size. We know
+ // this transmute is safe thanks to the `AsBytes` and `FromBytes`
+ // bounds enforced by the `false` branch.
+ //
+ // We use `$crate::__real_transmute` because we know it will always
+ // be available for crates which are using the 2015 edition of Rust.
+ // By contrast, if we were to use `std::mem::transmute`, this macro
+ // would not work for such crates in `no_std` contexts, and if we
+ // were to use `core::mem::transmute`, this macro would not work in
+ // `std` contexts in which `core` was not manually imported. This is
+ // not a problem for 2018 edition crates.
+ unsafe { $crate::__real_transmute(e) }
+ }
+ }}
+}
/// A length- and alignment-checked reference to a byte slice which can safely
/// be reinterpreted as another type.
@@ -370,7 +906,7 @@ impl LayoutVerified
where
B: ByteSlice,
{
- /// Construct a new `LayoutVerified`.
+ /// Constructs a new `LayoutVerified`.
///
/// `new` verifies that `bytes.len() == size_of::()` and that `bytes` is
/// aligned to `align_of::()`, and constructs a new `LayoutVerified`. If
@@ -383,7 +919,7 @@ where
Some(LayoutVerified(bytes, PhantomData))
}
- /// Construct a new `LayoutVerified` from the prefix of a byte slice.
+ /// Constructs a new `LayoutVerified` from the prefix of a byte slice.
///
/// `new_from_prefix` verifies that `bytes.len() >= size_of::()` and that
/// `bytes` is aligned to `align_of::()`. It consumes the first
@@ -399,7 +935,7 @@ where
Some((LayoutVerified(bytes, PhantomData), suffix))
}
- /// Construct a new `LayoutVerified` from the suffix of a byte slice.
+ /// Constructs a new `LayoutVerified` from the suffix of a byte slice.
///
/// `new_from_suffix` verifies that `bytes.len() >= size_of::()` and that
/// the last `size_of::()` bytes of `bytes` are aligned to
@@ -421,23 +957,11 @@ where
}
}
-impl LayoutVerified
-where
- B: ByteSlice,
- T: ?Sized,
-{
- // Get the underlying bytes.
- #[inline]
- pub fn bytes(&self) -> &[u8] {
- &self.0
- }
-}
-
impl LayoutVerified
where
B: ByteSlice,
{
- /// Construct a new `LayoutVerified` of a slice type.
+ /// Constructs a new `LayoutVerified` of a slice type.
///
/// `new_slice` verifies that `bytes.len()` is a multiple of
/// `size_of::()` and that `bytes` is aligned to `align_of::()`, and
@@ -457,6 +981,58 @@ where
}
Some(LayoutVerified(bytes, PhantomData))
}
+
+ /// Constructs a new `LayoutVerified` of a slice type from the prefix of a
+ /// byte slice.
+ ///
+ /// `new_slice_from_prefix` verifies that `bytes.len() >= size_of::() *
+ /// count` and that `bytes` is aligned to `align_of::()`. It consumes the
+ /// first `size_of::() * count` bytes from `bytes` to construct a
+ /// `LayoutVerified`, and returns the remaining bytes to the caller. It also
+ /// ensures that `sizeof::() * count` does not overflow a `usize`. If any
+ /// of the length, alignment, or overflow checks fail, it returns `None`.
+ ///
+ /// # Panics
+ ///
+ /// `new_slice_from_prefix` panics if `T` is a zero-sized type.
+ #[inline]
+ pub fn new_slice_from_prefix(bytes: B, count: usize) -> Option<(LayoutVerified, B)> {
+ let expected_len = match mem::size_of::().checked_mul(count) {
+ Some(len) => len,
+ None => return None,
+ };
+ if bytes.len() < expected_len {
+ return None;
+ }
+ let (prefix, bytes) = bytes.split_at(expected_len);
+ Self::new_slice(prefix).map(move |l| (l, bytes))
+ }
+
+ /// Constructs a new `LayoutVerified` of a slice type from the suffix of a
+ /// byte slice.
+ ///
+ /// `new_slice_from_suffix` verifies that `bytes.len() >= size_of::() *
+ /// count` and that `bytes` is aligned to `align_of::()`. It consumes the
+ /// last `size_of::() * count` bytes from `bytes` to construct a
+ /// `LayoutVerified`, and returns the preceding bytes to the caller. It also
+ /// ensures that `sizeof::() * count` does not overflow a `usize`. If any
+ /// of the length, alignment, or overflow checks fail, it returns `None`.
+ ///
+ /// # Panics
+ ///
+ /// `new_slice_from_suffix` panics if `T` is a zero-sized type.
+ #[inline]
+ pub fn new_slice_from_suffix(bytes: B, count: usize) -> Option<(B, LayoutVerified)> {
+ let expected_len = match mem::size_of::().checked_mul(count) {
+ Some(len) => len,
+ None => return None,
+ };
+ if bytes.len() < expected_len {
+ return None;
+ }
+ let (bytes, suffix) = bytes.split_at(expected_len);
+ Self::new_slice(suffix).map(move |l| (bytes, l))
+ }
}
fn map_zeroed(
@@ -464,9 +1040,7 @@ fn map_zeroed(
) -> Option> {
match opt {
Some(mut lv) => {
- for b in lv.0.iter_mut() {
- *b = 0;
- }
+ lv.0.fill(0);
Some(lv)
}
None => None,
@@ -478,9 +1052,7 @@ fn map_prefix_tuple_zeroed(
) -> Option<(LayoutVerified, B)> {
match opt {
Some((mut lv, rest)) => {
- for b in lv.0.iter_mut() {
- *b = 0;
- }
+ lv.0.fill(0);
Some((lv, rest))
}
None => None,
@@ -497,7 +1069,7 @@ impl LayoutVerified
where
B: ByteSliceMut,
{
- /// Construct a new `LayoutVerified` after zeroing the bytes.
+ /// Constructs a new `LayoutVerified` after zeroing the bytes.
///
/// `new_zeroed` verifies that `bytes.len() == size_of::()` and that
/// `bytes` is aligned to `align_of::()`, and constructs a new
@@ -511,7 +1083,7 @@ where
map_zeroed(Self::new(bytes))
}
- /// Construct a new `LayoutVerified` from the prefix of a byte slice,
+ /// Constructs a new `LayoutVerified` from the prefix of a byte slice,
/// zeroing the prefix.
///
/// `new_from_prefix_zeroed` verifies that `bytes.len() >= size_of::()`
@@ -528,11 +1100,11 @@ where
map_prefix_tuple_zeroed(Self::new_from_prefix(bytes))
}
- /// Construct a new `LayoutVerified` from the suffix of a byte slice,
+ /// Constructs a new `LayoutVerified` from the suffix of a byte slice,
/// zeroing the suffix.
///
- /// `new_from_suffix_zeroed` verifies that `bytes.len() >= size_of::()` and that
- /// the last `size_of::()` bytes of `bytes` are aligned to
+ /// `new_from_suffix_zeroed` verifies that `bytes.len() >= size_of::()`
+ /// and that the last `size_of::()` bytes of `bytes` are aligned to
/// `align_of::()`. It consumes the last `size_of::()` bytes from
/// `bytes` to construct a `LayoutVerified`, and returns the preceding bytes
/// to the caller. If either the length or alignment checks fail, it returns
@@ -551,7 +1123,7 @@ impl LayoutVerified
where
B: ByteSliceMut,
{
- /// Construct a new `LayoutVerified` of a slice type after zeroing the
+ /// Constructs a new `LayoutVerified` of a slice type after zeroing the
/// bytes.
///
/// `new_slice_zeroed` verifies that `bytes.len()` is a multiple of
@@ -570,6 +1142,56 @@ where
pub fn new_slice_zeroed(bytes: B) -> Option> {
map_zeroed(Self::new_slice(bytes))
}
+
+ /// Constructs a new `LayoutVerified` of a slice type from the prefix of a
+ /// byte slice, after zeroing the bytes.
+ ///
+ /// `new_slice_from_prefix` verifies that `bytes.len() >= size_of::() *
+ /// count` and that `bytes` is aligned to `align_of::()`. It consumes the
+ /// first `size_of::() * count` bytes from `bytes` to construct a
+ /// `LayoutVerified`, and returns the remaining bytes to the caller. It also
+ /// ensures that `sizeof::() * count` does not overflow a `usize`. If any
+ /// of the length, alignment, or overflow checks fail, it returns `None`.
+ ///
+ /// If the checks succeed, then the suffix which is consumed will be
+ /// initialized to zero. This can be useful when re-using buffers to ensure
+ /// that sensitive data previously stored in the buffer is not leaked.
+ ///
+ /// # Panics
+ ///
+ /// `new_slice_from_prefix_zeroed` panics if `T` is a zero-sized type.
+ #[inline]
+ pub fn new_slice_from_prefix_zeroed(
+ bytes: B,
+ count: usize,
+ ) -> Option<(LayoutVerified, B)> {
+ map_prefix_tuple_zeroed(Self::new_slice_from_prefix(bytes, count))
+ }
+
+ /// Constructs a new `LayoutVerified` of a slice type from the prefix of a
+ /// byte slice, after zeroing the bytes.
+ ///
+ /// `new_slice_from_suffix` verifies that `bytes.len() >= size_of::() *
+ /// count` and that `bytes` is aligned to `align_of::()`. It consumes the
+ /// last `size_of::() * count` bytes from `bytes` to construct a
+ /// `LayoutVerified`, and returns the preceding bytes to the caller. It also
+ /// ensures that `sizeof::() * count` does not overflow a `usize`. If any
+ /// of the length, alignment, or overflow checks fail, it returns `None`.
+ ///
+ /// If the checks succeed, then the consumed suffix will be initialized to
+ /// zero. This can be useful when re-using buffers to ensure that sensitive
+ /// data previously stored in the buffer is not leaked.
+ ///
+ /// # Panics
+ ///
+ /// `new_slice_from_suffix_zeroed` panics if `T` is a zero-sized type.
+ #[inline]
+ pub fn new_slice_from_suffix_zeroed(
+ bytes: B,
+ count: usize,
+ ) -> Option<(B, LayoutVerified)> {
+ map_suffix_tuple_zeroed(Self::new_slice_from_suffix(bytes, count))
+ }
}
impl LayoutVerified
@@ -577,7 +1199,7 @@ where
B: ByteSlice,
T: Unaligned,
{
- /// Construct a new `LayoutVerified` for a type with no alignment
+ /// Constructs a new `LayoutVerified` for a type with no alignment
/// requirement.
///
/// `new_unaligned` verifies that `bytes.len() == size_of::()` and
@@ -591,7 +1213,7 @@ where
Some(LayoutVerified(bytes, PhantomData))
}
- /// Construct a new `LayoutVerified` from the prefix of a byte slice for a
+ /// Constructs a new `LayoutVerified` from the prefix of a byte slice for a
/// type with no alignment requirement.
///
/// `new_unaligned_from_prefix` verifies that `bytes.len() >=
@@ -607,7 +1229,7 @@ where
Some((LayoutVerified(bytes, PhantomData), suffix))
}
- /// Construct a new `LayoutVerified` from the suffix of a byte slice for a
+ /// Constructs a new `LayoutVerified` from the suffix of a byte slice for a
/// type with no alignment requirement.
///
/// `new_unaligned_from_suffix` verifies that `bytes.len() >=
@@ -630,7 +1252,7 @@ where
B: ByteSlice,
T: Unaligned,
{
- /// Construct a new `LayoutVerified` of a slice type with no alignment
+ /// Constructs a new `LayoutVerified` of a slice type with no alignment
/// requirement.
///
/// `new_slice_unaligned` verifies that `bytes.len()` is a multiple of
@@ -648,6 +1270,64 @@ where
}
Some(LayoutVerified(bytes, PhantomData))
}
+
+ /// Constructs a new `LayoutVerified` of a slice type with no alignment
+ /// requirement from the prefix of a byte slice.
+ ///
+ /// `new_slice_from_prefix` verifies that `bytes.len() >= size_of::() *
+ /// count`. It consumes the first `size_of::() * count` bytes from
+ /// `bytes` to construct a `LayoutVerified`, and returns the remaining bytes
+ /// to the caller. It also ensures that `sizeof::() * count` does not
+ /// overflow a `usize`. If either the length, or overflow checks fail, it
+ /// returns `None`.
+ ///
+ /// # Panics
+ ///
+ /// `new_slice_unaligned_from_prefix` panics if `T` is a zero-sized type.
+ #[inline]
+ pub fn new_slice_unaligned_from_prefix(
+ bytes: B,
+ count: usize,
+ ) -> Option<(LayoutVerified, B)> {
+ let expected_len = match mem::size_of::().checked_mul(count) {
+ Some(len) => len,
+ None => return None,
+ };
+ if bytes.len() < expected_len {
+ return None;
+ }
+ let (prefix, bytes) = bytes.split_at(expected_len);
+ Self::new_slice_unaligned(prefix).map(move |l| (l, bytes))
+ }
+
+ /// Constructs a new `LayoutVerified` of a slice type with no alignment
+ /// requirement from the suffix of a byte slice.
+ ///
+ /// `new_slice_from_suffix` verifies that `bytes.len() >= size_of::() *
+ /// count`. It consumes the last `size_of::() * count` bytes from `bytes`
+ /// to construct a `LayoutVerified`, and returns the remaining bytes to the
+ /// caller. It also ensures that `sizeof::() * count` does not overflow a
+ /// `usize`. If either the length, or overflow checks fail, it returns
+ /// `None`.
+ ///
+ /// # Panics
+ ///
+ /// `new_slice_unaligned_from_suffix` panics if `T` is a zero-sized type.
+ #[inline]
+ pub fn new_slice_unaligned_from_suffix(
+ bytes: B,
+ count: usize,
+ ) -> Option<(B, LayoutVerified)> {
+ let expected_len = match mem::size_of::().checked_mul(count) {
+ Some(len) => len,
+ None => return None,
+ };
+ if bytes.len() < expected_len {
+ return None;
+ }
+ let (bytes, suffix) = bytes.split_at(expected_len);
+ Self::new_slice_unaligned(suffix).map(move |l| (bytes, l))
+ }
}
impl LayoutVerified
@@ -655,7 +1335,7 @@ where
B: ByteSliceMut,
T: Unaligned,
{
- /// Construct a new `LayoutVerified` for a type with no alignment
+ /// Constructs a new `LayoutVerified` for a type with no alignment
/// requirement, zeroing the bytes.
///
/// `new_unaligned_zeroed` verifies that `bytes.len() == size_of::()` and
@@ -670,7 +1350,7 @@ where
map_zeroed(Self::new_unaligned(bytes))
}
- /// Construct a new `LayoutVerified` from the prefix of a byte slice for a
+ /// Constructs a new `LayoutVerified` from the prefix of a byte slice for a
/// type with no alignment requirement, zeroing the prefix.
///
/// `new_unaligned_from_prefix_zeroed` verifies that `bytes.len() >=
@@ -686,7 +1366,7 @@ where
map_prefix_tuple_zeroed(Self::new_unaligned_from_prefix(bytes))
}
- /// Construct a new `LayoutVerified` from the suffix of a byte slice for a
+ /// Constructs a new `LayoutVerified` from the suffix of a byte slice for a
/// type with no alignment requirement, zeroing the suffix.
///
/// `new_unaligned_from_suffix_zeroed` verifies that `bytes.len() >=
@@ -708,7 +1388,7 @@ where
B: ByteSliceMut,
T: Unaligned,
{
- /// Construct a new `LayoutVerified` for a slice type with no alignment
+ /// Constructs a new `LayoutVerified` for a slice type with no alignment
/// requirement, zeroing the bytes.
///
/// `new_slice_unaligned_zeroed` verifies that `bytes.len()` is a multiple
@@ -726,6 +1406,58 @@ where
pub fn new_slice_unaligned_zeroed(bytes: B) -> Option> {
map_zeroed(Self::new_slice_unaligned(bytes))
}
+
+ /// Constructs a new `LayoutVerified` of a slice type with no alignment
+ /// requirement from the prefix of a byte slice, after zeroing the bytes.
+ ///
+ /// `new_slice_from_prefix` verifies that `bytes.len() >= size_of::() *
+ /// count`. It consumes the first `size_of::() * count` bytes from
+ /// `bytes` to construct a `LayoutVerified`, and returns the remaining bytes
+ /// to the caller. It also ensures that `sizeof::() * count` does not
+ /// overflow a `usize`. If either the length, or overflow checks fail, it
+ /// returns `None`.
+ ///
+ /// If the checks succeed, then the prefix will be initialized to zero. This
+ /// can be useful when re-using buffers to ensure that sensitive data
+ /// previously stored in the buffer is not leaked.
+ ///
+ /// # Panics
+ ///
+ /// `new_slice_unaligned_from_prefix_zeroed` panics if `T` is a zero-sized
+ /// type.
+ #[inline]
+ pub fn new_slice_unaligned_from_prefix_zeroed(
+ bytes: B,
+ count: usize,
+ ) -> Option<(LayoutVerified, B)> {
+ map_prefix_tuple_zeroed(Self::new_slice_unaligned_from_prefix(bytes, count))
+ }
+
+ /// Constructs a new `LayoutVerified` of a slice type with no alignment
+ /// requirement from the suffix of a byte slice, after zeroing the bytes.
+ ///
+ /// `new_slice_from_suffix` verifies that `bytes.len() >= size_of::() *
+ /// count`. It consumes the last `size_of::() * count` bytes from `bytes`
+ /// to construct a `LayoutVerified`, and returns the remaining bytes to the
+ /// caller. It also ensures that `sizeof::() * count` does not overflow a
+ /// `usize`. If either the length, or overflow checks fail, it returns
+ /// `None`.
+ ///
+ /// If the checks succeed, then the suffix will be initialized to zero. This
+ /// can be useful when re-using buffers to ensure that sensitive data
+ /// previously stored in the buffer is not leaked.
+ ///
+ /// # Panics
+ ///
+ /// `new_slice_unaligned_from_suffix_zeroed` panics if `T` is a zero-sized
+ /// type.
+ #[inline]
+ pub fn new_slice_unaligned_from_suffix_zeroed(
+ bytes: B,
+ count: usize,
+ ) -> Option<(B, LayoutVerified)> {
+ map_suffix_tuple_zeroed(Self::new_slice_unaligned_from_suffix(bytes, count))
+ }
}
impl<'a, B, T> LayoutVerified
@@ -733,17 +1465,17 @@ where
B: 'a + ByteSlice,
T: FromBytes,
{
- /// Convert this `LayoutVerified` into a reference.
+ /// Converts this `LayoutVerified` into a reference.
///
/// `into_ref` consumes the `LayoutVerified`, and returns a reference to
/// `T`.
pub fn into_ref(self) -> &'a T {
- // NOTE: This is safe because `B` is guaranteed to live for the lifetime
- // `'a`, meaning that a) the returned reference cannot outlive the `B`
- // from which `self` was constructed and, b) no mutable methods on that
- // `B` can be called during the lifetime of the returned reference. See
- // the documentation on `deref_helper` for what invariants we are
- // required to uphold.
+ // SAFETY: This is sound because `B` is guaranteed to live for the
+ // lifetime `'a`, meaning that a) the returned reference cannot outlive
+ // the `B` from which `self` was constructed and, b) no mutable methods
+ // on that `B` can be called during the lifetime of the returned
+ // reference. See the documentation on `deref_helper` for what
+ // invariants we are required to uphold.
unsafe { self.deref_helper() }
}
}
@@ -753,17 +1485,17 @@ where
B: 'a + ByteSliceMut,
T: FromBytes + AsBytes,
{
- /// Convert this `LayoutVerified` into a mutable reference.
+ /// Converts this `LayoutVerified` into a mutable reference.
///
/// `into_mut` consumes the `LayoutVerified`, and returns a mutable
/// reference to `T`.
pub fn into_mut(mut self) -> &'a mut T {
- // NOTE: This is safe because `B` is guaranteed to live for the lifetime
- // `'a`, meaning that a) the returned reference cannot outlive the `B`
- // from which `self` was constructed and, b) no other methods - mutable
- // or immutable - on that `B` can be called during the lifetime of the
- // returned reference. See the documentation on `deref_mut_helper` for
- // what invariants we are required to uphold.
+ // SAFETY: This is sound because `B` is guaranteed to live for the
+ // lifetime `'a`, meaning that a) the returned reference cannot outlive
+ // the `B` from which `self` was constructed and, b) no other methods -
+ // mutable or immutable - on that `B` can be called during the lifetime
+ // of the returned reference. See the documentation on
+ // `deref_mut_helper` for what invariants we are required to uphold.
unsafe { self.deref_mut_helper() }
}
}
@@ -773,17 +1505,17 @@ where
B: 'a + ByteSlice,
T: FromBytes,
{
- /// Convert this `LayoutVerified` into a slice reference.
+ /// Converts this `LayoutVerified` into a slice reference.
///
/// `into_slice` consumes the `LayoutVerified`, and returns a reference to
/// `[T]`.
pub fn into_slice(self) -> &'a [T] {
- // NOTE: This is safe because `B` is guaranteed to live for the lifetime
- // `'a`, meaning that a) the returned reference cannot outlive the `B`
- // from which `self` was constructed and, b) no mutable methods on that
- // `B` can be called during the lifetime of the returned reference. See
- // the documentation on `deref_slice_helper` for what invariants we are
- // required to uphold.
+ // SAFETY: This is sound because `B` is guaranteed to live for the
+ // lifetime `'a`, meaning that a) the returned reference cannot outlive
+ // the `B` from which `self` was constructed and, b) no mutable methods
+ // on that `B` can be called during the lifetime of the returned
+ // reference. See the documentation on `deref_slice_helper` for what
+ // invariants we are required to uphold.
unsafe { self.deref_slice_helper() }
}
}
@@ -793,17 +1525,18 @@ where
B: 'a + ByteSliceMut,
T: FromBytes + AsBytes,
{
- /// Convert this `LayoutVerified` into a mutable slice reference.
+ /// Converts this `LayoutVerified` into a mutable slice reference.
///
- /// `into_mut_slice` consumes the `LayoutVerified`, and returns a mutable reference to
- /// `[T]`.
+ /// `into_mut_slice` consumes the `LayoutVerified`, and returns a mutable
+ /// reference to `[T]`.
pub fn into_mut_slice(mut self) -> &'a mut [T] {
- // NOTE: This is safe because `B` is guaranteed to live for the lifetime
- // `'a`, meaning that a) the returned reference cannot outlive the `B`
- // from which `self` was constructed and, b) no other methods - mutable
- // or immutable - on that `B` can be called during the lifetime of the
- // returned reference. See the documentation on `deref_mut_slice_helper`
- // for what invariants we are required to uphold.
+ // SAFETY: This is sound because `B` is guaranteed to live for the
+ // lifetime `'a`, meaning that a) the returned reference cannot outlive
+ // the `B` from which `self` was constructed and, b) no other methods -
+ // mutable or immutable - on that `B` can be called during the lifetime
+ // of the returned reference. See the documentation on
+ // `deref_mut_slice_helper` for what invariants we are required to
+ // uphold.
unsafe { self.deref_mut_slice_helper() }
}
}
@@ -813,7 +1546,7 @@ where
B: ByteSlice,
T: FromBytes,
{
- /// Create an immutable reference to `T` with a specific lifetime.
+ /// Creates an immutable reference to `T` with a specific lifetime.
///
/// # Safety
///
@@ -834,7 +1567,7 @@ where
B: ByteSliceMut,
T: FromBytes + AsBytes,
{
- /// Create a mutable reference to `T` with a specific lifetime.
+ /// Creates a mutable reference to `T` with a specific lifetime.
///
/// # Safety
///
@@ -855,7 +1588,7 @@ where
B: ByteSlice,
T: FromBytes,
{
- /// Create an immutable reference to `[T]` with a specific lifetime.
+ /// Creates an immutable reference to `[T]` with a specific lifetime.
///
/// # Safety
///
@@ -875,7 +1608,7 @@ where
B: ByteSliceMut,
T: FromBytes + AsBytes,
{
- /// Create a mutable reference to `[T]` with a specific lifetime.
+ /// Creates a mutable reference to `[T]` with a specific lifetime.
///
/// # Safety
///
@@ -891,23 +1624,69 @@ where
}
}
+#[inline]
fn aligned_to(bytes: &[u8], align: usize) -> bool {
(bytes as *const _ as *const () as usize) % align == 0
}
impl LayoutVerified
where
- B: ByteSliceMut,
+ B: ByteSlice,
T: ?Sized,
{
- // Get the underlying bytes mutably.
+ /// Gets the underlying bytes.
#[inline]
- pub fn bytes_mut(&mut self) -> &mut [u8] {
- &mut self.0
+ pub fn bytes(&self) -> &[u8] {
+ &self.0
}
}
-impl Deref for LayoutVerified
+impl LayoutVerified
+where
+ B: ByteSliceMut,
+ T: ?Sized,
+{
+ /// Gets the underlying bytes mutably.
+ #[inline]
+ pub fn bytes_mut(&mut self) -> &mut [u8] {
+ &mut self.0
+ }
+}
+
+impl LayoutVerified
+where
+ B: ByteSlice,
+ T: FromBytes,
+{
+ /// Reads a copy of `T`.
+ #[inline]
+ pub fn read(&self) -> T {
+ // SAFETY: Because of the invariants on `LayoutVerified`, we know that
+ // `self.0` is at least `size_of::()` bytes long, and that it is at
+ // least as aligned as `align_of::()`. Because `T: FromBytes`, it is
+ // sound to interpret these bytes as a `T`.
+ unsafe { ptr::read(self.0.as_ptr() as *const T) }
+ }
+}
+
+impl LayoutVerified
+where
+ B: ByteSliceMut,
+ T: AsBytes,
+{
+ /// Writes the bytes of `t` and then forgets `t`.
+ #[inline]
+ pub fn write(&mut self, t: T) {
+ // SAFETY: Because of the invariants on `LayoutVerified`, we know that
+ // `self.0` is at least `size_of::()` bytes long, and that it is at
+ // least as aligned as `align_of::()`. Writing `t` to the buffer will
+ // allow all of the bytes of `t` to be accessed as a `[u8]`, but because
+ // `T: AsBytes`, we know this is sound.
+ unsafe { ptr::write(self.0.as_mut_ptr() as *mut T, t) }
+ }
+}
+
+impl Deref for LayoutVerified
where
B: ByteSlice,
T: FromBytes,
@@ -915,10 +1694,10 @@ where
type Target = T;
#[inline]
fn deref(&self) -> &T {
- // NOTE: This is safe because the lifetime of `self` is the same as the
- // lifetime of the return value, meaning that a) the returned reference
- // cannot outlive `self` and, b) no mutable methods on `self` can be
- // called during the lifetime of the returned reference. See the
+ // SAFETY: This is sound because the lifetime of `self` is the same as
+ // the lifetime of the return value, meaning that a) the returned
+ // reference cannot outlive `self` and, b) no mutable methods on `self`
+ // can be called during the lifetime of the returned reference. See the
// documentation on `deref_helper` for what invariants we are required
// to uphold.
unsafe { self.deref_helper() }
@@ -932,10 +1711,10 @@ where
{
#[inline]
fn deref_mut(&mut self) -> &mut T {
- // NOTE: This is safe because the lifetime of `self` is the same as the
- // lifetime of the return value, meaning that a) the returned reference
- // cannot outlive `self` and, b) no other methods on `self` can be
- // called during the lifetime of the returned reference. See the
+ // SAFETY: This is sound because the lifetime of `self` is the same as
+ // the lifetime of the return value, meaning that a) the returned
+ // reference cannot outlive `self` and, b) no other methods on `self`
+ // can be called during the lifetime of the returned reference. See the
// documentation on `deref_mut_helper` for what invariants we are
// required to uphold.
unsafe { self.deref_mut_helper() }
@@ -950,10 +1729,10 @@ where
type Target = [T];
#[inline]
fn deref(&self) -> &[T] {
- // NOTE: This is safe because the lifetime of `self` is the same as the
- // lifetime of the return value, meaning that a) the returned reference
- // cannot outlive `self` and, b) no mutable methods on `self` can be
- // called during the lifetime of the returned reference. See the
+ // SAFETY: This is sound because the lifetime of `self` is the same as
+ // the lifetime of the return value, meaning that a) the returned
+ // reference cannot outlive `self` and, b) no mutable methods on `self`
+ // can be called during the lifetime of the returned reference. See the
// documentation on `deref_slice_helper` for what invariants we are
// required to uphold.
unsafe { self.deref_slice_helper() }
@@ -967,10 +1746,10 @@ where
{
#[inline]
fn deref_mut(&mut self) -> &mut [T] {
- // NOTE: This is safe because the lifetime of `self` is the same as the
- // lifetime of the return value, meaning that a) the returned reference
- // cannot outlive `self` and, b) no other methods on `self` can be
- // called during the lifetime of the returned reference. See the
+ // SAFETY: This is sound because the lifetime of `self` is the same as
+ // the lifetime of the return value, meaning that a) the returned
+ // reference cannot outlive `self` and, b) no other methods on `self`
+ // can be called during the lifetime of the returned reference. See the
// documentation on `deref_mut_slice_helper` for what invariants we are
// required to uphold.
unsafe { self.deref_mut_slice_helper() }
@@ -989,6 +1768,19 @@ where
}
}
+impl Display for LayoutVerified
+where
+ B: ByteSlice,
+ T: FromBytes,
+ [T]: Display,
+{
+ #[inline]
+ fn fmt(&self, fmt: &mut Formatter<'_>) -> fmt::Result {
+ let inner: &[T] = self;
+ inner.fmt(fmt)
+ }
+}
+
impl Debug for LayoutVerified
where
B: ByteSlice,
@@ -1001,28 +1793,103 @@ where
}
}
-impl Display for LayoutVerified
+impl Debug for LayoutVerified
where
B: ByteSlice,
- T: FromBytes,
- [T]: Display,
+ T: FromBytes + Debug,
{
#[inline]
fn fmt(&self, fmt: &mut Formatter<'_>) -> fmt::Result {
let inner: &[T] = self;
- inner.fmt(fmt)
+ fmt.debug_tuple("LayoutVerified").field(&inner).finish()
}
}
-impl Debug for LayoutVerified
+impl Eq for LayoutVerified
where
B: ByteSlice,
- T: FromBytes + Debug,
+ T: FromBytes + Eq,
+{
+}
+
+impl Eq for LayoutVerified
+where
+ B: ByteSlice,
+ T: FromBytes + Eq,
+{
+}
+
+impl PartialEq for LayoutVerified
+where
+ B: ByteSlice,
+ T: FromBytes + PartialEq,
{
#[inline]
- fn fmt(&self, fmt: &mut Formatter<'_>) -> fmt::Result {
+ fn eq(&self, other: &Self) -> bool {
+ self.deref().eq(other.deref())
+ }
+}
+
+impl PartialEq for LayoutVerified
+where
+ B: ByteSlice,
+ T: FromBytes + PartialEq,
+{
+ #[inline]
+ fn eq(&self, other: &Self) -> bool {
+ self.deref().eq(other.deref())
+ }
+}
+
+impl Ord for LayoutVerified
+where
+ B: ByteSlice,
+ T: FromBytes + Ord,
+{
+ #[inline]
+ fn cmp(&self, other: &Self) -> Ordering {
+ let inner: &T = self;
+ let other_inner: &T = other;
+ inner.cmp(other_inner)
+ }
+}
+
+impl Ord for LayoutVerified
+where
+ B: ByteSlice,
+ T: FromBytes + Ord,
+{
+ #[inline]
+ fn cmp(&self, other: &Self) -> Ordering {
let inner: &[T] = self;
- fmt.debug_tuple("LayoutVerified").field(&inner).finish()
+ let other_inner: &[T] = other;
+ inner.cmp(other_inner)
+ }
+}
+
+impl PartialOrd for LayoutVerified