tango/

buf.rs

//! Typed buffers, octets being a `Buf<u8, 1>`, which is what a backend receives a message
//! into.
//!
//! A [`Buf`] is a typed, N-dimensional array of values, whose dimensions are fixed once it
//! is built. It has no lifetime: it holds a reference to a counted storage that every clone
//! and every slice shares, so that the buffer a message is received into can be handed out
//! in pieces, cast to the types of the values it holds, all the way up to the user, without
//! copying any of it.
//!
//! A [`BufMut`] is a buffer that is statically the only reference to its storage, which is
//! what allows writing to it, and growing it along one dimension, like a `Vec`, without ever
//! checking whether its storage is shared. A [`Buf`] turns into one with copy-on-write, see
//! [`Buf::make_mut`] and [`Buf::into_mut`], copying only its own values when its storage is
//! shared, or without, see [`Buf::get_mut`] and [`Buf::try_into_mut`], and a [`BufMut`]
//! turns back into a [`Buf`] to be shared, see [`BufMut::freeze`].
//!
//! # Alignment
//!
//! Storages are currently aligned on 8 octets, so that a buffer starting where its storage
//! starts, such as one that was just allocated, is aligned for every [`PackedElement`] and
//! casts to any of them without copying. This is an implementation detail, which is not
//! guaranteed to stay the same across versions: what depends on the alignment of some
//! values checks it, like [`Buf::cast`], which copies the values when they are not aligned
//! for their new type.

use std::borrow::Cow;
use std::sync::atomic::{self, AtomicPtr, AtomicUsize, Ordering};
use std::mem::{self, ManuallyDrop, MaybeUninit};
use std::fmt::{self, Debug, LowerHex, UpperHex};
use std::ops::{Bound, Range, RangeBounds};
use std::alloc::{self, Layout};
use std::ptr::{self, NonNull};
use std::num::NonZero;
use std::marker::PhantomData;
use std::{slice, str};

use crate::error::{Error, ErrorKind};
use crate::value::DevEnum;
use crate::dev::DevState;


// =========================== //
//           Storage           //
// =========================== //

/// The header of a storage, directly followed by its data, in units of 8 octets so that
/// the data is aligned for every [`PackedElement`].
#[repr(C)]
struct HeapHeader {
    /// Number of handles on this storage, the storage being freed when it drops to zero.
    count: AtomicUsize,
    /// Capacity of the data, in units of 8 octets.
    cap: usize,
    /// The side allocations freed together with this storage, see [`SideHeader`].
    side: AtomicPtr<SideHeader>,
}

/// The header of a side allocation, directly followed by its payload: something a [`Buf`]
/// needs beside its values, such as the spans of its strings, which lives exactly as long
/// as the storage it is attached to, and therefore needs no count of its own.
#[repr(C)]
struct SideHeader {
    /// The next side allocation of the same storage.
    next: *mut SideHeader,
    /// Size of the payload, in octets.
    size: usize,
}

/// The alignment of the data of a storage and of the payload of a side allocation, which
/// is not part of the API, see the [module](self) documentation.
const ALIGN: usize = 8;

/// What an allocation fails with: no layout at all for a capacity that large, or the layout
/// the allocator failed on.
type AllocResult<T> = Result<T, Option<Layout>>;

/// Unwrap an allocation the way the standard collections do: a panic when the capacity
/// overflows, the allocation error handler when the allocator fails.
fn infallible<T>(res: AllocResult<T>) -> T {
    match res {
        Ok(value) => value,
        Err(Some(layout)) => alloc::handle_alloc_error(layout),
        Err(None) => panic!("capacity overflow"),
    }
}

/// A raw handle on a storage, which does not count as a reference by itself: this is what
/// the [`HeapRef`] holding it acquires and releases.
#[derive(Clone, Copy)]
#[repr(transparent)]
struct Heap(NonNull<HeapHeader>);

/// A header aligned like the storages that are allocated, so that its (empty) data is too.
#[repr(C, align(8))]
struct EmptyHeapHeader(HeapHeader);

/// The storage of whatever holds no values at all, which is never allocated nor freed: it
/// is not counted, see [`Heap::is_immortal`], and is never written since it has no
/// octets, and nothing is ever attached to it.
static EMPTY_HEAP_HEADER: EmptyHeapHeader = EmptyHeapHeader(HeapHeader {
    count: AtomicUsize::new(usize::MAX),
    cap: 0,
    side: AtomicPtr::new(ptr::null_mut()),
});

impl Heap {

    /// A handle on the storage of whatever holds no values at all.
    // SAFETY: A static is never null.
    const EMPTY: Self = Self(unsafe { NonNull::new_unchecked((&raw const EMPTY_HEAP_HEADER.0).cast_mut()) });

    /// Whether this is the storage of whatever holds no values at all, which is not counted.
    #[inline]
    fn is_immortal(self) -> bool {
        self.0 == Self::EMPTY.0
    }

    /// The layout of a storage of that capacity, in units of 8 octets, absent if it
    /// overflows.
    fn layout(cap: usize) -> Option<Layout> {
        cap.checked_mul(ALIGN)
            .and_then(|size| size.checked_add(mem::size_of::<HeapHeader>()))
            .and_then(|size| Layout::from_size_align(size, ALIGN).ok())
    }

    /// Allocate a storage holding at least that many octets, all zeroes, its only reference
    /// being the returned handle. A storage is always zeroed when allocated, and so is what
    /// it grows by, see [`Self::grow`]: its whole capacity is always initialized, and
    /// zeroes need not be written where it was never written.
    fn alloc(len: usize) -> AllocResult<Self> {
        let cap = len.div_ceil(ALIGN);
        let layout = Self::layout(cap).ok_or(None)?;
        // SAFETY: The layout is never zero-sized, it always holds the header.
        let ptr = unsafe { alloc::alloc_zeroed(layout) };
        let ptr = NonNull::new(ptr.cast::<HeapHeader>()).ok_or(Some(layout))?;
        // SAFETY: The allocation is valid for the header.
        unsafe { ptr.write(HeapHeader { count: AtomicUsize::new(1), cap, side: AtomicPtr::new(ptr::null_mut()) }) };
        Ok(Self(ptr))
    }

    /// The data of this storage.
    #[inline]
    fn data(self) -> *mut u8 {
        // SAFETY: The data directly follows the header, in the same allocation.
        unsafe { self.0.as_ptr().add(1).cast::<u8>() }
    }

    /// The capacity of the data of this storage, in octets.
    #[inline]
    fn capacity(self) -> usize {
        // SAFETY: The handle points to a live storage.
        unsafe { (*self.0.as_ptr()).cap * ALIGN }
    }

    #[inline]
    fn header(&self) -> &HeapHeader {
        // SAFETY: The handle points to a live storage.
        unsafe { self.0.as_ref() }
    }

    /// Whether this is the only reference to the storage, which is what allows writing to
    /// it, the acquire ordering making the writes of the released references visible.
    #[inline]
    fn is_unique(self) -> bool {
        self.header().count.load(Ordering::Acquire) == 1
    }

    /// Add a reference to this storage.
    #[inline]
    fn acquire(self) {
        if self.is_immortal() {
            return;
        }
        let old = self.header().count.fetch_add(1, Ordering::Relaxed);
        // Like `Arc`, never let the count overflow, which would free a live storage.
        if old > isize::MAX as usize {
            std::process::abort();
        }
    }

    /// Release a reference to this storage, freeing it with its side allocations if it
    /// was the last one.
    ///
    /// # Safety
    ///
    /// The caller has to own the reference it releases, and not use the handle anymore.
    #[inline]
    unsafe fn release(self) {
        if self.is_immortal() || self.header().count.fetch_sub(1, Ordering::Release) != 1 {
            return;
        }
        atomic::fence(Ordering::Acquire);
        // SAFETY: This was the last reference, nothing else can reach the storage.
        unsafe { self.free() }
    }

    #[cold]
    unsafe fn free(self) {
        let header = self.0.as_ptr();
        // SAFETY: The storage is ours alone, allocated with that layout.
        unsafe {
            self.free_sides();
            alloc::dealloc(header.cast(), Self::layout((*header).cap).unwrap_unchecked());
        }
    }

    /// The layout of a side allocation of that payload size, absent if it overflows.
    fn side_layout(size: usize) -> Option<Layout> {
        size.checked_add(mem::size_of::<SideHeader>())
            .and_then(|size| Layout::from_size_align(size, ALIGN).ok())
    }

    /// Attach that side allocation to this storage, which frees it with itself.
    ///
    /// The storage may already be shared, hence the lock-free push, but nothing reads the
    /// list of side allocations before the last reference frees it.
    fn push_side(self, side: DetachedSide) {
        debug_assert!(!self.is_immortal(), "nothing is attached to the empty storage");
        let side = ManuallyDrop::new(side).0;
        let head = &self.header().side;
        let mut next = head.load(Ordering::Relaxed);
        loop {
            // SAFETY: The side allocation is ours until it is pushed.
            unsafe { (*side.as_ptr()).next = next };
            match head.compare_exchange_weak(next, side.as_ptr(), Ordering::Release, Ordering::Relaxed) {
                Ok(_) => break,
                Err(current) => next = current,
            }
        }
    }

    /// Free the side allocations of this storage, which nothing uses anymore once it is
    /// the only reference to the storage.
    ///
    /// # Safety
    ///
    /// The caller has to own the only reference to the storage.
    unsafe fn free_sides(self) {
        let mut side = self.header().side.swap(ptr::null_mut(), Ordering::Relaxed);
        while !side.is_null() {
            // SAFETY: The side allocations are ours alone, and were allocated with the
            // layout their header gives back.
            unsafe {
                let next = (*side).next;
                alloc::dealloc(side.cast(), Self::side_layout((*side).size).unwrap_unchecked());
                side = next;
            }
        }
    }

    /// Grow this storage to a capacity of at least that many octets, at least doubling it,
    /// the octets it adds being zeroed. This may move the storage, hence the handle being
    /// updated, and its side allocations with it.
    ///
    /// # Safety
    ///
    /// The caller has to own the only reference to the storage.
    ///
    /// When the allocation fails, the storage is left as it was.
    #[cold]
    unsafe fn grow(&mut self, capacity: usize) -> AllocResult<()> {
        let old_cap = self.header().cap;
        let cap = capacity.div_ceil(ALIGN).max(old_cap * 2);
        // SAFETY: The layout of a live storage is valid.
        let old_layout = unsafe { Self::layout(old_cap).unwrap_unchecked() };
        let new_layout = Self::layout(cap).ok_or(None)?;
        // SAFETY: The storage is ours alone, allocated with that layout.
        let ptr = unsafe { alloc::realloc(self.0.as_ptr().cast(), old_layout, new_layout.size()) };
        self.0 = NonNull::new(ptr.cast::<HeapHeader>()).ok_or(Some(new_layout))?;
        // SAFETY: The new allocation holds the header, followed by that many units.
        unsafe {
            (*self.0.as_ptr()).cap = cap;
            self.data().add(old_cap * ALIGN).write_bytes(0, (cap - old_cap) * ALIGN);
        }
        Ok(())
    }

}

/// A side allocation that is not attached to a storage yet, see [`Heap::push_side`],
/// which is freed if it never is: its payload is filled before the allocation is attached,
/// so that nothing is left attached to a shared storage when filling it fails.
struct DetachedSide(NonNull<SideHeader>);

impl DetachedSide {

    /// Allocate a side allocation of that payload size, whose payload is left
    /// uninitialized and aligned on 8 octets.
    fn new(size: usize) -> AllocResult<Self> {
        let layout = Heap::side_layout(size).ok_or(None)?;
        // SAFETY: The layout is never zero-sized, it always holds the side header.
        let side = NonNull::new(unsafe { alloc::alloc(layout) }.cast::<SideHeader>()).ok_or(Some(layout))?;
        // SAFETY: The allocation is valid for the side header.
        unsafe { side.write(SideHeader { next: ptr::null_mut(), size }) };
        Ok(Self(side))
    }

