Struct Tailed

#[repr(C)]
pub struct Tailed<Head, Tail: ?Sized> {
    pub head: Head,
    pub tail: Tail,
}

A custom DST type.

One of the main usages is Tailed<H, [T]>, where the type has a flexible array member.

Fields

head: Head

Leading, sized data part of the type.

tail: Tail

Trailing, unsized data part of the type.

Implementations

impl<H, T> Tailed<H, [T]>

pub fn from_raw_parts(data: *const H, count: usize) -> *const Self

Constructs a fat pointer from a pointer to the header and the count of elements in the trailing slice.

Safety

It’s important to specify the count of the trailing elements rather than the size of the allocated data.

let slice = &[1, 2, 3, 4, 5];
let (ptr, len) = (slice as *const i32, slice.len());
let pointed = Tailed::<_, [i32]>::from_raw_parts(ptr, 4);
let pointed = unsafe { &*pointed };

let other = Tailed { head: 1i32, tail: [2, 3, 4, 5] };
assert_eq!(pointed, &other as &Tailed::<_, [i32]>);
assert_eq!(std::mem::size_of_val(pointed), std::mem::size_of_val(&other));

pub fn from_raw_parts_mut(data: *mut H, count: usize) -> *mut Self

Constructs a fat pointer from a pointer to the header and the count of elements in the trailing slice.

Safety

The pointer to header must be correctly aligned.

use std::boxed::Box;

let slice = vec![1, 2, 3, 4, 5].into_boxed_slice();
let (len, ptr) = (slice.len(), Box::into_raw(slice));
let pointed = Tailed::<_, [i32]>::from_raw_parts_mut(ptr as *mut i32, 4);
let pointed = unsafe { &mut *pointed };

let other = Tailed { head: 1i32, tail: [2, 3, 4, 5] };
assert_eq!(pointed, &other as &Tailed::<_, [i32]>);
assert_eq!(std::mem::size_of_val(pointed), std::mem::size_of_val(&other));

impl<H> Tailed<MaybeUninit<H>, [u8]>

pub fn from_bytes(data: &[u8]) -> &Self

Creates a Tailed view into a slice of bytes.

#![feature(maybe_uninit_extra)]
use core::mem::MaybeUninit;

#[derive(PartialEq, Debug)]
#[repr(C)]
struct Header { a: u16, b: u8 };

let bytes: Box<[u8]> = vec![0x01, 0x01, 0x02, 0xFF, 0x03, 0x04].into();

let tailed = Tailed::<MaybeUninit<Header>, _>::from_bytes(&bytes);
assert_eq!(unsafe { tailed.head.read() }, Header {a: 0x0101, b: 0x02 });
assert_eq!(&tailed.tail, &[0x03, 0x04]);

Safety

The passed reference MUST be aligned in a compatible fashion, as if it was an reference to dynamically-sized Self.

The data buffer also MUST be at least mem::size_of::<H>() bytes long and be properly aligned (e.g. to account for trailing padding).

Moreover, since we can’t guarantee that the raw bytes correspond to a correctly initialized value of type H, it is the caller’s responsibility to assert that.

Panics

When any of the above safety preconditions are violated.

pub fn from_bytes_with_length(data: &[u8], len: usize) -> &Self

Creates a Tailed view into a slice of bytes with specifically len trailing bytes (any bytes after that are simply treated as padding).

Valid trailing byte count range is [0; mem::size_of_val(data) - mem::size_of::<H>()]. Specify usize::MAX to include as many bytes in the tail byte slice as possible.

#![feature(maybe_uninit_extra)]
use core::mem::MaybeUninit;

#[derive(PartialEq, Debug)]
#[repr(C)]
struct Header { a: u16, b: u8 };

let bytes: Box<[u8]> = vec![0x01, 0x01, 0x02, 0xFF, 0x03, 0xFF].into();

let tailed = Tailed::<MaybeUninit<Header>, _>::from_bytes_with_length(&bytes, 1);
assert_eq!(unsafe { tailed.head.read() }, Header {a: 0x0101, b: 0x02 });
assert_eq!(&tailed.tail, &[0x03]);
// Header is 4 bytes and there are 2 trailing bytes, despite tail having 1.
assert_eq!(core::mem::size_of_val(tailed), 6);
let tailed = Tailed::<MaybeUninit<Header>, _>::from_bytes_with_length(&bytes, 0);
assert_eq!(&tailed.tail, &[]);
let tailed = Tailed::<MaybeUninit<Header>, _>::from_bytes_with_length(&bytes, core::usize::MAX);
assert_eq!(&tailed.tail, &[0x03, 0xFF]);

Safety

In addition to upholding safety preconditions outlined in from_bytes, the passed len must be not bigger than the trailing byte count after header H type (including its padding).

Panics

When any of the above preconditions are violated.

pub unsafe fn from_bytes_unchecked_with_length(data: &[u8], len: usize) -> &Self

Unchecked version of from_bytes that can also specify the tail byte length manually.

pub unsafe fn assume_init(&self) -> &Tailed<H, [u8]>

Assumes that the header part of the DST is correctly initialized, yielding a read-only typed view into underlying storage.

This does not invoke any drop glue for the inner type and only provides read access to the underlying value.

use core::mem::MaybeUninit;

#[derive(PartialEq, Debug)]
#[repr(C)]
struct Header { a: u16, b: u8 };

let bytes: Box<[u8]> = vec![0x01, 0x01, 0x02, 0xFF, 0x03, 0x04].into();

let tailed = Tailed::<MaybeUninit<Header>, _>::from_bytes(&bytes);
let init: &Tailed<Header, _> = unsafe { Tailed::from_bytes(&bytes).assume_init() };
assert_eq!(&init.head, &Header { a: 0x0101, b: 0x02});
assert_eq!(&init.tail, &[0x03, 0x04]);

Trait Implementations

impl<Head: Debug, Tail: Debug + ?Sized> Debug for Tailed<Head, Tail>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<Head: PartialEq, Tail: PartialEq + ?Sized> PartialEq for Tailed<Head, Tail>

fn eq(&self, other: &Tailed<Head, Tail>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<Head, Tail: ?Sized> StructuralPartialEq for Tailed<Head, Tail>