usearch 2.21.3 → 2.25.0

package/numkong/rust/vector.rs

@@ -0,0 +1,1899 @@
+//! Owning and non-owning vector types with signed indexing and sub-byte support.
+//!
+//! This module provides:
+//!
+//! - [`Vector`]: Owning, non-resizable, SIMD-aligned vector
+//! - [`VectorView`]: Immutable, strided, non-owning view
+//! - [`VectorSpan`]: Mutable, strided, non-owning view
+//! - [`VectorIndex`]: Signed indexing trait (negative indices wrap from end)
+//!
+//! All types use [`StorageElement`] as their element bound, with sub-byte types
+//! (i4x2, u4x2, u1x8) supported via `try_get`/`try_set` and iterators.
+//!
+//! # Signed (Python-style) indexing
+//!
+//! Negative indices count from the end, mirroring Python's `list[-1]` idiom:
+//!
+//! ```ignore
+//! use numkong::vector::Vector;
+//! let v = Vector::<f32>::try_from_dims(&[10.0, 20.0, 30.0, 40.0, 50.0]).unwrap();
+//! // Last element via negative index.
+//! assert_eq!(v.try_get(-1_i32).unwrap(), 50.0);
+//! // Second-to-last.
+//! assert_eq!(v.try_get(-2_i32).unwrap(), 40.0);
+//! // Out-of-range negatives return an error rather than panic.
+//! assert!(v.try_get(-6_i32).is_err());
+//! ```
+//!
+//! # Sub-byte element iteration
+//!
+//! For packed types such as `i4x2`, `u4x2`, and `u1x8`, iteration yields one
+//! logical dimension per step (not one packed storage value):
+//!
+//! ```ignore
+//! use numkong::vector::Vector;
+//! use numkong::types::u1x8;
+//! let mut v = Vector::<u1x8>::try_zeros(8).unwrap();
+//! for (i, mut bit) in v.iter_mut().enumerate() {
+//!     *bit = if i % 2 == 0 { 1 } else { 0 };
+//! }
+//! assert_eq!(v.try_get(0_usize).unwrap(), 1);
+//! assert_eq!(v.try_get(1_usize).unwrap(), 0);
+//! ```
+
+extern crate alloc;
+
+use core::marker::PhantomData;
+use core::ptr::NonNull;
+
+use crate::tensor::{Allocator, Global, Tensor, TensorError, SIMD_ALIGNMENT};
+use crate::types::{DimMut, DimRef, FloatConvertible, NumberLike, StorageElement};
+
+// region: VectorIndex — Signed Indexing
+
+mod private {
+    pub trait Sealed {}
+}
+
+/// Trait for vector index types. Supports signed integers (negative = from end).
+pub trait VectorIndex: private::Sealed + Copy {
+    /// Resolve this index to a `usize` offset, or `None` if out of bounds.
+    fn resolve(self, len: usize) -> Option<usize>;
+}
+
+macro_rules! impl_vec_index_unsigned {
+    ($($t:ty),*) => {$(
+        impl private::Sealed for $t {}
+        impl VectorIndex for $t {
+            #[inline]
+            fn resolve(self, len: usize) -> Option<usize> {
+                let index = self as usize;
+                if index < len { Some(index) } else { None }
+            }
+        }
+    )*};
+}
+
+macro_rules! impl_vec_index_signed {
+    ($($t:ty),*) => {$(
+        impl private::Sealed for $t {}
+        impl VectorIndex for $t {
+            #[inline]
+            fn resolve(self, len: usize) -> Option<usize> {
+                let index = if self >= 0 {
+                    self as usize
+                } else {
+                    let neg = (-(self as isize)) as usize;
+                    if neg > len { return None; }
+                    len - neg
+                };
+                if index < len { Some(index) } else { None }
+            }
+        }
+    )*};
+}
+
+impl_vec_index_unsigned!(usize, u8, u16, u32, u64);
+impl_vec_index_signed!(isize, i8, i16, i32, i64);
+
+// endregion: VectorIndex
+
+// region: Sub-byte Proxy Types
+
+/// Immutable reference to a nibble (4-bit value) within a packed byte.
+///
+/// Obtained by iterating over or indexing into a `Vector<i4x2>` / `Vector<u4x2>`;
+/// the proxy remembers whether it refers to the low or high nibble of the shared
+/// byte and decodes accordingly. Prefer [`NibbleRef::get_unsigned`] for `u4x2`
+/// storage and [`NibbleRef::get_signed`] for `i4x2` storage (the latter
+/// sign-extends bit 3 so the return range is `-8..=7`).
+///
+/// # Example
+///
+/// ```ignore
+/// use numkong::vector::Vector;
+/// use numkong::types::i4x2;
+/// let mut v = Vector::<i4x2>::try_zeros(2).unwrap();
+/// v.try_set(0_usize, -3).unwrap();
+/// // Reading via `try_get` returns the same signed value NibbleRef::get_signed yields.
+/// assert_eq!(v.try_get(0_usize).unwrap(), -3);
+/// ```
+pub struct NibbleRef<'a> {
+    byte: *const u8,
+    high: bool,
+    _marker: PhantomData<&'a u8>,
+}
+
+impl<'a> NibbleRef<'a> {
+    /// Read the nibble value as u8 (0..16).
+    #[inline]
+    pub fn get_unsigned(&self) -> u8 {
+        // SAFETY: byte pointer is valid for the lifetime 'a
+        let byte_value = unsafe { *self.byte };
+        if self.high {
+            byte_value >> 4
+        } else {
+            byte_value & 0x0F
+        }
+    }
+
+    /// Read the nibble value as i8 (-8..7), sign-extending bit 3.
+    #[inline]
+    pub fn get_signed(&self) -> i8 {
+        let nibble = self.get_unsigned();
+        if nibble & 0x08 != 0 {
+            nibble as i8 | !0x0Fi8
+        } else {
+            nibble as i8
+        }
+    }
+}
+
+/// Mutable reference to a nibble (4-bit value) within a packed byte.
+///
+/// Obtained via mutable iteration / indexing of a `Vector<i4x2>` or
+/// `Vector<u4x2>`. Writes perform a read-modify-write on the shared byte so the
+/// sibling nibble is preserved. Pair `get_unsigned` / `set_unsigned` for
+/// unsigned storage and `get_signed` / `set_signed` for signed storage.
+///
+/// # Example
+///
+/// ```ignore
+/// use numkong::vector::Vector;
+/// use numkong::types::u4x2;
+/// let mut v = Vector::<u4x2>::try_zeros(4).unwrap();
+/// for (i, mut nibble) in v.iter_mut().enumerate() {
+///     *nibble = i as u8;
+/// }
+/// assert_eq!(v.try_get(3_usize).unwrap(), 3);
+/// ```
+pub struct NibbleRefMut<'a> {
+    byte: *mut u8,
+    high: bool,
+    _marker: PhantomData<&'a mut u8>,
+}
+
+impl<'a> NibbleRefMut<'a> {
+    /// Read the nibble value as u8.
+    #[inline]
+    pub fn get_unsigned(&self) -> u8 {
+        let byte_value = unsafe { *self.byte };
+        if self.high {
+            byte_value >> 4
+        } else {
+            byte_value & 0x0F
+        }
+    }
+
+    /// Read the nibble value as i8, sign-extending bit 3.
+    #[inline]
+    pub fn get_signed(&self) -> i8 {
+        let nibble = self.get_unsigned();
+        if nibble & 0x08 != 0 {
+            nibble as i8 | !0x0Fi8
+        } else {
+            nibble as i8
+        }
+    }
+
+    /// Set the nibble to an unsigned value (low 4 bits used).
+    #[inline]
+    pub fn set_unsigned(&self, value: u8) {
+        // SAFETY: byte pointer is valid and mutable for the lifetime 'a
+        unsafe {
+            let byte_value = *self.byte;
+            if self.high {
+                *self.byte = (byte_value & 0x0F) | ((value & 0x0F) << 4);
+            } else {
+                *self.byte = (byte_value & 0xF0) | (value & 0x0F);
+            }
+        }
+    }
+
+    /// Set the nibble to a signed value (low 4 bits used).
+    #[inline]
+    pub fn set_signed(&self, value: i8) {
+        self.set_unsigned(value as u8);
+    }
+}
+
+/// Immutable reference to a single bit within a packed byte.
+///
+/// Obtained by iterating over or indexing into a `Vector<u1x8>`. The `mask`
+/// selects which of the eight bits the proxy represents; the byte itself is
+/// shared with the seven sibling proxies for the same byte.
+///
+/// # Example
+///
+/// ```ignore
+/// use numkong::vector::Vector;
+/// use numkong::types::u1x8;
+/// let mut v = Vector::<u1x8>::try_zeros(8).unwrap();
+/// v.try_set(3_usize, 1).unwrap();
+/// // Immutable iteration yields BitRef-like proxies that deref to the bit value.
+/// let bits: Vec<u8> = v.iter().map(|b| *b).collect();
+/// assert_eq!(bits, vec![0, 0, 0, 1, 0, 0, 0, 0]);
+/// ```
+pub struct BitRef<'a> {
+    byte: *const u8,
+    mask: u8,
+    _marker: PhantomData<&'a u8>,
+}
+
+impl<'a> BitRef<'a> {
+    /// Read the bit as bool.
+    #[inline]
+    pub fn get(&self) -> bool {
+        // SAFETY: byte pointer is valid for the lifetime 'a
+        (unsafe { *self.byte } & self.mask) != 0
+    }
+}
+
+/// Mutable reference to a single bit within a packed byte.
+///
+/// Obtained via mutable iteration / indexing of a `Vector<u1x8>`. Writes OR or
+/// AND the stored byte so sibling bits are preserved; the `mask` selects which
+/// bit this proxy represents.
+///
+/// # Example
+///
+/// ```ignore
+/// use numkong::vector::Vector;
+/// use numkong::types::u1x8;
+/// let mut v = Vector::<u1x8>::try_zeros(8).unwrap();
+/// for (i, mut bit) in v.iter_mut().enumerate() {
+///     *bit = (i % 2 == 0) as u8;
+/// }
+/// assert_eq!(v.try_get(0_usize).unwrap(), 1);
+/// assert_eq!(v.try_get(1_usize).unwrap(), 0);
+/// ```
+pub struct BitRefMut<'a> {
+    byte: *mut u8,
+    mask: u8,
+    _marker: PhantomData<&'a mut u8>,
+}
+
+impl<'a> BitRefMut<'a> {
+    /// Read the bit as bool.
+    #[inline]
+    pub fn get(&self) -> bool {
+        // SAFETY: byte pointer is valid for the lifetime 'a
+        (unsafe { *self.byte } & self.mask) != 0
+    }
+
+    /// Set the bit.
+    #[inline]
+    pub fn set(&self, value: bool) {
+        // SAFETY: byte pointer is valid and mutable for the lifetime 'a
+        unsafe {
+            if value {
+                *self.byte |= self.mask;
+            } else {
+                *self.byte &= !self.mask;
+            }
+        }
+    }
+}
+
+// endregion: Sub-byte Proxy Types
+
+// region: Vector
+
+/// Owning, non-resizable, SIMD-aligned vector.
+///
+/// Size is fixed at construction. Uses [`StorageElement`] for element types,
+/// including sub-byte packed types via `Scalar::dimensions_per_value()`.
+///
+/// For normal types (`dimensions_per_value() == 1`), supports `Index`/`IndexMut`.
+/// For sub-byte types, use `try_get`/`try_set` or iterators.
+pub struct Vector<Scalar: StorageElement, Alloc: Allocator = Global> {
+    /// Pointer to the allocated buffer (typed as `Scalar` for alignment).
+    data: NonNull<Scalar>,
+    /// Number of logical dimensions.
+    dims: usize,
+    /// Number of storage values (dims / dimensions_per_value, rounded up).
+    values: usize,
+    /// Allocator instance.
+    alloc: Alloc,
+}
+
+unsafe impl<Scalar: StorageElement + Send, Alloc: Allocator + Send> Send for Vector<Scalar, Alloc> {}
+unsafe impl<Scalar: StorageElement + Sync, Alloc: Allocator + Sync> Sync for Vector<Scalar, Alloc> {}
+
+impl<Scalar: StorageElement, Alloc: Allocator> Drop for Vector<Scalar, Alloc> {
+    fn drop(&mut self) {
+        if self.values > 0 {
+            let layout = alloc::alloc::Layout::from_size_align(
+                self.values * core::mem::size_of::<Scalar>(),
+                SIMD_ALIGNMENT,
+            )
+            .unwrap();
+            // SAFETY: data was allocated with this layout in try_zeros_in,
+            // and values > 0 guarantees the pointer is non-dangling.
+            unsafe {
+                self.alloc.deallocate(
+                    NonNull::new_unchecked(self.data.as_ptr() as *mut u8),
+                    layout,
+                );
+            }
+        }
+    }
+}
+
+/// Convert dimension count to value count for `Scalar`.
+///
+/// For sub-byte types where `dimensions_per_value() > 1`, this is a ceiling
+/// division via [`usize::div_ceil`].
+#[inline]
+fn dims_to_values<Scalar: StorageElement>(dims: usize) -> usize {
+    dims.div_ceil(Scalar::dimensions_per_value())
+}
+
+impl<Scalar: StorageElement, Alloc: Allocator> Vector<Scalar, Alloc> {
+    /// Construct a vector from raw parts, taking ownership of the allocation.
+    ///
+    /// # Safety
+    /// - `data` must point to a valid allocation of `values * size_of::<Scalar>()` bytes
+    ///   obtained from `alloc`, aligned to [`SIMD_ALIGNMENT`].
+    /// - `dims` and `values` must be consistent (`values == ceil(dims / dimensions_per_value())`).
+    /// - The caller must not free the memory (this vector takes ownership).
+    pub unsafe fn from_raw_parts(
+        data: NonNull<Scalar>,
+        dims: usize,
+        values: usize,
+        alloc: Alloc,
+    ) -> Self {
+        Self {
+            data,
+            dims,
+            values,
+            alloc,
+        }
+    }
+
+    /// Try to create a zero-initialized vector with the given number of dimensions.
+    pub fn try_zeros_in(dims: usize, alloc: Alloc) -> Result<Self, TensorError> {
+        let values = dims_to_values::<Scalar>(dims);
+        if values == 0 {
+            return Ok(Self {
+                data: NonNull::dangling(),
+                dims: 0,
+                values: 0,
+                alloc,
+            });
+        }
+        let size = values * core::mem::size_of::<Scalar>();
+        let layout = alloc::alloc::Layout::from_size_align(size, SIMD_ALIGNMENT)
+            .map_err(|_| TensorError::AllocationFailed)?;
+        let ptr = alloc
+            .allocate(layout)
+            .ok_or(TensorError::AllocationFailed)?;
+        unsafe { core::ptr::write_bytes(ptr.as_ptr(), 0, size) };
+        Ok(Self {
+            data: unsafe { NonNull::new_unchecked(ptr.as_ptr() as *mut Scalar) },
+            dims,
+            values,
+            alloc,
+        })
+    }
+
+    /// Try to create a vector filled with `value`.
+    pub fn try_full_in(dims: usize, value: Scalar, alloc: Alloc) -> Result<Self, TensorError> {
+        let v = Self::try_zeros_in(dims, alloc)?;
+        if v.values > 0 {
+            let ptr = v.data.as_ptr();
+            for i in 0..v.values {
+                unsafe { ptr.add(i).write(value) };
+            }
+        }
+        Ok(v)
+    }
+
+    /// Try to create a vector filled with ones.
+    pub fn try_ones_in(dims: usize, alloc: Alloc) -> Result<Self, TensorError>
+    where
+        Scalar: NumberLike,
+    {
+        Self::try_full_in(dims, Scalar::one(), alloc)
+    }
+
+    /// Try to create an uninitialized vector.
+    ///
+    /// # Safety
+    /// The returned vector's contents are uninitialized. Reading from it before
+    /// writing is undefined behavior.
+    pub unsafe fn try_empty_in(dims: usize, alloc: Alloc) -> Result<Self, TensorError> {
+        let values = dims_to_values::<Scalar>(dims);
+        if values == 0 {
+            return Ok(Self {
+                data: NonNull::dangling(),
+                dims: 0,
+                values: 0,
+                alloc,
+            });
+        }
+        let size = values * core::mem::size_of::<Scalar>();
+        let layout = alloc::alloc::Layout::from_size_align(size, SIMD_ALIGNMENT)
+            .map_err(|_| TensorError::AllocationFailed)?;
+        let ptr = alloc
+            .allocate(layout)
+            .ok_or(TensorError::AllocationFailed)?;
+        Ok(Self {
+            data: unsafe { NonNull::new_unchecked(ptr.as_ptr() as *mut Scalar) },
+            dims,
+            values,
+            alloc,
+        })
+    }
+
+    /// Try to create a vector from a slice of scalars (f32 values).
+    ///
+    /// Each f32 value is converted through `DimScalar::from_f32()` before storage.
+    pub fn try_from_scalars_in(scalars: &[f32], alloc: Alloc) -> Result<Self, TensorError>
+    where
+        Scalar: FloatConvertible,
+    {
+        let element_count = scalars.len();
+        let mut v = Self::try_zeros_in(element_count, alloc)?;
+        for (i, &s) in scalars.iter().enumerate() {
+            v.try_set(i, Scalar::DimScalar::from_f32(s))?;
+        }
+        Ok(v)
+    }
+
+    /// Try to create a vector from a slice of per-dimension scalars.
+    ///
+    /// Each element in `dim_values` corresponds to one logical dimension.
+    pub fn try_from_dims_in(
+        dim_values: &[Scalar::DimScalar],
+        alloc: Alloc,
+    ) -> Result<Self, TensorError>
+    where
+        Scalar: FloatConvertible,
+    {
+        let element_count = dim_values.len();
+        let mut v = Self::try_zeros_in(element_count, alloc)?;
+        for (i, &d) in dim_values.iter().enumerate() {
+            v.try_set(i, d)?;
+        }
+        Ok(v)
+    }
+
+    /// Number of logical dimensions.
+    #[inline]
+    pub fn dims(&self) -> usize {
+        self.dims
+    }
+
+    /// Number of logical dimensions (same as `dims()`).
+    #[inline]
+    pub fn size(&self) -> usize {
+        self.dims
+    }
+
+    /// Number of underlying storage values (`Scalar` instances).
+    #[inline]
+    pub fn size_values(&self) -> usize {
+        self.values
+    }
+
+    /// Returns true if the vector has zero dimensions.
+    #[inline]
+    pub fn is_empty(&self) -> bool {
+        self.dims == 0
+    }
+
+    /// Raw pointer to the underlying data.
+    #[inline]
+    pub fn as_ptr(&self) -> *const Scalar {
+        self.data.as_ptr()
+    }
+
+    /// Mutable raw pointer to the underlying data.
+    #[inline]
+    pub fn as_mut_ptr(&mut self) -> *mut Scalar {
+        self.data.as_ptr()
+    }
+
+    /// Size in bytes.
+    #[inline]
+    pub fn size_bytes(&self) -> usize {
+        self.values * core::mem::size_of::<Scalar>()
+    }
+
+    /// Create an immutable view of this vector.
+    #[inline]
+    pub fn view(&self) -> VectorView<'_, Scalar> {
+        VectorView {
+            data: self.data.as_ptr() as *const Scalar,
+            dims: self.dims,
+            stride_bytes: core::mem::size_of::<Scalar>() as isize,
+            _marker: PhantomData,
+        }
+    }
+
+    /// Create a mutable span of this vector.
+    #[inline]
+    pub fn span(&mut self) -> VectorSpan<'_, Scalar> {
+        VectorSpan {
+            data: self.data.as_ptr(),
+            dims: self.dims,
+            stride_bytes: core::mem::size_of::<Scalar>() as isize,
+            _marker: PhantomData,
+        }
+    }
+
+    /// Try to get the logical dimension at `index` (supports signed indexing).
+    ///
+    /// Returns the native `DimScalar` type (e.g., `f64` for `Vector<f64>`, `i8` for `Vector<i4x2>`).
+    /// For sub-byte types, unpacks the appropriate sub-dimension from the packed storage value.
+    ///
+    /// # Examples
+    ///
+    /// Positive and Python-style negative indexing:
+    ///
+    /// ```ignore
+    /// use numkong::vector::Vector;
+    /// let v = Vector::<f32>::try_from_dims(&[10.0, 20.0, 30.0, 40.0, 50.0]).unwrap();
+    /// assert_eq!(v.try_get(0_usize).unwrap(), 10.0);
+    /// assert_eq!(v.try_get(-1_i32).unwrap(), 50.0);
+    /// assert_eq!(v.try_get(-5_i32).unwrap(), 10.0);
+    /// // Out-of-range indices return an error instead of panicking.
+    /// assert!(v.try_get(5_usize).is_err());
+    /// assert!(v.try_get(-6_i32).is_err());
+    /// ```
+    #[inline]
+    pub fn try_get<AnyIndex: VectorIndex>(
+        &self,
+        index: AnyIndex,
+    ) -> Result<Scalar::DimScalar, TensorError>
+    where
+        Scalar: FloatConvertible,
+    {
+        let i = index
+            .resolve(self.dims)
+            .ok_or(TensorError::IndexOutOfBounds {
+                index: 0,
+                size: self.dims,
+            })?;
+        let dims_per_value = Scalar::dimensions_per_value();
+        let value_index = i / dims_per_value;
+        let sub_index = i % dims_per_value;
+        // SAFETY: value_index < self.values, guaranteed by dims/values invariant
+        let packed = unsafe { *self.data.as_ptr().add(value_index) };
+        Ok(packed.unpack().as_ref()[sub_index])
+    }
+
+    /// Try to set the logical dimension at `index`.
+    ///
+    /// Accepts the native `DimScalar` type. For sub-byte types, reads the current packed value,
+    /// updates the targeted sub-dimension, and writes back the modified packed value.
+    ///
+    /// # Examples
+    ///
+    /// ```ignore
+    /// use numkong::vector::Vector;
+    /// let mut v = Vector::<f32>::try_zeros(4).unwrap();
+    /// v.try_set(0_usize, 1.0).unwrap();
+    /// // Signed indices let you write to the tail without computing the length.
+    /// v.try_set(-1_i32, 4.0).unwrap();
+    /// assert_eq!(v.try_get(0_usize).unwrap(), 1.0);
+    /// assert_eq!(v.try_get(3_usize).unwrap(), 4.0);
+    /// ```
+    #[inline]
+    pub fn try_set<AnyIndex: VectorIndex>(
+        &mut self,
+        index: AnyIndex,
+        value: Scalar::DimScalar,
+    ) -> Result<(), TensorError>
+    where
+        Scalar: FloatConvertible,
+    {
+        let i = index
+            .resolve(self.dims)
+            .ok_or(TensorError::IndexOutOfBounds {
+                index: 0,
+                size: self.dims,
+            })?;
+        let dims_per_value = Scalar::dimensions_per_value();
+        let value_index = i / dims_per_value;
+        let sub_index = i % dims_per_value;
+        // SAFETY: value_index < self.values, guaranteed by dims/values invariant
+        let ptr = unsafe { self.data.as_ptr().add(value_index) };
+        let mut unpacked = unsafe { *ptr }.unpack();
+        unpacked.as_mut()[sub_index] = value;
+        unsafe { ptr.write(Scalar::pack(unpacked)) };
+        Ok(())
+    }
+
+    /// Get a slice of the underlying storage values (only for normal types).
+    #[inline]
+    pub fn as_slice(&self) -> &[Scalar] {
+        if Scalar::dimensions_per_value() == 1 {
+            unsafe { core::slice::from_raw_parts(self.data.as_ptr(), self.values) }
+        } else {
+            // For sub-byte types, return the packed values
+            unsafe { core::slice::from_raw_parts(self.data.as_ptr(), self.values) }
+        }
+    }
+
+    /// Get a mutable slice of the underlying storage values.
+    #[inline]
+    pub fn as_mut_slice(&mut self) -> &mut [Scalar] {
+        unsafe { core::slice::from_raw_parts_mut(self.data.as_ptr(), self.values) }
+    }
+
+    /// Returns an iterator over the logical dimension values, yielding [`DimRef`] proxies.
+    pub fn iter(&self) -> VectorViewIterator<'_, Scalar>
+    where
+        Scalar: FloatConvertible,
+    {
+        self.view().iter()
+    }
+
+    /// Returns a mutable iterator over the logical dimension values, yielding [`DimMut`] proxies.
+    pub fn iter_mut(&mut self) -> VectorSpanIterator<'_, Scalar>
+    where
+        Scalar: FloatConvertible,
+    {
+        VectorSpanIterator {
+            data: self.data.as_ptr(),
+            stride_bytes: core::mem::size_of::<Scalar>() as isize,
+            front: 0,
+            back: self.dims,
+            _marker: PhantomData,
+        }
+    }
+}
+
+impl<Scalar: StorageElement, Alloc: Allocator> Vector<Scalar, Alloc> {
+    /// Convert this vector into a 1D tensor, transferring ownership without copying.
+    pub fn try_into_tensor<const MAX_RANK: usize>(
+        self,
+    ) -> Result<Tensor<Scalar, Alloc, MAX_RANK>, TensorError> {
+        if MAX_RANK == 0 {
+            return Err(TensorError::TooManyRanks { got: 1 });
+        }
+        let mut shape = [0usize; MAX_RANK];
+        shape[0] = self.dims;
+        let mut strides = [0isize; MAX_RANK];
+        strides[0] = core::mem::size_of::<Scalar>() as isize;
+        let alloc_bytes = self.values * core::mem::size_of::<Scalar>();
+        let data = self.data;
+        // SAFETY: we read the allocator out before forget, transferring ownership
+        let alloc = unsafe { core::ptr::read(&self.alloc) };
+        core::mem::forget(self);
+        // SAFETY: data/alloc_bytes match the original allocation
+        let tensor = unsafe { Tensor::from_raw_parts(data, alloc_bytes, shape, strides, 1, alloc) };
+        Ok(tensor)
+    }
+}
+
+impl<Scalar: StorageElement> Vector<Scalar, Global> {
+    /// Create a zero-initialized vector with the global allocator.
+    pub fn try_zeros(dims: usize) -> Result<Self, TensorError> {
+        Self::try_zeros_in(dims, Global)
+    }
+
+    /// Create a vector filled with `value`.
+    pub fn try_full(dims: usize, value: Scalar) -> Result<Self, TensorError> {
+        Self::try_full_in(dims, value, Global)
+    }
+
+    /// Create a vector filled with ones.
+    pub fn try_ones(dims: usize) -> Result<Self, TensorError>
+    where
+        Scalar: NumberLike,
+    {
+        Self::try_full(dims, Scalar::one())
+    }
+
+    /// Create an uninitialized vector.
+    ///
+    /// # Safety
+    /// The returned vector's contents are uninitialized. Reading from it before
+    /// writing is undefined behavior.
+    pub unsafe fn try_empty(dims: usize) -> Result<Self, TensorError> {
+        unsafe { Self::try_empty_in(dims, Global) }
+    }
+
+    /// Create a vector from scalar f32 values.
+    pub fn try_from_scalars(scalars: &[f32]) -> Result<Self, TensorError>
+    where
+        Scalar: FloatConvertible,
+    {
+        Self::try_from_scalars_in(scalars, Global)
+    }
+
+    /// Create a vector from per-dimension scalars.
+    pub fn try_from_dims(dims: &[Scalar::DimScalar]) -> Result<Self, TensorError>
+    where
+        Scalar: FloatConvertible,
+    {
+        Self::try_from_dims_in(dims, Global)
+    }
+}
+
+// Index for normal types (dimensions_per_value == 1)
+impl<AnyIndex: VectorIndex, Scalar: StorageElement, Alloc: Allocator> core::ops::Index<AnyIndex>
+    for Vector<Scalar, Alloc>
+{
+    type Output = Scalar;
+
+    #[inline]
+    fn index(&self, index: AnyIndex) -> &Scalar {
+        let i = index
+            .resolve(self.dims)
+            .expect("vector index out of bounds");
+        debug_assert_eq!(
+            Scalar::dimensions_per_value(),
+            1,
+            "Index trait not supported for sub-byte types"
+        );
+        unsafe { &*self.data.as_ptr().add(i) }
+    }
+}
+
+impl<AnyIndex: VectorIndex, Scalar: StorageElement, Alloc: Allocator> core::ops::IndexMut<AnyIndex>
+    for Vector<Scalar, Alloc>
+{
+    #[inline]
+    fn index_mut(&mut self, index: AnyIndex) -> &mut Scalar {
+        let i = index
+            .resolve(self.dims)
+            .expect("vector index out of bounds");
+        debug_assert_eq!(
+            Scalar::dimensions_per_value(),
+            1,
+            "IndexMut trait not supported for sub-byte types"
+        );
+        unsafe { &mut *self.data.as_ptr().add(i) }
+    }
+}
+
+impl<Scalar: StorageElement + Clone, Alloc: Allocator + Clone> Vector<Scalar, Alloc> {
+    /// Try to clone this vector, returning an error on allocation failure.
+    pub fn try_clone(&self) -> Result<Self, TensorError> {
+        if self.values == 0 {
+            return Ok(Self {
+                data: NonNull::dangling(),
+                dims: 0,
+                values: 0,
+                alloc: self.alloc.clone(),
+            });
+        }
+        let size = self.values * core::mem::size_of::<Scalar>();
+        let layout = alloc::alloc::Layout::from_size_align(size, SIMD_ALIGNMENT)
+            .map_err(|_| TensorError::AllocationFailed)?;
+        let ptr = self
+            .alloc
+            .allocate(layout)
+            .ok_or(TensorError::AllocationFailed)?;
+        unsafe {
+            core::ptr::copy_nonoverlapping(self.data.as_ptr() as *const u8, ptr.as_ptr(), size);
+        }
+        Ok(Self {
+            data: unsafe { NonNull::new_unchecked(ptr.as_ptr() as *mut Scalar) },
+            dims: self.dims,
+            values: self.values,
+            alloc: self.alloc.clone(),
+        })
+    }
+}
+
+impl<Scalar: StorageElement + Clone, Alloc: Allocator + Clone> Clone for Vector<Scalar, Alloc> {
+    fn clone(&self) -> Self {
+        self.try_clone().expect("vector clone allocation failed")
+    }
+}
+
+impl<Scalar: StorageElement> Default for Vector<Scalar, Global> {
+    fn default() -> Self {
+        Self {
+            data: NonNull::dangling(),
+            dims: 0,
+            values: 0,
+            alloc: Global,
+        }
+    }
+}
+
+// endregion: Vector
+
+// region: VectorView
+
+/// Immutable, possibly strided, non-owning view into a vector.
+///
+/// `VectorView` is a zero-copy borrow: it holds a raw pointer, a dimension
+/// count, and a byte stride between consecutive logical elements. It never
+/// frees its memory and is tied to the lifetime `'a` of whatever owns the
+/// storage (typically a [`Vector`] obtained via [`Vector::view`], or a row /
+/// column of a tensor).
+///
+/// Because the stride is stored in bytes and may be negative, views can walk
+/// memory in either direction, skip entries (see [`VectorView::try_strided`]),
+/// or expose a reversed iteration order (see [`VectorView::rev`]).
+///
+/// Use [`VectorView`] when only read access is needed. Its mutable counterpart
+/// is [`VectorSpan`], which offers the same striding semantics plus element
+/// writes. Both types support the [`VectorIndex`] trait, so `view[0_usize]`,
+/// `view[-1_i32]`, and friends all resolve via the same Python-style rules.
+pub struct VectorView<'a, Scalar: StorageElement> {
+    data: *const Scalar,
+    dims: usize,
+    stride_bytes: isize,
+    _marker: PhantomData<&'a Scalar>,
+}
+
+unsafe impl<'a, Scalar: StorageElement + Sync> Send for VectorView<'a, Scalar> {}
+unsafe impl<'a, Scalar: StorageElement + Sync> Sync for VectorView<'a, Scalar> {}
+
+impl<'a, Scalar: StorageElement> Clone for VectorView<'a, Scalar> {
+    fn clone(&self) -> Self {
+        *self
+    }
+}
+impl<'a, Scalar: StorageElement> Copy for VectorView<'a, Scalar> {}
+
+impl<'a, Scalar: StorageElement> VectorView<'a, Scalar> {
+    /// Create a view from a raw pointer, dimension count, and byte stride.
+    ///
+    /// # Safety
+    /// - `data` must be valid for reads of `dims` elements at the given stride.
+    /// - The pointed-to memory must outlive `'a`.
+    /// - `stride_bytes` must be non-zero for non-empty views.
+    #[inline]
+    pub unsafe fn from_raw_parts(data: *const Scalar, dims: usize, stride_bytes: isize) -> Self {
+        Self {
+            data,
+            dims,
+            stride_bytes,
+            _marker: PhantomData,
+        }
+    }
+
+    /// Number of logical dimensions.
+    #[inline]
+    pub fn dims(&self) -> usize {
+        self.dims
+    }
+
+    /// Number of logical dimensions (alias for dims).
+    #[inline]
+    pub fn size(&self) -> usize {
+        self.dims
+    }
+
+    /// Returns true if empty.
+    #[inline]
+    pub fn is_empty(&self) -> bool {
+        self.dims == 0
+    }
+
+    /// Stride in bytes between consecutive elements.
+    #[inline]
+    pub fn stride_bytes(&self) -> isize {
+        self.stride_bytes
+    }
+
+    /// Returns true if elements are stored contiguously (stride == sizeof(Scalar)).
+    #[inline]
+    pub fn is_contiguous(&self) -> bool {
+        self.stride_bytes == core::mem::size_of::<Scalar>() as isize
+    }
+
+    /// Get the underlying pointer.
+    #[inline]
+    pub fn as_ptr(&self) -> *const Scalar {
+        self.data
+    }
+
+    /// Get a contiguous slice, if this view is contiguous.
+    #[inline]
+    pub fn as_contiguous_slice(&self) -> Option<&'a [Scalar]> {
+        if self.is_contiguous() && Scalar::dimensions_per_value() == 1 {
+            Some(unsafe { core::slice::from_raw_parts(self.data, self.dims) })
+        } else {
+            None
+        }
+    }
+
+    /// Try to get element at index (supports signed indexing).
+    ///
+    /// Returns the native `DimScalar` type. For sub-byte types, uses value_index
+    /// for stride-based pointer walks to avoid buffer overread.
+    #[inline]
+    pub fn try_get<AnyIndex: VectorIndex>(
+        &self,
+        index: AnyIndex,
+    ) -> Result<Scalar::DimScalar, TensorError>
+    where
+        Scalar: FloatConvertible,
+    {
+        let i = index
+            .resolve(self.dims)
+            .ok_or(TensorError::IndexOutOfBounds {
+                index: 0,
+                size: self.dims,
+            })?;
+        let dims_per_value = Scalar::dimensions_per_value();
+        let value_index = i / dims_per_value;
+        let sub_index = i % dims_per_value;
+        // SAFETY: stride * value_index stays within allocation
+        let ptr = unsafe {
+            (self.data as *const u8).offset(self.stride_bytes * value_index as isize)
+                as *const Scalar
+        };
+        Ok(unsafe { *ptr }.unpack().as_ref()[sub_index])
+    }
+
+    /// Create a reversed view by negating the stride and pointing to the last element.
+    ///
+    /// The returned view has the same number of dimensions but iterates in the
+    /// opposite direction. For an empty view, returns a copy unchanged.
+    pub fn rev(&self) -> Self {
+        if self.dims == 0 {
+            return *self;
+        }
+        let last_offset = self.stride_bytes * (self.dims as isize - 1);
+        Self {
+            data: unsafe { (self.data as *const u8).offset(last_offset) as *const Scalar },
+            dims: self.dims,
+            stride_bytes: -self.stride_bytes,
+            _marker: PhantomData,
+        }
+    }
+
+    /// Create a sub-view with start, end, and step (Python-style slicing).
+    ///
+    /// Supports negative steps for reverse iteration. `step` must be non-zero.
+    /// Returns an error if `start` or `end` exceed `dims()`, or if `step == 0`.
+    pub fn try_strided(&self, start: usize, end: usize, step: isize) -> Result<Self, TensorError> {
+        if start > self.dims || end > self.dims || step == 0 {
+            return Err(TensorError::IndexOutOfBounds {
+                index: start.max(end),
+                size: self.dims,
+            });
+        }
+        let count = if step > 0 {
+            if end > start {
+                (end - start + step as usize - 1) / step as usize
+            } else {
+                0
+            }
+        } else if start > end {
+            let abs_step = (-step) as usize;
+            (start - end + abs_step - 1) / abs_step
+        } else {
+            0
+        };
+        let new_data = unsafe {
+            (self.data as *const u8).offset(self.stride_bytes * start as isize) as *const Scalar
+        };
+        Ok(Self {
+            data: new_data,
+            dims: count,
+            stride_bytes: self.stride_bytes * step,
+            _marker: PhantomData,
+        })
+    }
+
+    /// Returns an iterator over logical dimension values, yielding [`DimRef`] proxies.
+    pub fn iter(&self) -> VectorViewIterator<'a, Scalar>
+    where
+        Scalar: FloatConvertible,
+    {
+        VectorViewIterator {
+            data: self.data,
+            stride_bytes: self.stride_bytes,
+            front: 0,
+            back: self.dims,
+            _marker: PhantomData,
+        }
+    }
+}
+
+impl<'a, AnyIndex: VectorIndex, Scalar: StorageElement> core::ops::Index<AnyIndex>
+    for VectorView<'a, Scalar>
+{
+    type Output = Scalar;
+
+    #[inline]
+    fn index(&self, index: AnyIndex) -> &Scalar {
+        let i = index.resolve(self.dims).expect("view index out of bounds");
+        debug_assert_eq!(
+            Scalar::dimensions_per_value(),
+            1,
+            "Index trait not supported for sub-byte types"
+        );
+        unsafe {
+            &*((self.data as *const u8).offset(self.stride_bytes * i as isize) as *const Scalar)
+        }
+    }
+}
+
+// endregion: VectorView
+
+// region: VectorSpan
+
+/// Mutable, possibly strided, non-owning view into a vector.
+///
+/// `VectorSpan` is the read-write counterpart of [`VectorView`]: it still
+/// performs zero-copy borrowing via a raw pointer, dimension count, and byte
+/// stride, but additionally allows element writes through `try_set`, `fill`,
+/// `iter_mut`, and `IndexMut`. Spans are typically obtained via
+/// [`Vector::span`] or a mutable slice of a tensor row.
+///
+/// Like views, spans support signed ([`VectorIndex`]) indexing, negative
+/// strides via [`VectorSpan::as_view`] + [`VectorView::rev`], and Python-style
+/// slicing through their view projection. The `'a` lifetime mirrors the owner
+/// of the underlying memory, and Rust's borrow checker prevents aliasing a
+/// single span with any other reference for the duration of `'a`.
+pub struct VectorSpan<'a, Scalar: StorageElement> {
+    data: *mut Scalar,
+    dims: usize,
+    stride_bytes: isize,
+    _marker: PhantomData<&'a mut Scalar>,
+}
+
+unsafe impl<'a, Scalar: StorageElement + Send> Send for VectorSpan<'a, Scalar> {}
+unsafe impl<'a, Scalar: StorageElement + Sync> Sync for VectorSpan<'a, Scalar> {}
+
+impl<'a, Scalar: StorageElement> VectorSpan<'a, Scalar> {
+    /// Create a mutable view from a raw pointer, dimension count, and byte stride.
+    ///
+    /// # Safety
+    /// - `data` must be valid for reads and writes of `dims` elements at the given stride.
+    /// - The pointed-to memory must outlive `'a`.
+    /// - `stride_bytes` must be non-zero for non-empty views.
+    /// - No other references to the memory may exist for the duration of `'a`.
+    #[inline]
+    pub unsafe fn from_raw_parts(data: *mut Scalar, dims: usize, stride_bytes: isize) -> Self {
+        Self {
+            data,
+            dims,
+            stride_bytes,
+            _marker: PhantomData,
+        }
+    }
+
+    /// Number of logical dimensions.
+    #[inline]
+    pub fn dims(&self) -> usize {
+        self.dims
+    }
+
+    /// Number of logical dimensions (alias for dims).
+    #[inline]
+    pub fn size(&self) -> usize {
+        self.dims
+    }
+
+    /// Returns true if empty.
+    #[inline]
+    pub fn is_empty(&self) -> bool {
+        self.dims == 0
+    }
+
+    /// Stride in bytes.
+    #[inline]
+    pub fn stride_bytes(&self) -> isize {
+        self.stride_bytes
+    }
+
+    /// Returns true if contiguous.
+    #[inline]
+    pub fn is_contiguous(&self) -> bool {
+        self.stride_bytes == core::mem::size_of::<Scalar>() as isize
+    }
+
+    /// Get the underlying pointer.
+    #[inline]
+    pub fn as_ptr(&self) -> *const Scalar {
+        self.data
+    }
+
+    /// Get the mutable underlying pointer.
+    #[inline]
+    pub fn as_mut_ptr(&mut self) -> *mut Scalar {
+        self.data
+    }
+
+    /// Reborrow as an immutable view, sharing the same data pointer and stride.
+    pub fn as_view(&self) -> VectorView<'_, Scalar> {
+        VectorView {
+            data: self.data,
+            dims: self.dims,
+            stride_bytes: self.stride_bytes,
+            _marker: PhantomData,
+        }
+    }
+
+    /// Try to get element at index.
+    #[inline]
+    pub fn try_get<AnyIndex: VectorIndex>(
+        &self,
+        index: AnyIndex,
+    ) -> Result<Scalar::DimScalar, TensorError>
+    where
+        Scalar: FloatConvertible,
+    {
+        self.as_view().try_get(index)
+    }
+
+    /// Try to set the element at `index`.
+    ///
+    /// Accepts the native `DimScalar` type. For sub-byte types, uses value_index
+    /// for stride-based pointer walks to avoid buffer overwrite.
+    #[inline]
+    pub fn try_set<AnyIndex: VectorIndex>(
+        &mut self,
+        index: AnyIndex,
+        value: Scalar::DimScalar,
+    ) -> Result<(), TensorError>
+    where
+        Scalar: FloatConvertible,
+    {
+        let i = index
+            .resolve(self.dims)
+            .ok_or(TensorError::IndexOutOfBounds {
+                index: 0,
+                size: self.dims,
+            })?;
+        let dims_per_value = Scalar::dimensions_per_value();
+        let value_index = i / dims_per_value;
+        let sub_index = i % dims_per_value;
+        // SAFETY: stride * value_index stays within allocation
+        let ptr = unsafe {
+            (self.data as *mut u8).offset(self.stride_bytes * value_index as isize) as *mut Scalar
+        };
+        let mut unpacked = unsafe { *ptr }.unpack();
+        unpacked.as_mut()[sub_index] = value;
+        unsafe { ptr.write(Scalar::pack(unpacked)) };
+        Ok(())
+    }
+
+    /// Fill all elements with a value, respecting the stride between elements.
+    ///
+    /// Iterates over storage values (not logical dimensions) to avoid buffer
+    /// overwrite for sub-byte types.
+    pub fn fill(&mut self, value: Scalar) {
+        let values = self.dims.div_ceil(Scalar::dimensions_per_value());
+        for i in 0..values {
+            // SAFETY: i < values; stride * i stays within the allocation
+            let ptr = unsafe {
+                (self.data as *mut u8).offset(self.stride_bytes * i as isize) as *mut Scalar
+            };
+            unsafe { ptr.write(value) };
+        }
+    }
+
+    /// Get a contiguous slice, if this span is contiguous.
+    #[inline]
+    pub fn as_contiguous_slice(&self) -> Option<&[Scalar]> {
+        if self.is_contiguous() && Scalar::dimensions_per_value() == 1 {
+            Some(unsafe { core::slice::from_raw_parts(self.data, self.dims) })
+        } else {
+            None
+        }
+    }
+
+    /// Get a mutable contiguous slice, if this span is contiguous.
+    #[inline]
+    pub fn as_contiguous_slice_mut(&mut self) -> Option<&mut [Scalar]> {
+        if self.is_contiguous() && Scalar::dimensions_per_value() == 1 {
+            Some(unsafe { core::slice::from_raw_parts_mut(self.data, self.dims) })
+        } else {
+            None
+        }
+    }
+
+    /// Returns an iterator over logical dimension values, yielding [`DimRef`] proxies.
+    pub fn iter(&self) -> VectorViewIterator<'_, Scalar>
+    where
+        Scalar: FloatConvertible,
+    {
+        VectorViewIterator {
+            data: self.data,
+            stride_bytes: self.stride_bytes,
+            front: 0,
+            back: self.dims,
+            _marker: PhantomData,
+        }
+    }
+
+    /// Returns a mutable iterator over logical dimension values, yielding [`DimMut`] proxies.
+    pub fn iter_mut(&mut self) -> VectorSpanIterator<'_, Scalar>
+    where
+        Scalar: FloatConvertible,
+    {
+        VectorSpanIterator {
+            data: self.data,
+            stride_bytes: self.stride_bytes,
+            front: 0,
+            back: self.dims,
+            _marker: PhantomData,
+        }
+    }
+}
+
+impl<'a, AnyIndex: VectorIndex, Scalar: StorageElement> core::ops::Index<AnyIndex>
+    for VectorSpan<'a, Scalar>
+{
+    type Output = Scalar;
+
+    #[inline]
+    fn index(&self, index: AnyIndex) -> &Scalar {
+        let i = index.resolve(self.dims).expect("span index out of bounds");
+        debug_assert_eq!(
+            Scalar::dimensions_per_value(),
+            1,
+            "Index trait not supported for sub-byte types"
+        );
+        unsafe {
+            &*((self.data as *const u8).offset(self.stride_bytes * i as isize) as *const Scalar)
+        }
+    }
+}
+
+impl<'a, AnyIndex: VectorIndex, Scalar: StorageElement> core::ops::IndexMut<AnyIndex>
+    for VectorSpan<'a, Scalar>
+{
+    #[inline]
+    fn index_mut(&mut self, index: AnyIndex) -> &mut Scalar {
+        let i = index.resolve(self.dims).expect("span index out of bounds");
+        debug_assert_eq!(
+            Scalar::dimensions_per_value(),
+            1,
+            "IndexMut trait not supported for sub-byte types"
+        );
+        unsafe {
+            &mut *((self.data as *mut u8).offset(self.stride_bytes * i as isize) as *mut Scalar)
+        }
+    }
+}
+
+// endregion: VectorSpan
+
+// region: Iterators
+
+/// Stride-aware immutable iterator over logical dimensions, yielding [`DimRef`] proxies.
+///
+/// For normal types (`dimensions_per_value=1`), yields one proxy per storage value.
+/// For sub-byte types, unpacks each storage value and yields sub-dimensions individually.
+/// Implements `ExactSizeIterator`, `FusedIterator`, and `DoubleEndedIterator`.
+pub struct VectorViewIterator<'a, Scalar: FloatConvertible> {
+    data: *const Scalar,
+    stride_bytes: isize,
+    front: usize,
+    back: usize,
+    _marker: PhantomData<&'a Scalar>,
+}
+
+/// Backward-compatible alias for [`VectorViewIterator`].
+pub type VectorIterator<'a, Scalar> = VectorViewIterator<'a, Scalar>;
+
+impl<'a, Scalar: FloatConvertible> Iterator for VectorViewIterator<'a, Scalar> {
+    type Item = DimRef<'a, Scalar>;
+
+    #[inline]
+    fn next(&mut self) -> Option<DimRef<'a, Scalar>> {
+        if self.front >= self.back {
+            return None;
+        }
+        let dims_per_value = Scalar::dimensions_per_value();
+        let value_index = self.front / dims_per_value;
+        let sub_index = self.front % dims_per_value;
+        // SAFETY: value_index < values, stride * value_index within allocation
+        let ptr = unsafe {
+            (self.data as *const u8).offset(self.stride_bytes * value_index as isize)
+                as *const Scalar
+        };
+        let scalar = unsafe { *ptr }.unpack().as_ref()[sub_index];
+        self.front += 1;
+        Some(DimRef::new(scalar))
+    }
+
+    #[inline]
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        let element_count = self.back - self.front;
+        (element_count, Some(element_count))
+    }
+}
+
+impl<'a, Scalar: FloatConvertible> ExactSizeIterator for VectorViewIterator<'a, Scalar> {}
+impl<'a, Scalar: FloatConvertible> core::iter::FusedIterator for VectorViewIterator<'a, Scalar> {}
+
+impl<'a, Scalar: FloatConvertible> DoubleEndedIterator for VectorViewIterator<'a, Scalar> {
+    #[inline]
+    fn next_back(&mut self) -> Option<DimRef<'a, Scalar>> {
+        if self.front >= self.back {
+            return None;
+        }
+        self.back -= 1;
+        let dims_per_value = Scalar::dimensions_per_value();
+        let value_index = self.back / dims_per_value;
+        let sub_index = self.back % dims_per_value;
+        let ptr = unsafe {
+            (self.data as *const u8).offset(self.stride_bytes * value_index as isize)
+                as *const Scalar
+        };
+        Some(DimRef::new(unsafe { *ptr }.unpack().as_ref()[sub_index]))
+    }
+}
+
+/// Stride-aware mutable iterator over logical dimensions, yielding [`DimMut`] proxies.
+///
+/// For normal types (`dimensions_per_value=1`), yields one proxy per storage value.
+/// For sub-byte types, each proxy performs a read-modify-write on drop.
+/// Implements `ExactSizeIterator`, `FusedIterator`, and `DoubleEndedIterator`.
+pub struct VectorSpanIterator<'a, Scalar: FloatConvertible> {
+    data: *mut Scalar,
+    stride_bytes: isize,
+    front: usize,
+    back: usize,
+    _marker: PhantomData<&'a mut Scalar>,
+}
+
+impl<'a, Scalar: FloatConvertible> Iterator for VectorSpanIterator<'a, Scalar> {
+    type Item = DimMut<'a, Scalar>;
+
+    #[inline]
+    fn next(&mut self) -> Option<DimMut<'a, Scalar>> {
+        if self.front >= self.back {
+            return None;
+        }
+        let dims_per_value = Scalar::dimensions_per_value();
+        let value_index = self.front / dims_per_value;
+        let sub_index = self.front % dims_per_value;
+        let ptr = unsafe {
+            (self.data as *mut u8).offset(self.stride_bytes * value_index as isize) as *mut Scalar
+        };
+        let scalar = unsafe { *ptr }.unpack().as_ref()[sub_index];
+        self.front += 1;
+        Some(unsafe { DimMut::new(ptr, sub_index, scalar) })
+    }
+
+    #[inline]
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        let element_count = self.back - self.front;
+        (element_count, Some(element_count))
+    }
+}
+
+impl<'a, Scalar: FloatConvertible> ExactSizeIterator for VectorSpanIterator<'a, Scalar> {}
+impl<'a, Scalar: FloatConvertible> core::iter::FusedIterator for VectorSpanIterator<'a, Scalar> {}
+
+impl<'a, Scalar: FloatConvertible> DoubleEndedIterator for VectorSpanIterator<'a, Scalar> {
+    #[inline]
+    fn next_back(&mut self) -> Option<DimMut<'a, Scalar>> {
+        if self.front >= self.back {
+            return None;
+        }
+        self.back -= 1;
+        let dims_per_value = Scalar::dimensions_per_value();
+        let value_index = self.back / dims_per_value;
+        let sub_index = self.back % dims_per_value;
+        let ptr = unsafe {
+            (self.data as *mut u8).offset(self.stride_bytes * value_index as isize) as *mut Scalar
+        };
+        let scalar = unsafe { *ptr }.unpack().as_ref()[sub_index];
+        Some(unsafe { DimMut::new(ptr, sub_index, scalar) })
+    }
+}
+
+// endregion: Iterators
+
+// region: IntoIterator (immutable)
+
+impl<'a, Scalar: FloatConvertible, Alloc: Allocator> IntoIterator for &'a Vector<Scalar, Alloc> {
+    type Item = DimRef<'a, Scalar>;
+    type IntoIter = VectorViewIterator<'a, Scalar>;
+    fn into_iter(self) -> Self::IntoIter {
+        self.iter()
+    }
+}
+
+impl<'a, Scalar: FloatConvertible> IntoIterator for &'a VectorView<'a, Scalar> {
+    type Item = DimRef<'a, Scalar>;
+    type IntoIter = VectorViewIterator<'a, Scalar>;
+    fn into_iter(self) -> Self::IntoIter {
+        self.iter()
+    }
+}
+
+impl<'a, Scalar: FloatConvertible> IntoIterator for &'a VectorSpan<'a, Scalar> {
+    type Item = DimRef<'a, Scalar>;
+    type IntoIter = VectorViewIterator<'a, Scalar>;
+    fn into_iter(self) -> Self::IntoIter {
+        self.iter()
+    }
+}
+
+// endregion: IntoIterator (immutable)
+
+// region: IntoIterator (mutable)
+
+impl<'a, Scalar: FloatConvertible, Alloc: Allocator> IntoIterator
+    for &'a mut Vector<Scalar, Alloc>
+{
+    type Item = DimMut<'a, Scalar>;
+    type IntoIter = VectorSpanIterator<'a, Scalar>;
+    fn into_iter(self) -> Self::IntoIter {
+        self.iter_mut()
+    }
+}
+
+impl<'a, Scalar: FloatConvertible> IntoIterator for &'a mut VectorSpan<'a, Scalar> {
+    type Item = DimMut<'a, Scalar>;
+    type IntoIter = VectorSpanIterator<'a, Scalar>;
+    fn into_iter(self) -> Self::IntoIter {
+        self.iter_mut()
+    }
+}
+
+// endregion: IntoIterator (mutable)
+
+// region: AsRef
+
+impl<Scalar: StorageElement, Alloc: Allocator> AsRef<[Scalar]> for Vector<Scalar, Alloc> {
+    fn as_ref(&self) -> &[Scalar] {
+        self.as_slice()
+    }
+}
+
+// endregion: AsRef
+
+// region: PartialEq
+
+impl<Scalar: FloatConvertible, Alloc: Allocator> PartialEq for Vector<Scalar, Alloc>
+where
+    Scalar::DimScalar: PartialEq,
+{
+    fn eq(&self, other: &Self) -> bool {
+        self.dims == other.dims && self.iter().zip(other.iter()).all(|(a, b)| a == b)
+    }
+}
+
+impl<Scalar: FloatConvertible, Alloc: Allocator> PartialEq<[Scalar::DimScalar]>
+    for Vector<Scalar, Alloc>
+where
+    Scalar::DimScalar: PartialEq,
+{
+    fn eq(&self, other: &[Scalar::DimScalar]) -> bool {
+        self.dims == other.len() && self.iter().zip(other.iter()).all(|(a, b)| *a == *b)
+    }
+}
+
+impl<'a, Scalar: FloatConvertible> PartialEq for VectorView<'a, Scalar>
+where
+    Scalar::DimScalar: PartialEq,
+{
+    fn eq(&self, other: &Self) -> bool {
+        self.dims == other.dims && self.iter().zip(other.iter()).all(|(a, b)| a == b)
+    }
+}
+
+impl<'a, Scalar: FloatConvertible> PartialEq for VectorSpan<'a, Scalar>
+where
+    Scalar::DimScalar: PartialEq,
+{
+    fn eq(&self, other: &Self) -> bool {
+        self.dims == other.dims && self.iter().zip(other.iter()).all(|(a, b)| a == b)
+    }
+}
+
+// endregion: PartialEq
+
+// region: Tolerance Equality
+
+impl<Scalar: FloatConvertible, Alloc: Allocator> Vector<Scalar, Alloc>
+where
+    Scalar::DimScalar: NumberLike,
+{
+    /// Check if all elements are within tolerance of `other`.
+    ///
+    /// Uses the formula `|a - b| <= atol + rtol * |b|` per element.
+    /// Returns `false` if dimensions differ.
+    pub fn allclose<OtherAlloc: Allocator>(
+        &self,
+        other: &Vector<Scalar, OtherAlloc>,
+        atol: f64,
+        rtol: f64,
+    ) -> bool {
+        self.dims == other.dims
+            && self
+                .iter()
+                .zip(other.iter())
+                .all(|(a, b)| crate::types::is_close(a.to_f64(), b.to_f64(), atol, rtol))
+    }
+}
+
+impl<'a, Scalar: FloatConvertible> VectorView<'a, Scalar>
+where
+    Scalar::DimScalar: NumberLike,
+{
+    /// Check if all elements are within tolerance of `other`.
+    ///
+    /// Uses the formula `|a - b| <= atol + rtol * |b|` per element.
+    /// Returns `false` if dimensions differ.
+    pub fn allclose(&self, other: &Self, atol: f64, rtol: f64) -> bool {
+        self.dims == other.dims
+            && self
+                .iter()
+                .zip(other.iter())
+                .all(|(a, b)| crate::types::is_close(a.to_f64(), b.to_f64(), atol, rtol))
+    }
+}
+
+impl<'a, Scalar: FloatConvertible> VectorSpan<'a, Scalar>
+where
+    Scalar::DimScalar: NumberLike,
+{
+    /// Check if all elements are within tolerance of `other`.
+    ///
+    /// Uses the formula `|a - b| <= atol + rtol * |b|` per element.
+    /// Returns `false` if dimensions differ.
+    pub fn allclose(&self, other: &Self, atol: f64, rtol: f64) -> bool {
+        self.dims == other.dims
+            && self
+                .iter()
+                .zip(other.iter())
+                .all(|(a, b)| crate::types::is_close(a.to_f64(), b.to_f64(), atol, rtol))
+    }
+}
+
+// endregion: Tolerance Equality
+
+// region: Debug and Display
+
+/// Write a truncated, debug-formatted list from an iterator.
+fn fmt_debug_list<I: Iterator>(
+    f: &mut core::fmt::Formatter<'_>,
+    name: &str,
+    dims: usize,
+    iter: I,
+    limit: usize,
+) -> core::fmt::Result
+where
+    I::Item: core::fmt::Debug,
+{
+    write!(f, "{}(dims={}, [", name, dims)?;
+    for (i, value) in iter.enumerate() {
+        if i >= limit {
+            write!(f, ", ...")?;
+            break;
+        }
+        if i > 0 {
+            write!(f, ", ")?;
+        }
+        write!(f, "{:?}", value)?;
+    }
+    write!(f, "])")
+}
+
+/// Write a truncated, display-formatted list from an iterator.
+fn fmt_display_list<I: Iterator>(
+    f: &mut core::fmt::Formatter<'_>,
+    iter: I,
+    limit: usize,
+) -> core::fmt::Result
+where
+    I::Item: core::fmt::Display,
+{
+    let prec = f.precision();
+    write!(f, "[")?;
+    for (i, value) in iter.enumerate() {
+        if i >= limit {
+            write!(f, ", ...")?;
+            break;
+        }
+        if i > 0 {
+            write!(f, ", ")?;
+        }
+        if let Some(p) = prec {
+            write!(f, "{:.p$}", value)?;
+        } else {
+            write!(f, "{}", value)?;
+        }
+    }
+    write!(f, "]")
+}
+
+impl<Scalar: FloatConvertible, Alloc: Allocator> core::fmt::Debug for Vector<Scalar, Alloc>
+where
+    Scalar::DimScalar: core::fmt::Debug,
+{
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        fmt_debug_list(f, "Vector", self.dims, self.iter(), 8)
+    }
+}
+
+impl<'a, Scalar: FloatConvertible> core::fmt::Debug for VectorView<'a, Scalar>
+where
+    Scalar::DimScalar: core::fmt::Debug,
+{
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        fmt_debug_list(f, "VectorView", self.dims, self.iter(), 8)
+    }
+}
+
+impl<'a, Scalar: FloatConvertible> core::fmt::Debug for VectorSpan<'a, Scalar>
+where
+    Scalar::DimScalar: core::fmt::Debug,
+{
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        fmt_debug_list(f, "VectorSpan", self.dims, self.iter(), 8)
+    }
+}
+
+impl<Scalar: FloatConvertible, Alloc: Allocator> core::fmt::Display for Vector<Scalar, Alloc>
+where
+    Scalar::DimScalar: core::fmt::Display,
+{
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        fmt_display_list(f, self.iter(), 20)
+    }
+}
+
+// endregion: Debug and Display
+
+// region: Tests
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::types::{bf16, f16, i4x2, u1x8, u4x2};
+
+    fn check_vector_roundtrip<Scalar: FloatConvertible>() {
+        let dims_per_value = Scalar::dimensions_per_value();
+        let test_dims = 16 * dims_per_value;
+        let v = Vector::<Scalar>::try_zeros(test_dims).unwrap();
+        assert_eq!(v.dims(), test_dims);
+        assert_eq!(v.size_values(), test_dims / dims_per_value);
+        let count = v.iter().count();
+        assert_eq!(count, test_dims);
+    }
+
+    fn check_vector_try_get_set<Scalar: FloatConvertible>()
+    where
+        Scalar::DimScalar: core::fmt::Debug,
+    {
+        let dims_per_value = Scalar::dimensions_per_value();
+        let test_dims = 4 * dims_per_value;
+        let mut v = Vector::<Scalar>::try_zeros(test_dims).unwrap();
+        let one = Scalar::DimScalar::from_f32(1.0);
+        v.try_set(0_usize, one).unwrap();
+        v.try_set((test_dims - 1) as i32, one).unwrap();
+        let first = v.try_get(0_usize).unwrap();
+        let last = v.try_get(-1_i32).unwrap();
+        assert!(
+            first.to_f32() >= 0.5,
+            "first dim should be ~1.0, got {:?}",
+            first
+        );
+        assert!(
+            last.to_f32() >= 0.5,
+            "last dim should be ~1.0, got {:?}",
+            last
+        );
+    }
+
+    #[test]
+    fn vector_roundtrip_all_types() {
+        check_vector_roundtrip::<f32>();
+        check_vector_roundtrip::<f64>();
+        check_vector_roundtrip::<f16>();
+        check_vector_roundtrip::<bf16>();
+        check_vector_roundtrip::<i4x2>();
+        check_vector_roundtrip::<u4x2>();
+        check_vector_roundtrip::<u1x8>();
+    }
+
+    #[test]
+    fn vector_try_get_set_all_types() {
+        check_vector_try_get_set::<f32>();
+        check_vector_try_get_set::<f64>();
+        check_vector_try_get_set::<i4x2>();
+        check_vector_try_get_set::<u4x2>();
+        check_vector_try_get_set::<u1x8>();
+    }
+
+    #[test]
+    fn vec_index_signed() {
+        let v = Vector::<f32>::try_from_dims(&[10.0, 20.0, 30.0, 40.0, 50.0]).unwrap();
+        // Positive indexing
+        assert_eq!(v[0], 10.0);
+        assert_eq!(v[4], 50.0);
+        // Negative indexing (i32 default for integer literals)
+        assert_eq!(v[-1_i32], 50.0);
+        assert_eq!(v[-2_i32], 40.0);
+        assert_eq!(v[-5_i32], 10.0);
+    }
+
+    #[test]
+    fn vector_view_stride() {
+        let v = Vector::<f32>::try_from_scalars(&[1.0, 2.0, 3.0, 4.0, 5.0]).unwrap();
+        let view = v.view();
+        assert!(view.is_contiguous());
+        assert_eq!(view.size(), 5);
+
+        // Reversed view
+        let rev = view.rev();
+        assert_eq!(rev.try_get(0_usize).unwrap(), 5.0);
+        assert_eq!(rev.try_get(4_usize).unwrap(), 1.0);
+    }
+
+    #[test]
+    fn vector_span_fill() {
+        let mut v = Vector::<f32>::try_zeros(4).unwrap();
+        {
+            let mut span = v.span();
+            span.fill(42.0);
+        }
+        assert_eq!(v[0], 42.0);
+        assert_eq!(v[3], 42.0);
+    }
+
+    #[test]
+    fn vector_iter() {
+        let v = Vector::<f32>::try_from_scalars(&[1.0, 2.0, 3.0]).unwrap();
+        let values: Vec<f32> = v.iter().map(|x| *x).collect();
+        assert_eq!(values, vec![1.0, 2.0, 3.0]);
+
+        // Double-ended
+        let reversed_values: Vec<f32> = v.iter().rev().map(|x| *x).collect();
+        assert_eq!(reversed_values, vec![3.0, 2.0, 1.0]);
+    }
+
+    #[test]
+    fn view_strided_iteration() {
+        let v = Vector::<f32>::try_from_scalars(&[1.0, 2.0, 3.0, 4.0, 5.0]).unwrap();
+        let view = v.view();
+
+        // Every other element
+        let strided = view.try_strided(0, 5, 2).unwrap();
+        assert_eq!(strided.size(), 3);
+        let values: Vec<f32> = strided.iter().map(|x| *x).collect();
+        assert_eq!(values, vec![1.0, 3.0, 5.0]);
+    }
+
+    #[test]
+    fn vector_filled() {
+        let v = Vector::<f32>::try_full(3, 7.5).unwrap();
+        assert_eq!(v[0], 7.5);
+        assert_eq!(v[1], 7.5);
+        assert_eq!(v[2], 7.5);
+    }
+
+    #[test]
+    fn empty_vector() {
+        let v = Vector::<f32>::try_zeros(0).unwrap();
+        assert!(v.is_empty());
+        assert_eq!(v.size(), 0);
+    }
+
+    #[test]
+    #[should_panic]
+    fn index_out_of_bounds() {
+        let v = Vector::<f32>::try_zeros(3).unwrap();
+        let _ = v[3_usize];
+    }
+
+    #[test]
+    fn vector_allclose_matching() {
+        let a = Vector::<f32>::try_full(4, 1.0).unwrap();
+        let b = Vector::<f32>::try_full(4, 1.0 + 1e-7).unwrap();
+        assert!(a.allclose(&b, 1e-6, 0.0));
+    }
+
+    #[test]
+    fn vector_allclose_mismatching() {
+        let a = Vector::<f32>::try_full(4, 1.0).unwrap();
+        let b = Vector::<f32>::try_full(4, 2.0).unwrap();
+        assert!(!a.allclose(&b, 1e-6, 0.0));
+    }
+
+    #[test]
+    fn vector_allclose_different_dims() {
+        let a = Vector::<f32>::try_full(3, 1.0).unwrap();
+        let b = Vector::<f32>::try_full(4, 1.0).unwrap();
+        assert!(!a.allclose(&b, 1e-6, 1e-6));
+    }
+
+    #[test]
+    fn display_precision_forwarding() {
+        let v = Vector::<f32>::try_full(3, 1.0).unwrap();
+        let s = format!("{:.2}", v);
+        assert_eq!(s, "[1.00, 1.00, 1.00]");
+    }
+
+    #[test]
+    fn vector_span_iter_mut_f32() {
+        let mut v = Vector::<f32>::try_from_scalars(&[1.0, 2.0, 3.0]).unwrap();
+        for mut value in &mut v {
+            *value += 10.0;
+        }
+        let values: Vec<f32> = v.iter().map(|x| *x).collect();
+        assert_eq!(values, vec![11.0, 12.0, 13.0]);
+    }
+
+    #[test]
+    fn vector_span_iter_mut_i4x2() {
+        let mut v = Vector::<i4x2>::try_zeros(4).unwrap();
+        {
+            let mut span = v.span();
+            for (i, mut value) in span.iter_mut().enumerate() {
+                *value = (i + 1) as i8;
+            }
+        }
+        assert_eq!(v.try_get(0_usize).unwrap(), 1);
+        assert_eq!(v.try_get(1_usize).unwrap(), 2);
+        assert_eq!(v.try_get(2_usize).unwrap(), 3);
+        assert_eq!(v.try_get(3_usize).unwrap(), 4);
+    }
+
+    #[test]
+    fn vector_span_iter_mut_u1x8() {
+        let mut v = Vector::<u1x8>::try_zeros(8).unwrap();
+        for (i, mut value) in v.iter_mut().enumerate() {
+            if i % 2 == 0 {
+                *value = 1;
+            }
+        }
+        // Even indices should be 1, odd should be 0
+        assert_eq!(v.try_get(0_usize).unwrap(), 1);
+        assert_eq!(v.try_get(1_usize).unwrap(), 0);
+        assert_eq!(v.try_get(2_usize).unwrap(), 1);
+        assert_eq!(v.try_get(3_usize).unwrap(), 0);
+    }
+
+    #[test]
+    fn vector_span_iter_double_ended() {
+        let mut v = Vector::<f32>::try_from_scalars(&[1.0, 2.0, 3.0]).unwrap();
+        let mut span = v.span();
+        let mut it = span.iter_mut();
+        // Take from front
+        let mut first = it.next().unwrap();
+        *first = 10.0;
+        drop(first);
+        // Take from back
+        let mut last = it.next_back().unwrap();
+        *last = 30.0;
+        drop(last);
+        drop(it);
+        drop(span);
+        assert_eq!(v.try_get(0_usize).unwrap(), 10.0);
+        assert_eq!(v.try_get(1_usize).unwrap(), 2.0);
+        assert_eq!(v.try_get(2_usize).unwrap(), 30.0);
+    }
+
+    #[test]
+    fn vector_iterator_alias_compat() {
+        // VectorIterator type alias should still work
+        let v = Vector::<f32>::try_from_scalars(&[1.0]).unwrap();
+        let _it: VectorIterator<'_, f32> = v.iter();
+    }
+}
+
+// endregion: Tests