    /// The payload of this side allocation.
    #[inline]
    fn payload(&self) -> NonNull<u8> {
        // SAFETY: The payload directly follows the side header, in the same allocation.
        unsafe { self.0.add(1).cast::<u8>() }
    }

}

impl Drop for DetachedSide {
    fn drop(&mut self) {
        // SAFETY: The side allocation was never attached, and was allocated with the layout
        // its header gives back.
        unsafe { alloc::dealloc(self.0.as_ptr().cast(), Heap::side_layout((*self.0.as_ptr()).size).unwrap_unchecked()) }
    }
}

/// A reference to a storage, and where in it: what a [`Buf`] is made of, unless it is held
/// in place.
struct HeapRef {
    /// Inner pointer to the heap.
    inner: Heap,
    /// Offset in the storage, in octets.
    offset: usize,
}

impl HeapRef {

    /// A reference to the storage of whatever holds no values at all.
    const EMPTY: Self = Self {
        inner: Heap::EMPTY,
        offset: 0,
    };

    /// A reference to a new storage of a copy of these octets, of at least that capacity.
    fn copy(bytes: &[u8], capacity: usize) -> AllocResult<Self> {
        let storage = Heap::alloc(bytes.len().max(capacity))?;
        // SAFETY: The storage holds at least that many octets.
        unsafe { ptr::copy_nonoverlapping(bytes.as_ptr(), storage.data(), bytes.len()) };
        Ok(Self { inner: storage, offset: 0 })
    }

    /// Where these octets start in the storage.
    #[inline]
    fn ptr(&self) -> *mut u8 {
        // SAFETY: The offset is within the storage.
        unsafe { self.inner.data().add(self.offset) }
    }

    /// Another reference to the same storage, that many octets further.
    #[inline]
    fn clone_at(&self, count: usize) -> Self {
        self.inner.acquire();
        Self { inner: self.inner, offset: self.offset + count }
    }

    #[inline]
    fn is_unique(&self) -> bool {
        self.inner.is_unique()
    }

    /// Whether what holds this reference can be a [`BufMut`]: when it is the only reference
    /// to its storage, or when this is the empty storage, which a buffer never writes but
    /// grows out of, see [`BufMut::reserve`].
    #[inline]
    fn is_writable(&self) -> bool {
        self.inner.is_immortal() || self.inner.is_unique()
    }

}

impl Clone for HeapRef {
    #[inline]
    fn clone(&self) -> Self {
        self.clone_at(0)
    }
}

impl Drop for HeapRef {
    #[inline]
    fn drop(&mut self) {
        // SAFETY: This owns its reference, and is not used anymore.
        unsafe { self.inner.release() }
    }
}


// =========================== //
//            Spans            //
// =========================== //

/// Where the values of a [`Buf`] are in its storage: the range of octets of each of them,
/// either computed, see [`PackedSpans`], or given by a table, see [`TableSpans`].
///
/// # Safety
///
/// The ranges must be those the buffer was built with.
pub unsafe trait Spans: Copy + Send + Sync + 'static {

    /// The spans of no values at all.
    const EMPTY: Self;

    /// The offset and the length, in octets, of the value at that index, relative to where
    /// the buffer starts in its storage.
    ///
    /// # Safety
    ///
    /// The buffer these are the spans of must hold a value at that index.
    unsafe fn span(self, index: usize) -> (usize, usize);

    /// How many octets further the buffer starts, and the spans, of the buffer starting
    /// that many values further, which is what slicing is made of.
    ///
    /// # Safety
    ///
    /// The buffer these are the spans of must hold at least that many values.
    unsafe fn advance(self, count: usize) -> (usize, Self);

}

/// The spans of values packed one after the other, each as many octets as their type:
/// nothing is stored, the range of a value is computed from its index.
pub struct PackedSpans<T>(PhantomData<fn() -> T>);

impl<T> PackedSpans<T> {
    #[inline]
    const fn new() -> Self {
        Self(PhantomData)
    }
}

impl<T> Clone for PackedSpans<T> {
    #[inline]
    fn clone(&self) -> Self {
        *self
    }
}

impl<T> Copy for PackedSpans<T> {}

// SAFETY: The ranges are those of packed values of that type.
unsafe impl<T: 'static> Spans for PackedSpans<T> {

    const EMPTY: Self = Self::new();

    #[inline]
    unsafe fn span(self, index: usize) -> (usize, usize) {
        (index * mem::size_of::<T>(), mem::size_of::<T>())
    }

    #[inline]
    unsafe fn advance(self, count: usize) -> (usize, Self) {
        (count * mem::size_of::<T>(), self)
    }

}

/// The spans of values anywhere in the storage, each given by a table of ranges of octets,
/// relative to where the buffer starts: the table is a side allocation of the storage, so
/// it lives as long as the storage without being counted, and slicing the values only
/// moves the pointer to their ranges.
///
/// The span of a buffer built with a single value takes no table: the buffer starts where
/// its value does, and the length of the value is held in place of the pointer, tagged by
/// its lowest bit, which a table, aligned for its ranges, never has set.
#[derive(Clone, Copy)]
pub struct TableSpans(NonNull<Range<u32>>);

// SAFETY: The table is never written once it is shared.
unsafe impl Send for TableSpans {}
unsafe impl Sync for TableSpans {}

impl TableSpans {

    /// The span of a single value of that length, starting where the buffer starts, which
    /// is never more than `isize::MAX` octets since it is within an allocation.
    #[inline]
    fn single(len: usize) -> Self {
        debug_assert!(len <= isize::MAX as usize);
        // SAFETY: The tag bit is set, so the address is never zero.
        Self(NonNull::without_provenance(unsafe { NonZero::new_unchecked(len << 1 | 1) }))
    }

    /// The length of the single value these are the span of, absent for a table.
    #[inline]
    fn single_len(self) -> Option<usize> {
        let addr = self.0.addr().get();
        (addr & 1 != 0).then_some(addr >> 1)
    }

}

// SAFETY: The ranges are those of the table, checked when it was built, or the single one
// starting where the buffer does.
unsafe impl Spans for TableSpans {

    const EMPTY: Self = Self(NonNull::dangling());

    #[inline]
    unsafe fn span(self, index: usize) -> (usize, usize) {
        if let Some(len) = self.single_len() {
            return (0, len);
        }
        // SAFETY: The caller guarantees the range is there, and it was checked not to be
        // inverted when the table was built.
        let Range { start, end } = unsafe { self.0.add(index).read() };
        (start as usize, (end - start) as usize)
    }

    #[inline]
    unsafe fn advance(self, count: usize) -> (usize, Self) {
        if let Some(len) = self.single_len() {
            // The caller guarantees there is that many values, so none or the only one.
            return if count == 0 { (0, self) } else { (len, Self::EMPTY) };
        }
        // SAFETY: The caller guarantees there are that many spans.
        (0, Self(unsafe { self.0.add(count) }))
    }

}


// =========================== //
//           Elements          //
// =========================== //

/// A type of the values a [`Buf`] holds: where they are in its storage, see [`Spans`], and
/// what octets are one of them.
///
/// This is implemented for every [`PackedElement`], and for [`str`](prim@str), whose values are at
/// the spans of a table.
///
/// # Safety
///
/// [`Self::read`] must be sound for any octets [`Self::validate`] accepts.
pub unsafe trait Element: Send + Sync + 'static {

    /// How one value is given out: by value for a packed type, borrowed for a string.
    type Ref<'a>: Copy + Debug;

    /// Where the values are in the storage.
    type Spans: Spans;

    /// Whether a scalar of this type is held in place of a storage, which only a packed
    /// type small enough can be.
    const INLINE_FIXED: bool;

    /// Whether these octets are one valid value.
    fn validate(bytes: &[u8]) -> bool;

    /// The value in these octets.
    ///
    /// # Safety
    ///
    /// The octets must have been accepted by [`Self::validate`], and be aligned for a
    /// packed type.
    unsafe fn read<'a>(ptr: *const u8, len: usize) -> Self::Ref<'a>
    where
        Self: 'a;

    /// Format the values of one row of a buffer for [`Debug`], along its first dimension,
    /// within the brackets of that row: separated by commas unless a type has a better way.
    fn fmt_row<'a, I>(values: I, f: &mut fmt::Formatter<'_>) -> fmt::Result
    where
        I: Iterator<Item = Self::Ref<'a>>,
        Self: 'a,
    {
        for (index, value) in values.enumerate() {
            if index != 0 {
                f.write_str(", ")?;
            }
            Debug::fmt(&value, f)?;
        }
        Ok(())
    }

}

/// An element whose values are packed as their octets, one after the other, which is what
/// allows a [`Buf`] of them to be seen as a slice, see [`Buf::as_slice`], and written, see
/// [`BufMut`].
///
/// # Safety
///
/// The type must have no padding and not be zero-sized, its values must be exactly the
/// octets [`Self::validate_all`] accepts, read as they are, and octets that are all zeroes
/// must be a valid value, which is what new room in a storage holds.
pub unsafe trait PackedElement: Element<Spans = PackedSpans<Self>> + Copy {

    /// Whether the octets of a whole number of consecutive values are all valid values,
    /// in a single pass: what octets are checked with when they are cast, and what
    /// [`Element::validate`] is for one value.
    fn validate_all(bytes: &[u8]) -> bool;

}

/// What [`Element::INLINE_FIXED`] is for a packed type, checking it can be held in place.
const fn inline_fixed<T>() -> bool {
    assert!(mem::size_of::<T>() > 0, "a packed type is not zero-sized");
    assert!(mem::size_of::<T>() <= mem::size_of::<Repr>(), "a packed type fits in place of a storage");
    assert!(mem::align_of::<T>() <= ALIGN, "a packed type is aligned on at most 8 octets");
    true
}

/// Implement [`PackedElement`] for these types, all of whose octet patterns are valid
/// values unless a check of each octet is given.
macro_rules! impl_packed_element {
    ($($ty:ty $(where |$octet:ident| $valid:expr)? $(, debug $debug:path)?);* $(;)?) => { $(
        // SAFETY: The type has no padding, and is read from the octets validated.
        unsafe impl Element for $ty {

            type Ref<'a> = $ty;
            type Spans = PackedSpans<$ty>;

            const INLINE_FIXED: bool = inline_fixed::<$ty>();

            #[inline]
            fn validate(bytes: &[u8]) -> bool {
                bytes.len() == mem::size_of::<$ty>() && Self::validate_all(bytes)
            }

            #[inline]
            unsafe fn read<'a>(ptr: *const u8, _len: usize) -> $ty
            where
                $ty: 'a,
            {
                // SAFETY: The caller guarantees the value is there, and aligned.
                unsafe { ptr.cast::<$ty>().read() }
            }

            $(
            #[inline]
            fn fmt_row<'a, I>(values: I, f: &mut fmt::Formatter<'_>) -> fmt::Result
            where
                I: Iterator<Item = $ty>,
                $ty: 'a,
            {
                $debug(values, f)
            }
            )?

        }

        // SAFETY: Same as above, and zero is a valid value of each of these types.
        unsafe impl PackedElement for $ty {
            #[inline]
            fn validate_all(_bytes: &[u8]) -> bool {
                true $(&& _bytes.iter().all(|&$octet| $valid))?
            }
        }
    )* };
}

impl_packed_element!(
    u8, debug fmt_octets;
    i8; u16; i16; u32; i32; u64; i64; f32; f64; DevEnum;
    bool where |octet| octet <= 1;
    DevState where |octet| octet <= DevState::Unknown as u8;
);

/// Format octets as hexadecimal for [`Debug`], with runs of readable ASCII quoted, which is
/// how the octets of a stream are best told apart.
fn fmt_octets(octets: impl Iterator<Item = u8>, f: &mut fmt::Formatter<'_>) -> fmt::Result {

    let mut ascii = false;

    for (index, byte) in octets.enumerate() {

        if index != 0 && !ascii {
            f.write_str(" ")?;
        }

        if byte.is_ascii_alphanumeric() || matches!(byte, b' ' | b':' | b'/' | b'.' | b'-' | b'_') {
            if !ascii {
                f.write_str("'")?;
                ascii = true;
            }
            write!(f, "{}", byte as char)?;
        } else {
            if ascii {
                f.write_str("' ")?;
                ascii = false;
            }
            write!(f, "{byte:02X}")?;
        }

    }

    if ascii {
        f.write_str("'")?;
    }

    Ok(())

}

/// Format the octets of packed values as hexadecimal, two digits each, in the order they
/// are stored. The octets of each value are grouped together, groups being separated by a
/// space, except for octets, which are a single run that [`BufMut::from_hex`] parses back.
fn fmt_hex<T: PackedElement>(octets: &[u8], f: &mut fmt::Formatter<'_>, upper: bool) -> fmt::Result {
    let size = mem::size_of::<T>();
    for (index, &byte) in octets.iter().enumerate() {
        if size > 1 && index != 0 && index % size == 0 {
            f.write_str(" ")?;
        }
        if upper { write!(f, "{byte:02X}")? } else { write!(f, "{byte:02x}")? }
    }
    Ok(())
}

// SAFETY: A string is read from octets that are valid UTF-8.
unsafe impl Element for str {

    type Ref<'a> = &'a str;
    type Spans = TableSpans;

    const INLINE_FIXED: bool = false;

    #[inline]
    fn validate(bytes: &[u8]) -> bool {
        str::from_utf8(bytes).is_ok()
    }

    #[inline]
    unsafe fn read<'a>(ptr: *const u8, len: usize) -> &'a str
    where
        str: 'a,
    {
        // SAFETY: The caller guarantees the octets are there, and valid UTF-8.
        unsafe { str::from_utf8_unchecked(slice::from_raw_parts(ptr, len)) }
    }

}


// =========================== //
//           Buffers           //
// =========================== //

/// Either a reference to the storage of a buffer, or a scalar held in place, which of the
/// two being known from the type of the buffer, see [`Buf::INLINE`].
#[repr(C)]
union Repr {
    raw: ManuallyDrop<HeapRef>,
    inline: [MaybeUninit<u64>; mem::size_of::<HeapRef>() / 8],
}

/// A shared, typed, N-dimensional array of values, in column-major order, a scalar for
/// `DIM == 0`. Its dimensions are fixed once it is built. Octets are a `Buf<u8, 1>`, cast to other packed types with [`Self::cast`], and
/// turned into strings with [`Buf::from_spans`].
///
/// Cloning a buffer only counts one more reference to its storage, and so does slicing it,
/// which is what allows the buffer of a received message to be handed out in pieces without
/// copying any of it. A packed scalar is held in place and has no storage.
pub struct Buf<T: Element + ?Sized, const DIM: usize> {
    repr: Repr,
    spans: T::Spans,
    dim: [usize; DIM],
    _t: PhantomData<*const T>,
}

// SAFETY: The storage is only written through a unique reference, see `BufMut`, and the
// side allocations are never written once shared; the elements are `Send + Sync`.
unsafe impl<T: Element + ?Sized, const DIM: usize> Send for Buf<T, DIM> {}
unsafe impl<T: Element + ?Sized, const DIM: usize> Sync for Buf<T, DIM> {}

/// The number of values of an array of those dimensions, absent if it overflows.
#[inline]
fn checked_len(dim: &[usize]) -> Option<usize> {
    dim.iter().try_fold(1usize, |len, &d| len.checked_mul(d))
}

/// The bounds of that range over a length, panicking like slice indexing does.
#[track_caller]
fn range_bounds<R: RangeBounds<usize>>(range: R, len: usize) -> Range<usize> {
    let start = match range.start_bound() {
        Bound::Included(&start) => start,
        Bound::Excluded(&start) => start.checked_add(1).expect("range start overflow"),
        Bound::Unbounded => 0,
    };
    let end = match range.end_bound() {
        Bound::Included(&end) => end.checked_add(1).expect("range end overflow"),
        Bound::Excluded(&end) => end,
        Bound::Unbounded => len,
    };
    assert!(start <= end, "slice index starts at {start} but ends at {end}");
    assert!(end <= len, "range end index {end} out of range for length {len}");
    start..end
}


impl<T: Element + ?Sized, const DIM: usize> Buf<T, DIM> {

    /// Whether the buffer is held in place rather than in a storage, which only a scalar of
    /// a packed type is, and which is known from its type alone.
    const INLINE: bool = DIM == 0 && T::INLINE_FIXED;

    /// A buffer of no values, all its dimensions being zero, which allocates nothing: every
    /// empty buffer shares the same static storage.
    #[inline]
    pub const fn new() -> Self {
        const { assert!(DIM >= 1, "a scalar always holds one value") };
        let raw = ManuallyDrop::new(HeapRef::EMPTY);
        Self {
            repr: Repr { raw },
            spans: T::Spans::EMPTY,
            dim: [0; DIM],
            _t: PhantomData,
        }
    }

    /// A buffer of the values at that reference to a storage.
    ///
    /// # Safety
    ///
    /// The buffer must not be inline, and the storage must hold its values there, with
    /// those spans, aligned for a packed type.
    #[inline]
    unsafe fn from_raw(raw: HeapRef, spans: T::Spans, dim: [usize; DIM]) -> Self {
        debug_assert!(!Self::INLINE);
        Self {
            repr: Repr { raw: ManuallyDrop::new(raw) },
            spans,
            dim,
            _t: PhantomData,
        }
    }

    /// The reference to the storage of this buffer, which must not be inline.
    #[inline]
    fn raw(&self) -> &HeapRef {
        debug_assert!(!Self::INLINE);
        // SAFETY: A buffer that is not inline always holds a reference to its storage.
        unsafe { &self.repr.raw }
    }

    /// [`Self::raw`], writable, for a buffer that changes its storage or where in it it is.
    #[inline]
    fn raw_mut(&mut self) -> &mut HeapRef {
        debug_assert!(!Self::INLINE);
        // SAFETY: A buffer that is not inline always holds a reference to its storage.
        unsafe { &mut self.repr.raw }
    }

    /// The reference to the storage of this buffer, which must not be inline, moved out of
    /// it.
    #[inline]
    fn into_raw(self) -> HeapRef {
        let this = ManuallyDrop::new(self);
        // SAFETY: The reference is moved out of a buffer that is never dropped.
        unsafe { ptr::read(this.raw()) }
    }

    /// Where the values of this buffer start, which its spans are relative to.
    #[inline]
    fn base(&self) -> *const u8 {
        if Self::INLINE {
            ptr::addr_of!(self.repr).cast::<u8>()
        } else {
            self.raw().ptr()
        }
    }

    /// [`Self::base`], writable: a scalar held in place is only writable through a pointer
    /// taken from an exclusive reference.
    #[inline]
    fn base_mut(&mut self) -> *mut u8 {
        if Self::INLINE {
            ptr::addr_of_mut!(self.repr).cast::<u8>()
        } else {
            self.raw().ptr()
        }
    }

    /// The value at that index.
    ///
    /// # Safety
    ///
    /// The index must be below the length.
    #[inline]
    unsafe fn read(&self, index: usize) -> T::Ref<'_> {
        // SAFETY: The spans give the range of a value this buffer holds, validated.
        unsafe {
            let (offset, len) = self.spans.span(index);
            T::read(self.base().add(offset), len)
        }
    }

    /// The dimensions of this buffer, the first one varying the fastest.
    #[inline]
    pub fn dim(&self) -> [usize; DIM] {
        self.dim
    }

    /// The number of values of this buffer, 1 for a scalar.
    #[inline]
    pub fn len(&self) -> usize {
        self.dim.iter().product()
    }

    #[inline]
    pub fn is_empty(&self) -> bool {
        self.len() == 0
    }

    /// The index among the values of this buffer of the value at that position, one
    /// coordinate per dimension, in column-major order: the first coordinate is the one
    /// varying the fastest. Absent if a coordinate is out of its dimension.
    #[inline]
    pub fn raw_index(&self, pos: [usize; DIM]) -> Option<usize> {
        let mut index = 0;
        let mut stride = 1;
        for (&coord, &dim) in pos.iter().zip(&self.dim) {
            if coord >= dim {
                return None;
            }
            index += coord * stride;
            stride *= dim;
        }
        Some(index)
    }

    /// The value at that position, one coordinate per dimension, `[x]` for one and `[x, y]`
    /// for two, `[]` giving the value of a scalar. Absent if a coordinate is
    /// out of its dimension.
    #[inline]
    pub fn get(&self, pos: [usize; DIM]) -> Option<T::Ref<'_>> {
        let index = self.raw_index(pos)?;
        // SAFETY: The index of a position within the dimensions is below the length.
        Some(unsafe { self.read(index) })
    }

    /// The value at that position as a scalar of its own, see [`Self::get`]: copied in
    /// place for a packed type, sharing the storage for a string. Absent if a coordinate
    /// is out of its dimension.
    pub fn get_scalar(&self, pos: [usize; DIM]) -> Option<Buf<T, 0>> {

        let index = self.raw_index(pos)?;

        if Buf::<T, 0>::INLINE {
            let mut repr = Repr { inline: [MaybeUninit::uninit(); _] };
            // SAFETY: The index is within the buffer, and a packed value fits in place, see
            // `inline_fixed`; the spans of packed values are the same wherever they are.
            unsafe {
                let (offset, len) = self.spans.span(index);
                ptr::copy_nonoverlapping(self.base().add(offset), ptr::addr_of_mut!(repr).cast::<u8>(), len);
            }
            Some(Buf { repr, spans: self.spans, dim: [], _t: PhantomData })
        } else {
            // SAFETY: The index is within the buffer, and a type that is not held in place
            // as a scalar is not held in place here either; the value starts whole values
            // further, so it is aligned.
            unsafe {
                let (octets, spans) = self.spans.advance(index);
                Some(Buf::from_raw(self.raw().clone_at(octets), spans, []))
            }
        }

    }

    /// The value at that index among the values of this buffer, in column-major order, see
    /// [`Self::raw_index`]. Absent if the index is out of the length.
    #[inline]
    pub fn get_raw(&self, index: usize) -> Option<T::Ref<'_>> {
        // SAFETY: The index is checked against the length.
        (index < self.len()).then(|| unsafe { self.read(index) })
    }

    /// The values of this buffer, in column-major order.
    #[inline]
    pub fn iter(&self) -> impl ExactSizeIterator<Item = T::Ref<'_>> + '_ {
        // SAFETY: The indices are all below the length.
        (0..self.len()).map(move |index| unsafe { self.read(index) })
    }

    /// The part of this buffer within that range of its last dimension, which is the
    /// slowest varying one, so that the part shares the same storage: a range of values for
    /// one dimension, a range of rows for two.
    ///
    /// # Panics
    ///
    /// If the range is out of the last dimension, like slice indexing.
    #[track_caller]
    pub fn slice<R: RangeBounds<usize>>(&self, range: R) -> Self {

        const { assert!(DIM >= 1, "a scalar cannot be sliced") };
        let Range { start, end } = range_bounds(range, self.dim[DIM - 1]);

        let stride: usize = self.dim[..DIM - 1].iter().product();
        
        // SAFETY: The range is within the buffer.
        let (octets, spans) = unsafe { self.spans.advance(start * stride) };
        let mut dim = self.dim;
        dim[DIM - 1] = end - start;

        // SAFETY: The storage holds the values of the part there, aligned since they are
        // whole values further.
        unsafe { Self::from_raw(self.raw().clone_at(octets), spans, dim) }

    }

    /// Take the part of this buffer before `at` along its last dimension out as a buffer
    /// of its own, this one keeping the part from `at` on, both sharing the storage: how a
    /// message is framed out of the octets that arrived, the ones behind it being the
    /// front of the next ones.
    ///
    /// # Panics
    ///
    /// If `at` is past the last dimension.
    #[track_caller]
    pub fn split_to(&mut self, at: usize) -> Self {
        let front = self.slice(..at);
        *self = self.slice(at..);
        front
    }

    /// Take the part of this buffer from `at` on along its last dimension out as a buffer
    /// of its own, this one keeping the part before `at`, both sharing the storage.
    ///
    /// # Panics
    ///
    /// If `at` is past the last dimension.
    #[track_caller]
    pub fn split_off(&mut self, at: usize) -> Self {
        let back = self.slice(at..);
        *self = self.slice(..at);
        back
    }

    /// The same values with other dimensions, as long as they are as many: typically values
    /// decoded in one dimension and given the two dimensions they actually have. A scalar is
    /// one value, so it is reshaped to and from any dimensions of one value, being copied
    /// in or out of place for a packed type, see [`Buf`].
    pub fn reshape<const D: usize>(self, dim: [usize; D]) -> Option<Buf<T, D>> {
        if checked_len(&dim)? != self.len() {
            return None;
        }
        let spans = self.spans;
        // SAFETY: In every case, the values are kept with their spans, and are as many.
        Some(match (Self::INLINE, Buf::<T, D>::INLINE) {
            (false, false) => unsafe { Buf::from_raw(self.into_raw(), spans, dim) },
            // SAFETY: A buffer held in place always holds its inline octets.
            (true, true) => Buf { repr: Repr { inline: unsafe { self.repr.inline } }, spans, dim, _t: PhantomData },
            (true, false) => unsafe {
                let (offset, len) = spans.span(0);
                let bytes = slice::from_raw_parts(self.base().add(offset), len);
                Buf::from_raw(infallible(HeapRef::copy(bytes, len)), spans, dim)
            },
            (false, true) => {
                let raw = self.into_raw();
                let mut repr = Repr { inline: [MaybeUninit::uninit(); _] };
                // SAFETY: The value is copied in place, which is large enough, see
                // `inline_fixed`, before the reference is released.
                unsafe {
                    let (offset, len) = spans.span(0);
                    ptr::copy_nonoverlapping(raw.ptr().add(offset), ptr::addr_of_mut!(repr).cast::<u8>(), len);
                }
                Buf { repr, spans, dim, _t: PhantomData }
            }
        })
    }

    /// The single value of this buffer as a scalar, absent if it does not hold exactly one:
    /// typically a scalar decoded as one dimension of one, see [`Self::reshape`].
    #[inline]
    pub fn into_scalar(self) -> Option<Buf<T, 0>> {
        self.reshape([])
    }

    /// Whether this buffer is the only reference to its storage, which a buffer held in
    /// place always is.
    #[inline]
    pub fn is_unique(&self) -> bool {
        Self::INLINE || self.raw().is_unique()
    }

    /// Whether this buffer can be a [`BufMut`], see [`HeapRef::is_writable`].
    #[inline]
    fn is_writable(&self) -> bool {
        Self::INLINE || self.raw().is_writable()
    }

}

impl<T: Element + ?Sized> Buf<T, 1> {

    /// Keep only the first values, no more than that many.
    #[inline]
    pub fn truncate(&mut self, len: usize) {
        self.dim[0] = self.dim[0].min(len);
    }

}

impl<T: Element + ?Sized> Buf<T, 0> {

    /// The value of this scalar.
    #[inline]
    pub fn value(&self) -> T::Ref<'_> {
        // SAFETY: A scalar always holds one value.
        unsafe { self.read(0) }
    }

}

// --- Standard traits impl --- //

impl<T: Element + ?Sized, const DIM: usize> Clone for Buf<T, DIM> {
    #[inline]
    fn clone(&self) -> Self {
        let repr = if Self::INLINE {
            // SAFETY: A buffer held in place always holds its inline octets.
            Repr { inline: unsafe { self.repr.inline } }
        } else {
            Repr { raw: ManuallyDrop::new(self.raw().clone()) }
        };
        Self { repr, spans: self.spans, dim: self.dim, _t: PhantomData }
    }
}

impl<T: Element + ?Sized, const DIM: usize> Drop for Buf<T, DIM> {
    #[inline]
    fn drop(&mut self) {
        if !Self::INLINE {
            // SAFETY: A buffer that is not inline always holds a reference, not used anymore.
            unsafe { ManuallyDrop::drop(&mut self.repr.raw) }
        }
    }
}

impl<T: Element + ?Sized, const DIM: usize> Default for Buf<T, DIM> {
    /// An empty buffer, see [`Self::new`].
    #[inline]
    fn default() -> Self {
        Self::new()
    }
}

impl<T: Element + ?Sized, const DIM: usize> PartialEq for Buf<T, DIM>
where
    for<'a> T::Ref<'a>: PartialEq,
{
    /// Two buffers are equal if they have the same dimensions and values, wherever these
    /// are.
    fn eq(&self, other: &Self) -> bool {
        self.dim == other.dim && self.iter().eq(other.iter())
    }
}

impl<T: Element + ?Sized, const DIM: usize> Eq for Buf<T, DIM>
where
    for<'a> T::Ref<'a>: Eq,
{}

// --- Formatters --- //

/// Format a buffer for [`Debug`]: its name and dimensions, and its values with one pair of
/// brackets per dimension, the first one innermost, `Buf<3, 2>[[1, 2, 3], [4, 5, 6]]`, or
/// one row per line in the alternate form. A scalar is its value in parentheses.
fn fmt_buf<'a, T, I>(f: &mut fmt::Formatter<'_>, name: &str, dim: &[usize], mut values: I) -> fmt::Result
where
    T: Element + ?Sized + 'a,
    I: Iterator<Item = T::Ref<'a>>,
{
    f.write_str(name)?;
    if dim.is_empty() {
        f.write_str("(")?;
        T::fmt_row(values, f)?;
        return f.write_str(")");
    }
    f.write_str("<")?;
    for (index, d) in dim.iter().enumerate() {
        if index != 0 {
            f.write_str(", ")?;
        }
        write!(f, "{d}")?;
    }
    f.write_str(">")?;
    fmt_level::<T, I>(f, dim, 0, &mut values)
}

/// Format the values within the last of these dimensions, at that depth of nesting.
fn fmt_level<'a, T, I>(f: &mut fmt::Formatter<'_>, dim: &[usize], depth: usize, values: &mut I) -> fmt::Result
where
    T: Element + ?Sized + 'a,
    I: Iterator<Item = T::Ref<'a>>,
{
    const INDENT: usize = 4;
    let (&len, inner) = dim.split_last().expect("at least one dimension");
    f.write_str("[")?;
    if inner.is_empty() {
        T::fmt_row(values.by_ref().take(len), f)?;
    } else {
        let pretty = f.alternate();
        for index in 0..len {
            if pretty {
                write!(f, "\n{:1$}", "", (depth + 1) * INDENT)?;
            } else if index != 0 {
                f.write_str(", ")?;
            }
            fmt_level::<T, I>(f, inner, depth + 1, values)?;
            if pretty {
                f.write_str(",")?;
            }
        }
        if pretty && len != 0 {
            write!(f, "\n{:1$}", "", depth * INDENT)?;
        }
    }
    f.write_str("]")
}

impl<T: Element + ?Sized, const DIM: usize> Debug for Buf<T, DIM> {
    /// Its dimensions and values, row by row, see [`Element::fmt_row`].
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt_buf::<T, _>(f, "Buf", &self.dim, self.iter())
    }
}

impl<T: PackedElement> UpperHex for Buf<T, 1> {
    /// The octets of the values as hexadecimal, in the order they are stored, each value's
    /// grouped and separated by a space, octets being a single run that
    /// [`BufMut::from_hex`] parses back.
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt_hex::<T>(self.as_bytes(), f, true)
    }
}

impl<T: PackedElement> LowerHex for Buf<T, 1> {
    /// The octets of the values as hexadecimal, in the order they are stored, each value's
    /// grouped and separated by a space, octets being a single run that
    /// [`BufMut::from_hex`] parses back.
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt_hex::<T>(self.as_bytes(), f, false)
    }
}

// --- Packed --- //

impl<T: PackedElement, const DIM: usize> Buf<T, DIM> {

    /// Whether these octets are valid values, as many as the dimensions say, absent if
    /// not, and then whether a buffer of them can share their storage, being aligned and
    /// not held in place.
    #[inline]
    fn check_packed(bytes: &[u8], dim: [usize; DIM]) -> Option<bool> {
        let size = checked_len(&dim)?.checked_mul(mem::size_of::<T>())?;
        if bytes.len() != size || !T::validate_all(bytes) {
            return None;
        }
        Some(!Self::INLINE && bytes.as_ptr().addr().is_multiple_of(mem::align_of::<T>()))
    }

    /// A buffer of a copy of these octets, held in place for a scalar, and allocating
    /// nothing if there are none.
    ///
    /// # Safety
    ///
    /// The octets must be valid values, as many as the dimensions say.
    unsafe fn copy_from_bytes(bytes: &[u8], dim: [usize; DIM]) -> Self {
        if Self::INLINE {
            let mut repr = Repr { inline: [MaybeUninit::uninit(); _] };
            // SAFETY: The inline octets are large enough, see `inline_fixed`.
            unsafe { ptr::copy_nonoverlapping(bytes.as_ptr(), ptr::addr_of_mut!(repr).cast::<u8>(), bytes.len()) };
            Self { repr, spans: PackedSpans::new(), dim, _t: PhantomData }
        } else if bytes.is_empty() {
            // SAFETY: The empty storage holds no values, as many as the dimensions say.
            unsafe { Self::from_raw(HeapRef::EMPTY, PackedSpans::new(), dim) }
        } else {
            // SAFETY: A new storage is aligned for any packed type.
            unsafe { Self::from_raw(infallible(HeapRef::copy(bytes, bytes.len())), PackedSpans::new(), dim) }
        }
    }

    /// A buffer of these values, with those dimensions, copied into a new storage unless it
    /// is a scalar, which is held in place. Absent if the values are not as many as the
    /// dimensions say.
    pub fn from_slice(values: &[T], dim: [usize; DIM]) -> Option<Self> {
        if checked_len(&dim)? != values.len() {
            return None;
        }
        // SAFETY: A packed type has no padding, so its values are all initialized octets.
        let bytes = unsafe { slice::from_raw_parts(values.as_ptr().cast::<u8>(), mem::size_of_val(values)) };
        // SAFETY: The octets are those of valid values, as many as the dimensions say.
        Some(unsafe { Self::copy_from_bytes(bytes, dim) })
    }

    /// A buffer of zeroes with those dimensions, see [`BufMut::zeroed`].
    #[inline]
    pub fn zeroed(dim: [usize; DIM]) -> Self {
        BufMut::zeroed(dim).freeze()
    }

    /// Where the values of this buffer start.
    #[inline]
    pub fn as_ptr(&self) -> *const T {
        self.base().cast::<T>()
    }

    /// The values of this buffer, in column-major order.
    #[inline]
    pub fn as_slice(&self) -> &[T] {
        // SAFETY: The buffer holds that many initialized and aligned values.
        unsafe { slice::from_raw_parts(self.as_ptr(), self.len()) }
    }

    /// The octets of the values of this buffer, what a backend encodes them from.
    #[inline]
    pub fn as_bytes(&self) -> &[u8] {
        // SAFETY: A packed type has no padding, so its values are all initialized octets.
        unsafe { slice::from_raw_parts(self.base(), self.len() * mem::size_of::<T>()) }
    }

    /// The octets of this buffer as packed values of another type, with those dimensions,
    /// sharing its storage if they are aligned for that type, and copied otherwise, or
    /// held in place for a scalar. The buffer is given back if it does not hold as many
    /// octets as the dimensions say, or holds an invalid value.
    ///
    /// This is how a backend decodes an array out of the message it received, in native
    /// byte order, typically out of a slice of it.
    pub fn cast<U: PackedElement, const D: usize>(self, dim: [usize; D]) -> Result<Buf<U, D>, Self> {

        let Some(share) = Buf::<U, D>::check_packed(self.as_bytes(), dim) else { 
            return Err(self);
        };

        // SAFETY: Checked above, the storage being shared only if this one has one.
        Ok(unsafe {
            if share && !Self::INLINE {
                Buf::from_raw(self.into_raw(), PackedSpans::new(), dim)
            } else {
                Buf::copy_from_bytes(self.as_bytes(), dim)
            }
        })

    }

    /// The octets of the values of this buffer, a new buffer for a scalar held in place.
    pub fn into_bytes(self) -> Buf<u8, 1> {
        let len = self.as_bytes().len();
        match self.cast([len]) {
            Ok(bytes) => bytes,
            Err(_) => unreachable!("every octet is a valid one"),
        }
    }

    /// This buffer as a writable one, for as long as it is borrowed, absent if its storage
    /// is shared, like `Arc::get_mut`.
    #[inline]
    pub fn get_mut(&mut self) -> Option<&mut BufMut<T, DIM>> {
        // SAFETY: The buffer is the only reference to its storage, and nothing can share
        // it while it is exclusively borrowed.
        self.is_writable().then(|| unsafe { &mut *(self as *mut Self).cast::<BufMut<T, DIM>>() })
    }

    /// This buffer as a writable one, for as long as it is borrowed, which first copies its
    /// values into a storage of their own if its storage is shared: only these values are
    /// copied, not the whole storage.
    #[inline]
    pub fn make_mut(&mut self) -> &mut BufMut<T, DIM> {
        if !self.is_writable() {
            // SAFETY: The octets are those of the values of this buffer.
            *self = unsafe { Self::copy_from_bytes(self.as_bytes(), self.dim) };
        }
        // SAFETY: The buffer is the only reference to its storage, and borrowed as such.
        unsafe { &mut *(self as *mut Self).cast::<BufMut<T, DIM>>() }
    }

    /// This buffer as one that is statically the only reference to its storage, given
    /// back if its storage is shared, which the empty storage never is.
    #[inline]
    pub fn try_into_mut(self) -> Result<BufMut<T, DIM>, Self> {
        if self.is_writable() {
            Ok(BufMut(self))
        } else {
            Err(self)
        }
    }

    /// This buffer as one that is statically the only reference to its storage, which
    /// copies its values into a storage of their own if its storage is shared, see
    /// [`Self::make_mut`].
    #[inline]
    pub fn into_mut(mut self) -> BufMut<T, DIM> {
        self.make_mut();
        BufMut(self)
    }

    /// The part of this buffer that these values are, sharing its storage, see
    /// [`Self::slice`]: what values taken out of [`Self::as_slice`] turn back into, such as
    /// the octets a decoder that only handles slices has read.
    ///
    /// # Panics
    ///
    /// If the values are not within this buffer, or are not a range of its last dimension:
    /// any range of values for one dimension, but only whole rows for two.
    #[track_caller]
    pub fn slice_ref(&self, subset: &[T]) -> Self {

        const { assert!(DIM >= 1, "a scalar cannot be sliced") };
        
        let size = mem::size_of::<T>();
        let offset = subset.as_ptr().addr().wrapping_sub(self.base().addr());
        let (start, len) = (offset / size, self.len());
        
        assert!(offset.is_multiple_of(size) && start <= len && subset.len() <= len - start,
            "the values at {:p} are not within the buffer at {:p}, of {len} values", 
            subset.as_ptr(), 
            self.base());

        let stride: usize = self.dim[..DIM - 1].iter().product();
        if stride == 0 {
            return self.slice(..0);
        }

        assert!(start.is_multiple_of(stride) && subset.len().is_multiple_of(stride),
            "the values {start}..{} are not whole rows of {stride} values", 
            start + subset.len());
        
        self.slice(start / stride..(start + subset.len()) / stride)

    }

}

impl<T: PackedElement> From<T> for Buf<T, 0> {
    /// A scalar of that value, held in place.
    #[inline]
    fn from(value: T) -> Self {
        Self::from_slice(slice::from_ref(&value), []).expect("a scalar holds one value")
    }
}

impl<T: PackedElement> From<&[T]> for Buf<T, 1> {
    #[inline]
    fn from(values: &[T]) -> Self {
        Self::from_slice(values, [values.len()]).expect("same length")
    }
}

impl<T: PackedElement> From<Vec<T>> for Buf<T, 1> {
    #[inline]
    fn from(values: Vec<T>) -> Self {
        Self::from(values.as_slice())
    }
}

impl<T: PackedElement> From<Box<[T]>> for Buf<T, 1> {
    #[inline]
    fn from(values: Box<[T]>) -> Self {
        Self::from(&*values)
    }
}

impl<T: PackedElement, const N: usize> From<[T; N]> for Buf<T, 1> {
    #[inline]
    fn from(values: [T; N]) -> Self {
        Self::from(values.as_slice())
    }
}

impl<T: PackedElement, const DIM: usize> From<BufMut<T, DIM>> for Buf<T, DIM> {
    #[inline]
    fn from(buf: BufMut<T, DIM>) -> Self {
        buf.freeze()
    }
}

// --- Table --- //

impl<T: Element<Spans = TableSpans> + ?Sized, const DIM: usize> Buf<T, DIM> {

    /// The values at these spans of these octets, with those dimensions, sharing their
    /// storage, each span being accepted by that check. The octets are given back if the
    /// spans are not as many as the dimensions say, if one of them is not accepted, or if
    /// their table cannot be allocated, as many spans as the dimensions say being allocated
    /// before any is checked, and the dimensions possibly coming off the wire.
    fn with_spans<I, F>(bytes: Buf<u8, 1>, spans: I, dim: [usize; DIM], mut check: F) -> Result<Self, Buf<u8, 1>>
    where
        I: IntoIterator<Item = Range<u32>>,
        F: FnMut(&[u8], &Range<u32>) -> bool,
    {

        let Some(len) = checked_len(&dim) else { 
            return Err(bytes);
        };

        let mut spans = spans.into_iter();

        // With length zero we don't have to 
        if len == 0 {
            
            if spans.next().is_some() {
                return Err(bytes);
            }

            // SAFETY: The storage holds no values, as many as the dimensions say.
            return Ok(unsafe { Self::from_raw(bytes.into_raw(), TableSpans::EMPTY, dim) });

        }

        // A single value takes no table, the buffer starting where it does, so nothing is
        // allocated, not even for an empty value within the empty storage.
        if len == 1 {

            let Some(span) = spans.next().filter(|span| check(bytes.as_slice(), span)) else {
                return Err(bytes);
            };

            if spans.next().is_some() {
                return Err(bytes);
            }

            let mut raw = bytes.into_raw();
            raw.offset += span.start as usize;
            // SAFETY: The span was accepted, within the octets, which start further by its
            // start, and the dimensions say a single value.
            return Ok(unsafe { Self::from_raw(raw, TableSpans::single(span.len()), dim) });
            
        }

        let Some(size) = len.checked_mul(mem::size_of::<Range<u32>>()) else { 
            return Err(bytes);
        };

        let Ok(side) = DetachedSide::new(size) else { 
            return Err(bytes);
        };

        let table = side.payload().cast::<Range<u32>>();
        for index in 0..len {
            let Some(span) = spans.next().filter(|span| check(bytes.as_slice(), span)) else { 
                return Err(bytes);
            };
            // SAFETY: The table holds that many spans, and is aligned for them.
            unsafe { table.add(index).write(span) };
        }

        if spans.next().is_some() {
            return Err(bytes);
        }

        let mut raw = bytes.into_raw();
        // Nothing is attached to the empty storage: empty values within it are given a
        // storage of their own, which they need no octets of.
        if raw.inner.is_immortal() {
            raw = HeapRef { inner: infallible(Heap::alloc(0)), offset: 0 };
        }
        raw.inner.push_side(side);

        // SAFETY: The spans were all accepted, as many as the dimensions say.
        Ok(unsafe { Self::from_raw(raw, TableSpans(table), dim) })
        
    }

}

impl<const DIM: usize> Buf<str, DIM> {

    /// The strings at these spans of these octets, relative to them, with those
    /// dimensions, sharing their storage. The octets are given back if the spans are not as
    /// many as the dimensions say, are out of the octets, or are not valid UTF-8.
    ///
    /// This is how a backend decodes strings out of the message it received, the spans
    /// being typically given as it reads them.
    pub fn from_spans<I>(bytes: Buf<u8, 1>, spans: I, dim: [usize; DIM]) -> Result<Self, Buf<u8, 1>>
    where
        I: IntoIterator<Item = Range<u32>>,
    {
        Self::with_spans(bytes, spans, dim, |bytes, span| {
            bytes.get(span.start as usize..span.end as usize).is_some_and(str::validate)
        })
    }

    /// The unchecked form of [`Self::from_spans`], for a backend that already validated
    /// the strings: only their number is checked.
    ///
    /// # Safety
    ///
    /// The spans must be within the octets, and valid UTF-8 there.
    ///
    /// # Panics
    ///
    /// If the spans are not as many as the dimensions say, or if their table cannot be
    /// allocated.
    #[inline]
    #[track_caller]
    pub unsafe fn from_spans_unchecked<I>(bytes: Buf<u8, 1>, spans: I, dim: [usize; DIM]) -> Self
    where
        I: IntoIterator<Item = Range<u32>>,
    {
        Self::with_spans(bytes, spans, dim, |_, _| true)
            .unwrap_or_else(|_| panic!("no table of as many spans as the dimensions {dim:?} say"))
    }

}

impl Buf<str, 1> {

    /// A buffer of copies of these strings, as many as there are. Absent if several of them
    /// do not fit spans of 32 bits.
    ///
    /// A single string is copied into a storage of its own, its span taking no table, so
    /// it allocates nothing more, and nothing at all when it is empty.
    pub fn from_strs<I>(values: I) -> Option<Self>
    where
        I: IntoIterator,
        I::Item: AsRef<str>,
    {

        let mut values = values.into_iter();

        let Some(first) = values.next() else {
            // SAFETY: The empty storage holds no values, as many as the dimensions say.
            return Some(unsafe { Self::from_raw(HeapRef::EMPTY, TableSpans::EMPTY, [0]) });
        };

        let Some(second) = values.next() else {
            let value = first.as_ref();
            let raw = if value.is_empty() { HeapRef::EMPTY } else { infallible(HeapRef::copy(value.as_bytes(), 0)) };
            // SAFETY: The storage holds that single string where the buffer starts.
            return Some(unsafe { Self::from_raw(raw, TableSpans::single(value.len()), [1]) });
        };

        let mut buf = BufMut::<u8, 1>::new();
        // The size hint only tells how many spans to make room for: the strings are copied
        // as they come, whatever it said.
        let mut spans = Vec::with_capacity(values.size_hint().0.saturating_add(2));

        for value in [first, second].into_iter().chain(values) {
            let start = u32::try_from(buf.len()).ok()?;
            buf.extend_from_slice(value.as_ref().as_bytes());
            spans.push(start..u32::try_from(buf.len()).ok()?);
        }

        let len = spans.len();
        // SAFETY: The spans are those of the strings just written, as many as the
        // dimensions say.
        Some(unsafe { Self::from_spans_unchecked(buf.freeze(), spans, [len]) })

    }

}

impl From<&str> for Buf<str, 0> {
    /// A scalar of a copy of that string, which is its only allocation, none if it is
    /// empty.
    #[inline]
    fn from(value: &str) -> Self {
        Buf::<str, 1>::from_strs([value])
            .and_then(Buf::into_scalar)
            .expect("a single string always makes a scalar")
    }
}

impl From<Cow<'_, str>> for Buf<str, 0> {
    /// A scalar of a copy of that string.
    #[inline]
    fn from(value: Cow<'_, str>) -> Self {
        Self::from(&*value)
    }
}

impl From<String> for Buf<str, 0> {
    /// A scalar of a copy of that string.
    #[inline]
    fn from(value: String) -> Self {
        Self::from(value.as_str())
    }
}

impl<S: AsRef<str>> From<&[S]> for Buf<str, 1> {
    #[inline]
    fn from(values: &[S]) -> Self {
        Self::from_strs(values).expect("strings of more than 4 GiB")
    }
}


// =========================== //
//       Writable buffers      //
// =========================== //

/// A buffer of packed values that is statically the only reference to its storage, like a
/// `Vec`: it is written without ever checking whether its storage is shared, it grows
/// along one dimension, and it turns into a [`Buf`] to be shared, see [`Self::freeze`]. A [`Buf`] turns
/// into one with copy-on-write, see [`Buf::make_mut`] and [`Buf::into_mut`].
///
/// It cannot be sliced, which would share its storage, and cloning it copies its values
/// into a storage of their own, like a `Vec`. An empty one may have no storage of its own,
/// see [`Self::new`], until it first grows.
#[repr(transparent)]
pub struct BufMut<T: PackedElement, const DIM: usize>(Buf<T, DIM>);

impl<T: PackedElement, const DIM: usize> BufMut<T, DIM> {

    /// A buffer of zeroes with those dimensions, held in place for a scalar.
    ///
    /// # Panics
    ///
    /// If the dimensions are too large for a storage.
    pub fn zeroed(dim: [usize; DIM]) -> Self {

        let size = checked_len(&dim)
            .and_then(|len| len.checked_mul(mem::size_of::<T>()))
            .expect("capacity overflow");

        if Buf::<T, DIM>::INLINE || size == 0 {
            // SAFETY: Zeroes are valid values of a packed type, as many as the dimensions say.
            return Self(unsafe { Buf::copy_from_bytes(&[0; mem::size_of::<Repr>()][..size], dim) });
        }

        let raw = HeapRef { inner: infallible(Heap::alloc(size)), offset: 0 };

        // SAFETY: A new storage is aligned for any packed type, and holds zeroes.
        Self(unsafe { Buf::from_raw(raw, PackedSpans::new(), dim) })
        
    }

    /// A buffer of these values, see [`Buf::from_slice`].
    #[inline]
    pub fn from_slice(values: &[T], dim: [usize; DIM]) -> Option<Self> {
        Buf::from_slice(values, dim).map(Self)
    }

    /// The dimensions of this buffer, see [`Buf::dim`].
    #[inline]
    pub fn dim(&self) -> [usize; DIM] {
        self.0.dim
    }

    /// The number of values of this buffer, 1 for a scalar.
    #[inline]
    pub fn len(&self) -> usize {
        self.0.len()
    }

    #[inline]
    pub fn is_empty(&self) -> bool {
        self.0.is_empty()
    }

    /// Where the values of this buffer start.
    #[inline]
    pub fn as_ptr(&self) -> *const T {
        self.0.as_ptr()
    }

    #[inline]
    pub fn as_slice(&self) -> &[T] {
        self.0.as_slice()
    }

    #[inline]
    pub fn as_mut_slice(&mut self) -> &mut [T] {
        let len = self.len();
        // SAFETY: The buffer holds that many aligned values, in a storage it alone references.
        unsafe { slice::from_raw_parts_mut(self.0.base_mut().cast::<T>(), len) }
    }

    #[inline]
    pub fn as_bytes(&self) -> &[u8] {
        self.0.as_bytes()
    }

    /// Share this buffer, which cannot be written anymore unless it is the only reference
    /// to its storage again, see [`Buf::try_into_mut`].
    #[inline]
    pub fn freeze(self) -> Buf<T, DIM> {
        self.0
    }

}

impl<T: PackedElement> BufMut<T, 1> {

    /// An empty buffer, which allocates nothing until it grows, see [`Buf::new`].
    #[inline]
    pub const fn new() -> Self {
        Self(Buf::new())
    }

    /// An empty buffer that can grow to at least that many values without reallocating.
    #[inline]
    pub fn with_capacity(capacity: usize) -> Self {
        let mut buf = Self::new();
        buf.reserve(capacity);
        buf
    }

    /// How many values this buffer can hold without reallocating.
    #[inline]
    pub fn capacity(&self) -> usize {
        let raw = self.0.raw();
        (raw.inner.capacity() - raw.offset) / mem::size_of::<T>()
    }

    /// Where the value at that index is, which may be past the length but not past the
    /// capacity.
    #[inline]
    fn ptr_at(&self, index: usize) -> *mut T {
        debug_assert!(index <= self.capacity());
        // SAFETY: The index is within the capacity.
        unsafe { self.0.raw().ptr().cast::<T>().add(index) }
    }

    /// Make room for at least that many more values, growing the storage if it lacks room.
    #[inline]
    pub fn reserve(&mut self, additional: usize) {
        infallible(self.alloc_reserve(additional))
    }

    /// [`Self::reserve`], failing rather than aborting when the allocation does, which
    /// leaves the buffer as it was: for a length that comes off the wire.
    pub fn try_reserve(&mut self, additional: usize) -> Result<(), Error> {
        self.alloc_reserve(additional).map_err(|_| Error::new(ErrorKind::Internal)
            .with_description(format!("Failed to allocate room for {additional} more values behind {}", self.len())))
    }

    fn alloc_reserve(&mut self, additional: usize) -> AllocResult<()> {
        let len = self.len();
        let raw = self.0.raw_mut();
        let end = len.checked_add(additional)
            .and_then(|len| len.checked_mul(mem::size_of::<T>()))
            .and_then(|size| raw.offset.checked_add(size))
            .ok_or(None)?;
        if end <= raw.inner.capacity() {
            return Ok(());
        }
        if raw.inner.is_immortal() {
            // The empty storage is never written, a buffer grows out of it into a storage
            // of its own, which it starts at, its offset in the empty storage being zero.
            raw.inner = Heap::alloc(end)?;
        } else {
            // SAFETY: The buffer is the only reference to its storage.
            unsafe { raw.inner.grow(end)? };
        }
        Ok(())
    }

    /// Append that value.
    #[inline]
    pub fn push(&mut self, value: T) {
        self.reserve(1);
        // SAFETY: There is room for it, in a storage this buffer alone references.
        unsafe { self.ptr_at(self.len()).write(value) };
        self.0.dim[0] += 1;
    }

    /// Append these values.
    pub fn extend_from_slice(&mut self, values: &[T]) {
        self.reserve(values.len());
        // SAFETY: There is room for them, in a storage this buffer alone references.
        unsafe { ptr::copy_nonoverlapping(values.as_ptr(), self.ptr_at(self.len()), values.len()) };
        self.0.dim[0] += values.len();
    }

    /// Grow or shrink to that many values, the added ones being that value.
    ///
    /// Zeroes are only written up to the capacity this buffer had before growing: what a
    /// storage grows by is already zeroed.
    pub fn resize(&mut self, len: usize, value: T) {
        let old_len = self.len();
        if len > old_len {
            // SAFETY: A packed type has no padding, so its value is all initialized octets.
            let bytes = unsafe { slice::from_raw_parts(ptr::from_ref(&value).cast::<u8>(), mem::size_of::<T>()) };
            let end = if bytes.iter().all(|&octet| octet == 0) {
                // Values that are partly within the old capacity are written.
                let raw = self.0.raw();
                len.min((raw.inner.capacity() - raw.offset).div_ceil(mem::size_of::<T>()))
            } else {
                len
            };
            self.reserve(len - old_len);
            for index in old_len..end {
                // SAFETY: There is room for it, in a storage this buffer alone references.
                unsafe { self.ptr_at(index).write(value) };
            }
        }
        self.0.dim[0] = len;
    }

    /// Keep only the first values, no more than that many.
    #[inline]
    pub fn truncate(&mut self, len: usize) {
        self.0.truncate(len);
    }

    /// Empty this buffer, keeping its storage, and so its capacity, and freeing what the
    /// buffers cast from it had attached to it.
    pub fn clear(&mut self) {
        let raw = self.0.raw_mut();
        if !raw.inner.is_immortal() {
            // SAFETY: The buffer is the only reference to its storage.
            unsafe { raw.inner.free_sides() };
        }
        raw.offset = 0;
        self.0.dim[0] = 0;
    }

}

impl BufMut<u8, 1> {

    /// Parse plain hexadecimal octets, in either case, which is what [`UpperHex`] and
    /// [`LowerHex`] give, absent if they are not.
    pub fn from_hex(s: &str) -> Option<Self> {
        if !s.len().is_multiple_of(2) {
            return None;
        }
        let mut buf = Self::with_capacity(s.len() / 2);
        for hex in s.as_bytes().as_chunks::<2>().0 {
            let hex = str::from_utf8(hex).ok()?;
            buf.push(u8::from_str_radix(hex, 16).ok()?);
        }
        Some(buf)
    }

    /// Grow or shrink to that many octets, the added ones being left as they are, which
    /// saves zeroing octets that are about to be written: they are zeroes, unless this
    /// buffer held something there before it was shrunk or cleared.
    ///
    /// This is only for octets, every one of which is valid, unlike what was left there
    /// for other types.
    pub fn set_len(&mut self, len: usize) {
        self.reserve(len.saturating_sub(self.len()));
        self.0.dim[0] = len;
    }

}

// --- Standard traits impl --- //

impl<T: PackedElement, const DIM: usize> Clone for BufMut<T, DIM> {
    /// A copy of the values of this buffer, in a storage of their own, the capacity past
    /// them not being kept.
    #[inline]
    fn clone(&self) -> Self {
        // SAFETY: The octets are those of the values of this buffer.
        Self(unsafe { Buf::copy_from_bytes(self.as_bytes(), self.dim()) })
    }
}

impl<T: PackedElement> Default for BufMut<T, 1> {
    #[inline]
    fn default() -> Self {
        Self::new()
    }
}

impl<T: PackedElement + PartialEq, const DIM: usize> PartialEq for BufMut<T, DIM> {
    #[inline]
    fn eq(&self, other: &Self) -> bool {
        self.dim() == other.dim() && self.as_slice() == other.as_slice()
    }
}

impl<T: PackedElement + Eq, const DIM: usize> Eq for BufMut<T, DIM> {}

impl<T: PackedElement> From<&[T]> for BufMut<T, 1> {
    #[inline]
    fn from(values: &[T]) -> Self {
        Self(Buf::from(values))
    }
}

impl<T: PackedElement> From<Vec<T>> for BufMut<T, 1> {
    #[inline]
    fn from(values: Vec<T>) -> Self {
        Self::from(values.as_slice())
    }
}

// --- Formatters --- //

impl<T: PackedElement, const DIM: usize> Debug for BufMut<T, DIM> {
    /// Its dimensions and values, row by row, see [`Element::fmt_row`].
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt_buf::<T, _>(f, "BufMut", &self.0.dim, self.0.iter())
    }
}

impl<T: PackedElement> UpperHex for BufMut<T, 1> {
    /// The octets of the values as hexadecimal, in the order they are stored, each value's
    /// grouped and separated by a space, octets being a single run that
    /// [`BufMut::from_hex`] parses back.
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt_hex::<T>(self.as_bytes(), f, true)
    }
}

impl<T: PackedElement> LowerHex for BufMut<T, 1> {
    /// The octets of the values as hexadecimal, in the order they are stored, each value's
    /// grouped and separated by a space, octets being a single run that
    /// [`BufMut::from_hex`] parses back.
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt_hex::<T>(self.as_bytes(), f, false)
    }
}

#[cfg(test)]
#[allow(clippy::single_range_in_vec_init)]
mod tests {

    use super::*;

    /// A scalar of a packed type is held in place: it has no storage to share, so it is
    /// always unique, and its only value is at the empty position.
    #[test]
    fn scalar() {
        let scalar = Buf::<f64, 0>::from(1.5);
        assert_eq!(scalar.value(), 1.5);
        assert_eq!(scalar.get([]), Some(1.5));
        assert_eq!(scalar.len(), 1);
        let clone = scalar.clone();
        assert!(scalar.is_unique() && clone.is_unique());
    }

    #[test]
    fn one_dim() {
        let buf = Buf::<i32, 1>::from(vec![1, 2, 3]);
        assert_eq!(buf.dim(), [3]);
        assert_eq!(buf.get([1]), Some(2));
        assert_eq!(buf.get([3]), None);
        assert_eq!(buf.as_slice(), &[1, 2, 3]);
        assert_eq!(buf.iter().sum::<i32>(), 6);
    }

    /// Two dimensions are in column-major order: `[x, y]`, with `x` varying the fastest, so
    /// a 3×2 buffer is its two rows one after the other.
    #[test]
    fn two_dim() {
        let buf = Buf::<u8, 2>::from_slice(&[1, 2, 3, 4, 5, 6], [3, 2]).unwrap();
        assert_eq!(buf.get([0, 1]), Some(4));
        assert_eq!(buf.get([2, 1]), Some(6));
        assert_eq!(buf.get([3, 0]), None);
        assert_eq!(buf.raw_index([1, 1]), Some(4));
        assert_eq!(buf.get_raw(4), Some(5));
        // The dimensions have to account for every value.
        assert!(Buf::<u8, 2>::from_slice(&[1, 2, 3], [2, 2]).is_none());
        // And can be changed afterwards, as long as they still do.
        let flat = buf.reshape([6]).unwrap();
        assert_eq!(flat.as_slice(), &[1, 2, 3, 4, 5, 6]);
    }

    /// Empty buffers allocate nothing, all sharing the same static storage, which is never
    /// written: growing one first gives it a storage of its own.
    #[test]
    fn empty() {
        const EMPTY: Buf<u32, 2> = Buf::new();
        const EMPTY_MUT: BufMut<u8, 1> = BufMut::new();
        assert_eq!(EMPTY.dim(), [0, 0]);
        assert!(!EMPTY.is_unique());
        let mut values = Buf::<u32, 1>::from(vec![]);
        assert_eq!(values.as_ptr().cast::<u8>(), EMPTY_MUT.as_ptr());
        assert_eq!(values.make_mut().as_mut_slice(), &mut []);
        assert!(Buf::<str, 1>::from(&[] as &[&str]).iter().next().is_none());
        // Empty strings within an empty buffer have their spans attached elsewhere.
        let strings = Buf::<str, 1>::from_spans(values.into_bytes(), [0..0, 0..0], [2]).unwrap();
        assert_eq!(strings.iter().collect::<Vec<_>>(), ["", ""]);
        let mut buf = EMPTY_MUT;
        assert_eq!(buf.capacity(), 0);
        buf.clear();
        buf.extend_from_slice(&[]);
        assert_eq!(buf.as_ptr(), EMPTY_MUT.as_ptr());
        buf.extend_from_slice(&[1, 2]);
        assert_ne!(buf.as_ptr(), EMPTY_MUT.as_ptr());
        let mut shared = EMPTY.reshape::<1>([0]).unwrap();
        shared.get_mut().unwrap().resize(3, 7);
        assert_eq!(shared.as_slice(), [7; 3]);
    }

    /// Cloning a writable buffer copies its values, both copies staying unique.
    #[test]
    fn writable_clone() {
        let mut buf = BufMut::from(&[1u16, 2][..]);
        let mut copy = buf.clone();
        assert_ne!(copy.as_ptr(), buf.as_ptr());
        copy.as_mut_slice()[0] = 0;
        buf.push(3);
        assert_eq!((buf.as_slice(), copy.as_slice()), (&[1, 2, 3][..], &[0, 2][..]));
        assert!(buf.freeze().is_unique() && copy.freeze().is_unique());
    }

    /// Values taken out of a buffer turn back into the part of it they are, as long as they
    /// are a range of its last dimension.
    #[test]
    fn slicing_by_ref() {
        let values = Buf::<u16, 1>::from(vec![1, 2, 3, 4]);
        let part = values.slice_ref(&values.as_slice()[1..3]);
        assert_eq!(part.as_slice(), &[2, 3]);
        assert_eq!(part.as_ptr(), values.as_slice()[1..].as_ptr());
        let rows = values.reshape([2, 2]).unwrap();
        assert_eq!(rows.slice_ref(&rows.as_slice()[2..]).dim(), [2, 1]);
        let res = std::panic::catch_unwind(|| rows.slice_ref(&rows.as_slice()[1..3]));
        assert!(res.is_err());
        let other = [3, 4];
        let res = std::panic::catch_unwind(|| rows.slice_ref(&other));
        assert!(res.is_err());
    }

    /// A decoder's slice of octets turns back into the part of the buffer it is.
    #[test]
    fn octets_by_ref() {
        let buf = Buf::from(&b"hello world"[..]);
        let part = buf.slice_ref(&buf.as_slice()[6..]);
        assert_eq!(part.as_slice(), b"world");
        assert!(buf.slice_ref(&buf.as_slice()[11..]).is_empty());
    }

    /// Slicing cuts along the last dimension, values for one dimension or rows for two,
    /// and shares the storage rather than copying.
    #[test]
    fn slicing() {
        let buf = Buf::<u8, 2>::from_slice(&[1, 2, 3, 4, 5, 6], [2, 3]).unwrap();
        let rows = buf.slice(1..);
        assert_eq!(rows.dim(), [2, 2]);
        assert_eq!(rows.as_slice(), &[3, 4, 5, 6]);
        assert!(!buf.is_unique());
        assert_eq!(rows.slice(..1).as_slice(), &[3, 4]);
    }

    /// A scalar is one value: it is reshaped to and from anything of one value, a packed one
    /// moving in and out of place.
    #[test]
    fn scalar_shapes() {
        let scalar = Buf::<u16, 0>::from(7);
        let square = scalar.clone().reshape([1, 1]).unwrap();
        assert_eq!(square.as_slice(), &[7]);
        assert!(scalar.clone().reshape([2]).is_none());
        assert_eq!(square.into_scalar().unwrap(), scalar);
        assert_eq!(scalar.clone().into_scalar().unwrap(), scalar);
        let string = Buf::<str, 0>::from("ab");
        let strings = string.clone().reshape([1]).unwrap();
        assert!(!string.is_unique());
        assert_eq!(strings.into_scalar().unwrap().value(), "ab");
    }

    /// Splitting shares the storage, each side keeping its part.
    #[test]
    fn splitting() {
        let mut buf = Buf::from(&b"headtail"[..]);
        let head = buf.split_to(4);
        assert_eq!((head.as_slice(), buf.as_slice()), (&b"head"[..], &b"tail"[..]));
        let tail = buf.split_off(2);
        assert_eq!((buf.as_slice(), tail.as_slice()), (&b"ta"[..], &b"il"[..]));
        assert!(!head.is_unique());
        let mut rows = Buf::<u8, 2>::from_slice(&[1, 2, 3, 4, 5, 6], [2, 3]).unwrap();
        assert_eq!(rows.split_to(1).as_slice(), &[1, 2]);
        assert_eq!(rows.dim(), [2, 2]);
    }

    #[test]
    #[should_panic(expected = "out of range")]
    fn slice_out_of_range() {
        Buf::<u8, 1>::from(vec![1, 2]).slice(1..3);
    }

    /// A scalar held in place is written in place.
    #[test]
    fn scalar_mutation() {
        let mut scalar = Buf::<i32, 0>::from(1);
        scalar.make_mut().as_mut_slice()[0] = 2;
        assert_eq!(scalar.value(), 2);
        assert_eq!(BufMut::<i32, 0>::zeroed([]).freeze().value(), 0);
    }

    /// A single value is taken out as a scalar: in place for a packed one, sharing the
    /// storage for a string.
    #[test]
    fn scalar_extraction() {
        let values = Buf::<f64, 1>::from(vec![1.5, 2.5]);
        assert_eq!(values.slice(1..).into_scalar().unwrap().value(), 2.5);
        assert!(values.is_unique());
        assert!(values.clone().into_scalar().is_none());
        let strings = Buf::<str, 1>::from(&["ab", "cd"][..]);
        let scalar = strings.slice(1..).into_scalar().unwrap();
        assert_eq!(scalar.value(), "cd");
        assert!(!strings.is_unique());
        assert_eq!(strings.get_scalar([0]).unwrap().value(), "ab");
        assert!(strings.get_scalar([2]).is_none());
        let image = Buf::<u8, 2>::from_slice(&[1, 2, 3, 4, 5, 6], [2, 3]).unwrap();
        assert_eq!(image.get_scalar([1, 2]).unwrap().value(), 6);
        assert_eq!(Buf::<u16, 0>::from(7).get_scalar([]).unwrap().value(), 7);
    }

    /// Writing to a shared buffer first copies it, only its own values and not the whole
    /// storage, so that what shares the storage is never affected.
    #[test]
    fn copy_on_write() {
        let mut values = Buf::<u16, 1>::from(vec![1, 2, 3, 4]);
        let part = values.slice(1..3);
        values.make_mut().as_mut_slice()[1] = 9;
        assert_eq!(values.as_slice(), &[1, 9, 3, 4]);
        assert_eq!(part.as_slice(), &[2, 3]);
        assert!(values.is_unique());
        // A unique buffer is written in place.
        let ptr = values.as_ptr();
        values.make_mut().as_mut_slice()[0] = 0;
        assert_eq!(values.as_ptr(), ptr);
        // And a shared one turned into a writable one only takes its own values.
        let rest = Buf::from(vec![0u16; 64]).slice(1..);
        let part = rest.slice(..2).into_mut();
        assert_ne!(part.as_ptr(), rest.as_ptr());
        assert!(part.capacity() < rest.len());
    }

    /// A shared buffer grows through copy-on-write, what was sharing its storage keeping
    /// the octets it had.
    #[test]
    fn copy_on_write_growth() {
        let mut buf = Buf::from(&b"head"[..]);
        let head = buf.clone();
        buf.make_mut().extend_from_slice(b" tail");
        assert_eq!((buf.as_slice(), head.as_slice()), (&b"head tail"[..], &b"head"[..]));
    }

    /// A buffer of one dimension grows like a `Vec`, whatever its type.
    #[test]
    fn growth() {
        let mut buf = BufMut::<u32, 1>::with_capacity(4);
        buf.extend_from_slice(&[1, 2]);
        buf.resize(5, 0);
        buf.extend_from_slice(&[7; 100]);
        buf.push(8);
        assert_eq!(buf.len(), 106);
        assert_eq!(buf.as_slice()[..6], [1, 2, 0, 0, 0, 7]);
        assert_eq!(buf.as_slice()[105], 8);
        buf.truncate(2);
        assert_eq!(buf.as_slice(), &[1, 2]);
    }

    /// Setting the length of octets grows without zeroing: what the buffer held there
    /// before it shrank is still there, and octets it never held are zeroes.
    #[test]
    fn length() {
        let mut buf = BufMut::from(&[0xAA; 8][..]);
        buf.truncate(4);
        buf.set_len(12);
        assert_eq!(buf.as_slice(), [&[0xAA; 8][..], &[0; 4]].concat());
        buf.truncate(4);
        buf.resize(8, 0);
        assert_eq!(buf.as_slice(), [0xAA, 0xAA, 0xAA, 0xAA, 0, 0, 0, 0]);
    }

    /// Resizing with zeroes zeroes what the buffer held within its capacity, and relies on
    /// what it grows by being zeroed already.
    #[test]
    fn zero_resize() {
        let mut buf = BufMut::from(&[0xAAAAu16; 4][..]);
        buf.clear();
        buf.resize(100, 0);
        assert_eq!(buf.as_slice(), [0; 100]);
        buf.clear();
        buf.resize(2, 0xBBBB);
        buf.resize(3, 0);
        assert_eq!(buf.as_slice(), [0xBBBB, 0xBBBB, 0]);
    }

    /// A reservation that cannot be allocated fails and leaves the buffer as it was.
    #[test]
    fn reservation() {
        let mut buf = BufMut::from(&[1u16, 2][..]);
        assert!(buf.try_reserve(usize::MAX).is_err());
        assert!(buf.try_reserve(isize::MAX as usize).is_err());
        assert_eq!(buf.as_slice(), [1, 2]);
        buf.reserve(64);
        assert!(buf.capacity() >= 66);
    }

    /// Clearing a buffer keeps its storage for the next message, and so does freezing it
    /// once what was shared out of it is gone.
    #[test]
    fn recycling() {
        let mut buf = BufMut::from(&b"first"[..]);
        let ptr = buf.as_ptr();
        buf.clear();
        buf.extend_from_slice(b"second");
        assert_eq!(buf.as_ptr(), ptr);

        let buf = buf.freeze();
        let first = Buf::<str, 0>::from_spans(buf.slice(..3), [0..3], []).unwrap();
        let buf = buf.try_into_mut().unwrap_err();
        drop(first);
        let mut buf = buf.try_into_mut().unwrap();
        buf.clear();
        assert_eq!(buf.as_ptr(), ptr);
    }

    /// A shared buffer only turns back into a writable one, without copying, once nothing
    /// else references its storage.
    #[test]
    fn unique_buffer() {
        let buf = Buf::from(&[1u8, 2, 3][..]);
        let ptr = buf.as_ptr();
        let part = buf.slice(1..);
        let mut buf = buf.try_into_mut().unwrap_err();
        assert!(buf.get_mut().is_none());
        drop(part);
        buf.get_mut().unwrap().truncate(1);
        let buf = buf.try_into_mut().unwrap();
        assert_eq!(buf.as_ptr(), ptr);
        assert_eq!(buf.as_slice(), [1]);
    }

    /// Casting octets to packed values shares the storage when they are aligned for the
    /// type, and copies them otherwise, which is always correct and only slower.
    #[test]
    fn packed_cast() {
        let buf = Buf::<u32, 1>::from(vec![1, 2, 3, 4]).into_bytes();
        let aligned = buf.slice(8..).cast::<u32, 1>([2]).unwrap();
        assert_eq!(aligned.as_slice(), &[3, 4]);
        assert!(!aligned.is_unique());
        let unaligned = buf.slice(1..9).cast::<u32, 1>([2]).unwrap();
        assert!(unaligned.is_unique());
        // The octets must be exactly those of the dimensions, the buffer being given back
        // if they are not.
        let buf = buf.cast::<u32, 1>([3]).unwrap_err();
        // A scalar is always copied in place.
        assert!(buf.slice(..2).cast::<u16, 0>([]).unwrap().is_unique());
        // And any packed type casts to any other.
        let halves = aligned.cast::<u16, 2>([2, 2]).unwrap();
        assert_eq!(halves.cast::<u64, 0>([]).unwrap().value(), 3 | 4 << 32);
    }

    /// A buffer starting where its storage starts is currently aligned for every packed
    /// type, which is not part of the API.
    #[test]
    fn storage_alignment() {
        let buf = Buf::from(&[0u8; 16][..]);
        assert_eq!(buf.as_ptr().addr() % ALIGN, 0);
        assert!(!buf.clone().cast::<f64, 1>([2]).unwrap().is_unique());
    }

    /// Not every octet pattern is a value: a boolean is only 0 or 1.
    #[test]
    fn invalid_values() {
        let buf = Buf::from(&[0u8, 1, 2][..]);
        assert!(buf.slice(..2).cast::<bool, 1>([2]).is_ok());
        assert!(buf.cast::<bool, 1>([3]).is_err());
    }

    /// A buffer gives its octets back, which is what it is encoded from.
    #[test]
    fn octets_round_trip() {
        let values = Buf::<u16, 1>::from(vec![1, 2]);
        assert_eq!(values.as_bytes(), [1u16.to_ne_bytes(), 2u16.to_ne_bytes()].concat());
        let buf = values.into_bytes();
        assert_eq!(buf.cast::<u16, 1>([2]).unwrap().as_slice(), &[1, 2]);
    }

    #[test]
    fn strings() {
        let strings = Buf::<str, 1>::from(&["ab", "", "cde"][..]);
        assert_eq!(strings.get([2]), Some("cde"));
        assert_eq!(strings.iter().collect::<Vec<_>>(), ["ab", "", "cde"]);
        assert_eq!(strings.slice(1..).get([1]), Some("cde"));
        assert_eq!(Buf::<str, 0>::from("scalar").value(), "scalar");
    }

    /// Strings copied out of an iterator, as many as it gives whatever its size hint says,
    /// empty ones and no string at all included.
    #[test]
    fn strings_from_iter() {
        let strings = Buf::<str, 1>::from_strs(["ab", "", "cde"].into_iter().filter(|_| true)).unwrap();
        assert_eq!(strings.dim(), [3]);
        assert_eq!(strings.iter().collect::<Vec<_>>(), ["ab", "", "cde"]);
        let empty = Buf::<str, 1>::from_strs(std::iter::empty::<&str>()).unwrap();
        assert!(empty.is_empty());
    }

    /// Strings decoded from octets are found at the spans the decoder gives, relative to
    /// the octets, and share their storage: they outlive the buffer of octets.
    #[test]
    fn string_spans() {
        let msg = Buf::from(&b"..hello world"[..]);
        let strings = Buf::<str, 1>::from_spans(msg.slice(2..), [0..5, 6..11], [2]).unwrap();
        drop(msg);
        assert_eq!(strings.iter().collect::<Vec<_>>(), ["hello", "world"]);
        // Every span is checked: within the octets, not inverted, and valid UTF-8.
        let buf = Buf::from(&[b'a', 0xff][..]);
        let buf = Buf::<str, 1>::from_spans(buf, [0..3], [1]).unwrap_err();
        let buf = Buf::<str, 1>::from_spans(buf, [1..2], [1]).unwrap_err();
        #[allow(clippy::reversed_empty_ranges)]
        let buf = Buf::<str, 1>::from_spans(buf, [1..0], [1]).unwrap_err();
        assert!(Buf::<str, 0>::from_spans(buf, [0..1], []).is_ok());
    }

    /// A single string takes no table of spans: it shares the storage of its octets, and
    /// an empty one built out of nothing allocates nothing at all.
    #[test]
    fn single_string() {
        let msg = Buf::from(&b"..hello world"[..]);
        let hello = Buf::<str, 0>::from_spans(msg.slice(2..), [0..5], []).unwrap();
        let world = Buf::<str, 1>::from_spans(msg.slice(2..), [6..11], [1]).unwrap();
        drop(msg);
        assert_eq!(hello.value(), "hello");
        assert_eq!(world.iter().collect::<Vec<_>>(), ["world"]);
        assert_eq!(world.get_scalar([0]).unwrap().value(), "world");
        assert!(world.slice(1..).is_empty());
        assert_eq!(world.slice(..1).reshape([1, 1]).unwrap().get([0, 0]), Some("world"));
        assert_eq!(world.into_scalar().unwrap().value(), "world");
        let buf = Buf::from(&b"ab"[..]);
        let buf = Buf::<str, 0>::from_spans(buf, [0..1, 1..2], []).unwrap_err();
        assert!(Buf::<str, 0>::from_spans(buf, [], []).is_err());
        let empty = Buf::<str, 0>::from("");
        assert_eq!(empty.value(), "");
        assert!(!empty.is_unique());
    }

    /// Spans are given as the decoder reads them, and must be exactly as many as the
    /// dimensions say, which nothing is attached to the storage for when they are not.
    #[test]
    fn span_iterator() {
        let msg = Buf::from(&b"a,bc,def"[..]);
        let spans = msg.as_slice().split(|&b| b == b',').scan(0, |start, part| {
            let span = *start..*start + part.len() as u32;
            *start = span.end + 1;
            Some(span)
        }).collect::<Vec<_>>();
        let strings = Buf::<str, 1>::from_spans(msg.clone(), spans.clone(), [3]).unwrap();
        assert_eq!(strings.iter().collect::<Vec<_>>(), ["a", "bc", "def"]);
        let msg = Buf::<str, 1>::from_spans(msg, spans.clone(), [2]).unwrap_err();
        let msg = Buf::<str, 1>::from_spans(msg, spans.clone(), [4]).unwrap_err();
        let msg = Buf::<str, 1>::from_spans(msg, spans.clone(), [usize::MAX]).unwrap_err();
        assert!(Buf::<str, 1>::from_spans(msg, [], [0]).is_ok());
    }

    #[test]
    fn thread_sharing() {
        let values = Buf::<f64, 1>::from(vec![1.0, 2.0]);
        let sum = std::thread::spawn({
            let values = values.clone();
            move || values.iter().sum::<f64>()
        });
        assert_eq!(sum.join().unwrap(), 3.0);
    }

    /// A state is packed like a number, only its known values being valid ones.
    #[test]
    fn states() {
        let buf = Buf::from(&[DevState::Moving as u8, 200][..]);
        let buf = buf.cast::<DevState, 1>([2]).unwrap_err();
        assert_eq!(buf.slice(..1).cast::<DevState, 0>([]).unwrap().value(), DevState::Moving);
    }

    /// Buffers are equal when their dimensions and values are, wherever they are stored.
    #[test]
    fn equality() {
        let values = Buf::<i32, 1>::from([1, 2, 3, 4]);
        assert_eq!(values.slice(2..), Buf::from([3, 4]));
        assert_ne!(values.clone().reshape([2, 2]).unwrap(), Buf::from_slice(&[1, 2, 3, 4], [4, 1]).unwrap());
    }

    /// Only the first values of a buffer are shown.
    #[test]
    fn debug() {
        assert_eq!(format!("{:?}", Buf::<u16, 1>::from([7; 3])), "Buf<3>[7, 7, 7]");
        assert_eq!(format!("{:?}", Buf::<u16, 0>::from(7)), "Buf(7)");
        let rows = Buf::<i32, 2>::from_slice(&[1, 2, 3, 4, 5, 6], [3, 2]).unwrap();
        assert_eq!(format!("{rows:?}"), "Buf<3, 2>[[1, 2, 3], [4, 5, 6]]");
        assert_eq!(format!("{rows:#?}"), "Buf<3, 2>[\n    [1, 2, 3],\n    [4, 5, 6],\n]");
        assert_eq!(format!("{:?}", BufMut::<u8, 2>::zeroed([2, 0])), "BufMut<2, 0>[]");
        assert_eq!(format!("{:?}", Buf::<u8, 2>::new().reshape([0, 2]).unwrap()), "Buf<0, 2>[[], []]");
        assert_eq!(format!("{:?}", Buf::<str, 1>::from(&["a", "b"][..])), r#"Buf<2>["a", "b"]"#);
    }

    /// Octets are shown in hexadecimal, all of them, with runs of readable ASCII quoted.
    #[test]
    fn octets_debug() {
        assert_eq!(format!("{:?}", Buf::from(&b"\x01\x02GIOP\x00"[..])), "Buf<7>[01 02 'GIOP' 00]");
        assert_eq!(format!("{:?}", BufMut::<u8, 1>::from(vec![0xAB; 20])), format!("BufMut<20>[{}AB]", "AB ".repeat(19)));
        let rows = Buf::<u8, 2>::from_slice(b"ab\x01\x02", [2, 2]).unwrap();
        assert_eq!(format!("{rows:?}"), "Buf<2, 2>[['ab'], [01 02]]");
    }

    /// Octets are formatted as plain hexadecimal, which is parsed back, and other packed
    /// values as the groups of their octets.
    #[test]
    fn hex() {
        let buf = Buf::from(&[0x01, 0xAB, 0x00][..]);
        assert_eq!(format!("{buf:X}"), "01AB00");
        assert_eq!(format!("{buf:x}"), "01ab00");
        assert_eq!(format!("{:X}", buf.clone().into_mut()), "01AB00");
        assert_eq!(BufMut::from_hex("01AB00").unwrap().freeze(), buf);
        assert_eq!(BufMut::from_hex("01ab00").unwrap().freeze(), buf);
        assert!(BufMut::from_hex("01A").is_none());
        assert!(BufMut::from_hex("0G").is_none());
        // Larger values are grouped, in the order their octets are stored.
        let words = Buf::<u16, 1>::from([0x0102, 0xABCD]);
        let expected = if cfg!(target_endian = "little") { "0201 cdab" } else { "0102 abcd" };
        assert_eq!(format!("{words:x}"), expected);
        assert_eq!(format!("{:X}", Buf::<u32, 1>::new()), "");
    }

    /// A buffer is a reference to a storage and its dimensions, nothing more: the spans of
    /// a packed type take no room, and a table is one pointer.
    #[test]
    fn sizes() {
        assert_eq!(mem::size_of::<Buf<f64, 0>>(), 16);
        assert_eq!(mem::size_of::<Buf<u8, 1>>(), 24);
        assert_eq!(mem::size_of::<Buf<f64, 2>>(), 32);
        assert_eq!(mem::size_of::<Buf<str, 1>>(), 32);
        assert_eq!(mem::size_of::<BufMut<u8, 1>>(), 24);
    }

}