Struct FixedVec

pub struct FixedVec<T: Storable<W>, W: Word, E: Endianness, B: AsRef<[W]> = Vec<W>> { /* private fields */ }

A compressed vector of integers with fixed-width encoding.

FixedVec stores a sequence of integers where each element is encoded using the same number of bits. This allows for O(1) random access by calculating the memory location of any element. It is suitable for data where values are bounded within a known range.

Type Parameters

• T: The integer type for the elements (e.g., u32, i16). It must implement the Storable trait.
• W: The underlying storage word (e.g., u64, usize). It must implement the Word trait.
• E: The Endianness (e.g., LE or BE) for bit-level operations.
• B: The backend storage buffer, such as Vec<W> for an owned vector or &[W] for a borrowed view.

For common configurations, several type aliases are provided.

Implementations

impl<T, W, E, B> FixedVec<T, W, E, B>

where T: Storable<W> + Send + Sync, W: Word + Sync, E: Endianness, B: AsRef<[W]> + Sync,

pub fn par_iter(&self) -> impl IndexedParallelIterator<Item = T> + '_

Returns a parallel iterator over the decompressed values.

This operation is highly parallelizable because each element can be decompressed independently from the others.

Examples

use compressed_intvec::fixed::{FixedVec, UFixedVec};
use rayon::prelude::*;

let data: Vec<u32> = (0..100).collect();
let vec: UFixedVec<u32> = FixedVec::builder().build(&data).unwrap();

let count = vec.par_iter().filter(|&x| x % 2 == 0).count();
assert_eq!(count, 50);

pub fn par_get_many(&self, indices: &[usize]) -> Result<Vec<T>, FixedVecError>

Retrieves multiple elements in parallel.

Errors

Returns an error if any index is out of bounds.

Examples

use compressed_intvec::fixed::{FixedVec, UFixedVec};

let data: Vec<u32> = (0..100).collect();
let vec: UFixedVec<u32> = FixedVec::builder().build(&data).unwrap();

let indices = vec![10, 50, 99];
let values = vec.par_get_many(&indices).unwrap();
assert_eq!(values, vec![10, 50, 99]);

// An out-of-bounds index will result in an error.
let invalid_indices = vec![10, 100];
assert!(vec.par_get_many(&invalid_indices).is_err());

pub unsafe fn par_get_many_unchecked(&self, indices: &[usize]) -> Vec<T>

Retrieves multiple elements in parallel without bounds checking.

Safety

Calling this method with any out-of-bounds index is Undefined Behavior. All indices must be less than self.len().

impl<T, W, E> FixedVec<T, W, E, Vec<W>>

where T: Storable<W>, W: Word, E: Endianness, BufBitWriter<E, MemWordWriterVec<W, Vec<W>>>: BitWrite<E, Error = Infallible>,

pub fn builder() -> FixedVecBuilder<T, W, E>

Creates a builder for constructing a FixedVec from a slice.

The builder provides methods to customize the vector’s properties, such as the BitWidth strategy.

Examples

use compressed_intvec::fixed::{FixedVec, BitWidth, UFixedVec};

let data: &[u32] = &[10, 20, 30, 40, 50];
let vec: UFixedVec<u32> = FixedVec::builder()
    .bit_width(BitWidth::Minimal)
    .build(data)
    .unwrap();

assert_eq!(vec.get(1), Some(20));

pub fn from_iter_builder<I: IntoIterator<Item = T>>( iter: I, bit_width: usize, ) -> FixedVecFromIterBuilder<T, W, E, I>

Creates a builder for constructing a FixedVec from an iterator.

This builder is suitable for large datasets provided by an iterator, as it processes the data in a streaming fashion.

Arguments

• iter: An iterator that yields the integer values.
• bit_width: The number of bits to use for each element. This must be specified, as the builder cannot analyze the data in advance.

Examples

use compressed_intvec::fixed::{FixedVec, UFixedVec};

let data = 0..100u32;
let vec: UFixedVec<u32> = FixedVec::from_iter_builder(data, 7)
    .build()
    .unwrap();

assert_eq!(vec.len(), 100);
assert_eq!(vec.bit_width(), 7);
assert_eq!(vec.get(99), Some(99));

pub fn from_slice(slice: &[T]) -> Result<Self, Error>

Creates an owned FixedVec from a slice of data.

This method is a convenience wrapper around the builder API, using the default bit width strategy (BitWidth::Minimal).

Examples

use compressed_intvec::fixed::{FixedVec, UFixedVec};
 
let data: &[u32] = &[10, 20, 30];
 
let vec: UFixedVec<u32> = FixedVec::from_slice(data).unwrap();
 
assert_eq!(vec.len(), 3);
assert_eq!(vec.bit_width(), 5); // 30 fits in 5 bits
assert_eq!(vec.get(0), Some(10));

impl<T, W, E, B> FixedVec<T, W, E, B>

where T: Storable<W>, W: Word, E: Endianness, B: AsRef<[W]>,

pub fn from_parts(bits: B, len: usize, bit_width: usize) -> Result<Self, Error>

Creates a FixedVec from its raw components.

This constructor allows for the creation of a zero-copy view over an existing buffer.

Errors

Returns an Error::InvalidParameters if bit_width is larger than the word size or if the bits buffer is too small to hold the specified number of elements and the required padding.

Implementation Notes

The provided bits buffer must contain at least one extra “padding” word at the end. This padding is essential to prevent out-of-bounds memory access in methods like get_unchecked.

Examples

use compressed_intvec::fixed::{FixedVec, UFixedVec};

// 3 elements * 5 bits = 15 bits. This requires 1 data word.
// We need 1 extra word for padding.
let mut buffer = vec![0_usize; 2];

// Manually encode data into the first word.
// 10 (01010), 20 (10100), 30 (11110)
buffer[0] = 0b11110_10100_01010;

let vec = UFixedVec::<u32, _>::from_parts(&buffer, 3, 5).unwrap();
assert_eq!(vec.get(0), Some(10));
assert_eq!(vec.get(1), Some(20));
assert_eq!(vec.get(2), Some(30));

pub fn len(&self) -> usize

Returns the number of elements in the vector.

pub fn is_empty(&self) -> bool

Returns true if the vector is empty.

pub fn bit_width(&self) -> usize

Returns the number of bits used to encode each element.

pub fn as_limbs(&self) -> &[W]

Returns a read-only slice of the underlying storage words.

pub fn as_raw_parts(&self) -> (*const W, usize)

Returns a raw pointer to the start of the underlying buffer and its length in words.

Safety

The caller must ensure that the buffer is not mutated in a way that violates the invariants of the FixedVec while the pointer is active.

pub fn get(&self, index: usize) -> Option<T>

Returns the element at the specified index, or None if the index is out of bounds.

This operation is O(1).

Examples

use compressed_intvec::fixed::{FixedVec, UFixedVec};

let data: &[u32] = &[10, 20, 30];
let vec: UFixedVec<u32> = FixedVec::builder().build(data).unwrap();

assert_eq!(vec.get(1), Some(20));
assert_eq!(vec.get(3), None);

pub unsafe fn get_unchecked(&self, index: usize) -> T

Returns the element at the specified index without bounds checking.

Safety

Calling this method with an out-of-bounds index is undefined behavior. The index must be less than the vector’s len.

pub unsafe fn get_unaligned_unchecked(&self, index: usize) -> T

Returns the element at index using unaligned memory access.

This method can be significantly faster for random access. It performs a single, potentially unaligned read of a Word and extracts the value.

Performance

This method is generally the fastest way to perform random reads on Little-Endian architectures, especially when the bit_width is not a power of two.

• get_unchecked: May require reading one or two separate machine words and combining them with bit shifts. This is fast if the data is already in the CPU cache.
• get_unaligned_unchecked: Performs a single memory read that may cross word boundaries. It often results in fewer instructions and better throughput than the two separate reads of get_unchecked, especially in memory-bound scenarios.

Safety

Calling this method with an out-of-bounds index is undefined behavior. The FixedVec must have been constructed with sufficient padding (at least one Word) to guarantee that the unaligned read does not go past the allocated buffer. This padding is guaranteed by the default builders.

Implementation Notes

For Big-Endian, this method falls back to the standard get_unchecked implementation.

pub fn iter(&self) -> FixedVecIter<'_, T, W, E, B>

Returns an iterator over the elements of the vector.

Examples

use compressed_intvec::fixed::{FixedVec, UFixedVec};

let data: &[u32] = &[10, 20, 30];
let vec: UFixedVec<u32> = FixedVec::builder().build(data).unwrap();
let mut iter = vec.iter();

for (i, value) in iter.enumerate() {
    assert_eq!(Some(value), vec.get(i));
}

pub unsafe fn iter_unchecked(&self) -> FixedVecUncheckedIter<'_, T, W, E, B>

Returns an unchecked iterator over the elements of the vector.

Safety

The caller must ensure that the iterator is not advanced beyond the vector’s length.

pub fn slice(&self, start: usize, len: usize) -> Option<FixedVecSlice<&Self>>

Creates an immutable view (slice) of a sub-region of the vector.

Returns None if the specified range is out of bounds.

Arguments

• start: The starting index of the slice.
• len: The number of elements in the slice.

pub fn split_at( &self, mid: usize, ) -> Option<(FixedVecSlice<&Self>, FixedVecSlice<&Self>)>

Splits the vector into two immutable views at a given index.

Returns None if mid is out of bounds.

Arguments

• mid: The index at which to split the vector.

pub fn chunks(&self, chunk_size: usize) -> Chunks<'_, T, W, E, B>

Returns an iterator over non-overlapping chunks of the vector.

Each chunk is a FixedVecSlice of length chunk_size, except for the last chunk, which may be shorter.

Panics

Panics if chunk_size is 0.

pub fn windows(&self, size: usize) -> Windows<'_, T, W, E, B>

Returns an iterator over all contiguous windows of length size.

The windows overlap. If the vector is shorter than size, the iterator returns no values.

Panics

Panics if size is 0.

Examples

use compressed_intvec::fixed_vec;

let vec = fixed_vec![1u32, 2, 3, 4, 5];
let mut windows = vec.windows(3);

let slice1 = vec.slice(0, 3).unwrap();
let slice2 = vec.slice(1, 3).unwrap();
let slice3 = vec.slice(2, 3).unwrap();

assert_eq!(windows.next().unwrap(), slice1);
assert_eq!(windows.next().unwrap(), slice2);
assert_eq!(windows.next().unwrap(), slice3);
assert!(windows.next().is_none());

pub fn addr_of(&self, index: usize) -> Option<*const W>

Returns a raw pointer to the storage word containing the start of an element.

This method returns a pointer to the Word in the backing buffer where the data for the element at index begins.

Returns None if index is out of bounds.

Safety

This method is safe as it only returns a raw pointer. Dereferencing the pointer is unsafe. The caller must ensure that the pointer is not used after the FixedVec is dropped or modified.

pub fn prefetch(&self, index: usize)

Hints to the CPU to prefetch the data for the element at index into cache.

This method uses an intrinsic to reduce memory latency for predictable access patterns. It only has an effect on architectures that support it (e.g., x86, x86-64) and compiles to a no-op on other platforms.

pub fn binary_search(&self, value: &T) -> Result<usize, usize>

where T: Ord,

Binary searches this vector for a given element.

If the value is found, returns Ok(usize) with the index of the matching element. If the value is not found, returns Err(usize) with the index where the value could be inserted to maintain order.

Examples

use compressed_intvec::fixed::{FixedVec, UFixedVec};

let data: &[u32] = &[10, 20, 30, 40, 50];
let vec: UFixedVec<u32> = FixedVec::builder().build(data).unwrap();

assert_eq!(vec.binary_search(&30), Ok(2));
assert_eq!(vec.binary_search(&35), Err(3));

pub fn binary_search_by_key<K: Ord, F>( &self, key: &K, f: F, ) -> Result<usize, usize>

where F: FnMut(T) -> K,

Binary searches this vector with a key extraction function.

This method is useful when searching for a value of a different type than the elements of the slice. The function f is used to extract a key of type K from an element, which is then compared to key.

pub fn binary_search_by<F>(&self, f: F) -> Result<usize, usize>

where F: FnMut(&T) -> Ordering,

Binary searches this vector with a custom comparison function.

The comparator function f should return an Ordering indicating the relation of a probe element to the value being searched for.

Examples

use compressed_intvec::fixed_vec;
use std::cmp::Ordering;

let vec = fixed_vec![0u32, 1, 1, 2, 3];

// Search for a value by comparing it to the probe.
let result = vec.binary_search_by(|probe| probe.cmp(&1));
assert!(matches!(result, Ok(1) | Ok(2)));

let result_not_found = vec.binary_search_by(|probe| probe.cmp(&4));
assert_eq!(result_not_found, Err(5));

pub fn partition_point<P>(&self, pred: P) -> usize

where P: FnMut(&T) -> bool,

Returns the index of the partition point of the vector.

The vector is partitioned according to the predicate pred. This means all elements for which pred returns true are on the left of the partition point, and all elements for which pred returns false are on the right.

Examples

use compressed_intvec::fixed_vec;

let vec = fixed_vec![0u32, 1, 2, 3, 4, 5];

// Find the partition point for elements `< 3`.
let partition_idx = vec.partition_point(|&x| x < 3);
assert_eq!(partition_idx, 3);

impl<T, W, E> FixedVec<T, W, E, Vec<W>>

where T: Storable<W> + ToPrimitive, W: Word, E: Endianness,

pub fn new(bit_width: usize) -> Result<Self, Error>

Creates a new, empty FixedVec with a specified bit width.

Errors

Returns an Error::InvalidParameters if bit_width is greater than the number of bits in the storage word W.

Examples

use compressed_intvec::fixed::{FixedVec, UFixedVec};

let vec: UFixedVec<u32> = FixedVec::new(8).unwrap();
assert!(vec.is_empty());
assert_eq!(vec.bit_width(), 8);

pub fn push(&mut self, value: T)

Appends an element to the end of the vector.

This operation has amortized O(1) complexity.

Panics

Panics if the value is too large to be represented by the configured bit_width.

Examples

use compressed_intvec::fixed::{FixedVec, UFixedVec};

let mut vec: UFixedVec<u32> = FixedVec::new(4).unwrap();
vec.push(10);
vec.push(15);

assert_eq!(vec.len(), 2);
assert_eq!(vec.get(1), Some(15));

pub fn pop(&mut self) -> Option<T>

Removes the last element from the vector and returns it.

Returns None if the vector is empty.

Examples

use compressed_intvec::fixed_vec;

let mut vec = fixed_vec![1u32, 2, 3];
assert_eq!(vec.pop(), Some(3));
assert_eq!(vec.len(), 2);

pub fn clear(&mut self)

Removes all elements from the vector, leaving the capacity unchanged.

pub fn with_capacity(bit_width: usize, capacity: usize) -> Result<Self, Error>

Creates a new, empty FixedVec with a specified bit width and capacity.

The vector will be able to hold at least capacity elements without reallocating.

Errors

Returns an Error::InvalidParameters if bit_width is greater than the number of bits in the storage word W.

Examples

use compressed_intvec::fixed::{FixedVec, UFixedVec};

let vec: UFixedVec<u32> = FixedVec::with_capacity(5, 1000).unwrap();
assert!(vec.capacity() >= 1000);

pub fn capacity(&self) -> usize

Returns the number of elements the vector can hold without reallocating.

pub fn word_capacity(&self) -> usize

Returns the capacity of the underlying storage in words.

pub fn reserve(&mut self, additional: usize)

Reserves capacity for at least additional more elements to be inserted.

Panics

Panics if the new capacity overflows usize.

Examples

use compressed_intvec::fixed::{FixedVec, UFixedVec};

let mut vec: UFixedVec<u32> = FixedVec::new(4).unwrap();
vec.reserve(100);
assert!(vec.capacity() >= 100);

pub fn resize(&mut self, new_len: usize, value: T)

Resizes the vector so that its length is equal to new_len.

If new_len is greater than the current length, the vector is extended by appending value. If new_len is less than the current length, the vector is truncated.

Panics

Panics if the value used for filling does not fit in the configured bit_width.

Examples

use compressed_intvec::fixed::{FixedVec, UFixedVec};

let mut vec = UFixedVec::<u32>::new(4).unwrap();
vec.push(1);
vec.push(2);

vec.resize(4, 10);
assert_eq!(vec.len(), 4);
assert_eq!(vec.get(3), Some(10));

vec.resize(1, 0);
assert_eq!(vec.len(), 1);
assert_eq!(vec.get(0), Some(1));

pub fn shrink_to_fit(&mut self)

Shrinks the capacity of the vector as much as possible.

pub fn remove(&mut self, index: usize) -> T

Removes and returns the element at index, shifting all elements after it to the left.

This operation is O(n), where n is the number of elements after index.

Panics

Panics if index is out of bounds.

Complexity

This operation has a complexity of O(L), where L is the number of bits that need to be shifted. In the worst case (removing the first element), this is proportional to the total number of bits in the vector (self.len() * self.bit_width()).

Panics

Panics if index is out of bounds.

pub fn insert(&mut self, index: usize, element: T)

Inserts an element at index, shifting all elements after it to the right.

This operation is O(n), where n is the number of elements after index.

Panics

Panics if index is out of bounds or if the element is too large to be represented by the configured bit_width.

Complexity

This operation has a complexity of O(L), where L is the number of bits that need to be shifted. In the worst case (inserting at the beginning), this is proportional to the total number of bits in the vector (self.len() * self.bit_width()).

Panics

Panics if index is out of bounds or if the element is too large to be represented by the configured bit_width.

pub fn swap_remove(&mut self, index: usize) -> T

Removes an element at index and returns it, replacing it with the last element of the vector.

This operation is O(1) but does not preserve the order of elements.

Panics

Panics if index is out of bounds.

pub fn try_push(&mut self, value: T) -> Result<(), Error>

Appends an element to the vector, returning an error if the value doesn’t fit.

Errors

Returns Error::ValueTooLarge if the value cannot be represented by the configured bit_width.

pub fn extend_from_slice(&mut self, other: &[T])

Extends the vector with the elements from a slice.

Panics

Panics if any value in other does not fit within the bit_width.

impl<T, W, E, B> FixedVec<T, W, E, B>

where T: Storable<W>, W: Word, E: Endianness, B: AsRef<[W]> + AsMut<[W]>,

pub fn at_mut(&mut self, index: usize) -> Option<MutProxy<'_, T, W, E, B>>

Returns a mutable proxy for an element at index.

This allows for syntax like *vec.at_mut(i).unwrap() = new_value;.

Returns None if the index is out of bounds.

pub unsafe fn as_mut_limbs(&mut self) -> &mut [W]

Returns a mutable slice of the underlying storage words.

Safety

Modifying the returned slice is logically unsafe. Any change to the bits can violate the invariants of the FixedVec, leading to panics or incorrect results on subsequent method calls.

pub fn set(&mut self, index: usize, value: T)

Sets the value of the element at index.

Panics

Panics if index is out of bounds or if value is too large to be represented by the configured bit_width.

Examples

use compressed_intvec::fixed::{FixedVec, UFixedVec, BitWidth};

let data: &[u32] = &[10, 20, 30];
let mut vec: UFixedVec<u32> = FixedVec::builder().bit_width(BitWidth::Explicit(7)).build(data).unwrap();

vec.set(1, 99);
assert_eq!(vec.get(1), Some(99));

pub unsafe fn set_unchecked(&mut self, index: usize, value_w: W)

Sets the value of the element at index without bounds or value checking.

Safety

The caller must ensure that index is within bounds and that value_w fits within the configured bit_width. Failure to do so will result in data corruption or a panic.

pub fn try_set(&mut self, index: usize, value: T) -> Result<(), Error>

Sets the value of an element, returning an error if the value doesn’t fit.

Errors

Returns Error::ValueTooLarge if the value cannot be represented by the configured bit_width.

Panics

Panics if index is out of bounds.

pub fn chunks_mut(&mut self, chunk_size: usize) -> ChunksMut<'_, T, W, E, B>

Returns an iterator over non-overlapping, mutable chunks of the vector.

Panics

Panics if chunk_size is 0.

pub unsafe fn iter_mut_unchecked(&mut self) -> IterMutUnchecked<'_, T, W, E, B>

Returns an unchecked mutable iterator over the elements of the vector.

Safety

The caller must ensure that the iterator is not advanced beyond the vector’s length.

pub unsafe fn map_in_place_unchecked<F>(&mut self, f: F)

where F: FnMut(T) -> T,

Applies a function to all elements in place, without checking if the returned values fit within the bit_width.

Safety

The caller must ensure that the function f always returns a value that can be represented by self.bit_width() bits. Returning a value that is too large will result in data corruption.

pub fn map_in_place<F>(&mut self, f: F)

where F: FnMut(T) -> T,

Applies a function to all elements in the vector, modifying them in-place.

Panics

Panics if the function f returns a value that does not fit within the configured bit_width.

Examples

use compressed_intvec::fixed::{FixedVec, BitWidth, UFixedVec};

// Values up to 9*2=18, requires 5 bits. We must build with enough space.
let initial_data: Vec<u32> = (0..10).collect();
let mut vec: UFixedVec<u32> = FixedVec::builder()
    .bit_width(BitWidth::Explicit(5))
    .build(&initial_data)
    .unwrap();

vec.map_in_place(|x| x * 2);

for i in 0..vec.len() {
    assert_eq!(vec.get(i), Some(i as u32 * 2));
}

pub fn replace(&mut self, index: usize, value: T) -> T

Replaces the element at index with a new value, returning the old value.

Panics

Panics if index is out of bounds or if value does not fit within the configured bit_width.

pub fn swap(&mut self, a: usize, b: usize)

Swaps the elements at indices a and b.

Panics

Panics if a or b are out of bounds.

pub fn first_mut(&mut self) -> Option<MutProxy<'_, T, W, E, B>>

Returns a mutable proxy to the first element, or None if empty.

pub fn last_mut(&mut self) -> Option<MutProxy<'_, T, W, E, B>>

Returns a mutable proxy to the last element, or None if empty.

pub fn first(&self) -> Option<T>

Returns the first element of the vector, or None if empty.

pub fn last(&self) -> Option<T>

Returns the last element of the vector, or None if empty.

pub fn split_at_mut( &mut self, mid: usize, ) -> (FixedVecSlice<&mut Self>, FixedVecSlice<&mut Self>)

Splits the vector into two mutable slices at mid.

Panics

Panics if mid > len.

pub fn iter_mut(&mut self) -> IterMut<'_, T, W, E, B>

Returns a mutable iterator over the elements of the vector.

pub fn rotate_left(&mut self, mid: usize)

Rotates the elements of the vector in-place such that the element at mid becomes the first element.

Panics

Panics if mid > len.

pub fn rotate_right(&mut self, k: usize)

Rotates the elements of the vector in-place such that the element at len - k becomes the first element.

Panics

Panics if k > len.

pub fn fill(&mut self, value: T)

Fills the vector with the given value.

Panics

Panics if value does not fit in the configured bit_width.

pub fn fill_with<F>(&mut self, f: F)

where F: FnMut() -> T,

Fills the vector with values returned by a closure.

Panics

Panics if the closure returns a value that does not fit in the configured bit_width.

pub fn copy_from_slice( &mut self, src: &Self, src_range: Range<usize>, dest_index: usize, )

Copies a sequence of elements from a source FixedVec into this one.

Panics

Panics if the source and destination vectors do not have the same bit_width, or if the source or destination ranges are out of bounds.

Trait Implementations

impl<T: Clone + Storable<W>, W: Clone + Word, E: Clone + Endianness, B: Clone + AsRef<[W]>> Clone for FixedVec<T, W, E, B>

fn clone(&self) -> FixedVec<T, W, E, B>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Storable<W>, W, E: Endianness, B> CopyType for FixedVec<T, W, E, B>

where B: MemSize + AsRef<[W]>, usize: MemSize, W: MemSize + Word, PhantomData<(T, W, E)>: MemSize,

type Copy = False

impl<T: Debug + Storable<W>, W: Debug + Word, E: Debug + Endianness, B: Debug + AsRef<[W]>> Debug for FixedVec<T, W, E, B>

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

Formats the value using the given formatter.

impl<T, W, E> Default for FixedVec<T, W, E, Vec<W>>

where T: Storable<W>, W: Word, E: Endianness,

fn default() -> Self

Creates an empty FixedVec with a default bit_width of 1.

impl<T, W, E> Extend<T> for FixedVec<T, W, E, Vec<W>>

where T: Storable<W> + ToPrimitive, W: Word, E: Endianness,

fn extend<I: IntoIterator<Item = T>>(&mut self, iter: I)

Extends the vector with the contents of an iterator.

Panics

Panics if any value from the iterator does not fit within the configured bit_width.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<T> From<AtomicFixedVec<T>> for FixedVec<T, u64, LE, Vec<u64>>

where T: Storable<u64>,

fn from(atomic_vec: AtomicFixedVec<T>) -> Self

Creates a FixedVec from an owned AtomicFixedVec. This is a zero-copy operation that re-uses the allocated buffer.

impl<T, W, E> From<FixedVec<T, W, E>> for AtomicFixedVec<T>

where T: Storable<W> + Storable<u64>, W: Word, E: Endianness,

fn from(fixed_vec: FixedVec<T, W, E, Vec<W>>) -> Self

Creates an AtomicFixedVec from an owned FixedVec. This is a zero-copy operation that re-uses the allocated buffer.

impl<T, W, E> From<FixedVec<T, W, E>> for FixedVec<T, W, E, Box<[W]>>

where T: Storable<W>, W: Word, E: Endianness,

fn from(vec: FixedVec<T, W, E, Vec<W>>) -> Self

Converts a Vec-backed FixedVec into a Box<[]>-backed FixedVec.

impl<T, W, E> From<FixedVec<T, W, E, Box<[W]>>> for FixedVec<T, W, E, Vec<W>>

where T: Storable<W>, W: Word, E: Endianness,

fn from(vec: FixedVec<T, W, E, Box<[W]>>) -> Self

Converts a Box<[]>-backed FixedVec into a Vec-backed FixedVec.

impl<T, W, E> FromIterator<T> for FixedVec<T, W, E, Vec<W>>

where T: Storable<W>, W: Word, E: Endianness, BufBitWriter<E, MemWordWriterVec<W, Vec<W>>>: BitWrite<E, Error = Infallible>,

fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self

Creates a FixedVec by collecting elements from an iterator.

The bit width is determined automatically using the BitWidth::Minimal strategy. This requires collecting the iterator into a temporary Vec<T> to analyze its contents before compression.

Memory Usage

Because this implementation must first collect all items into a temporary Vec<T> to determine the optimal bit_width, it may lead to a temporary peak in memory usage that is roughly double the size of the uncompressed data.

For very large datasets where this memory overhead is a concern, it is recommended to use FixedVec::from_iter_builder instead. The builder allows for streaming construction but requires the bit_width to be specified manually.

Examples

use compressed_intvec::fixed::{FixedVec, UFixedVec};

let data = 0u32..100;
let vec: UFixedVec<u32> = data.collect();

assert_eq!(vec.len(), 100);
assert_eq!(vec.get(50), Some(50));

impl<'a, T, W, E, B> IntoIterator for &'a FixedVec<T, W, E, B>

where T: Storable<W>, W: Word, E: Endianness, B: AsRef<[W]>,

Allows iterating over a borrowed FixedVec (e.g., for val in &my_vec).

type Item = T

The type of the elements being iterated over.

type IntoIter = FixedVecIter<'a, T, W, E, B>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T, W, E> IntoIterator for FixedVec<T, W, E, Vec<W>>

where T: Storable<W> + 'static, W: Word, E: Endianness,

Allows iterating over an owned FixedVec, consuming it.

fn into_iter(self) -> Self::IntoIter

Consumes the vector and returns an iterator over its elements.

type Item = T

The type of the elements being iterated over.

type IntoIter = FixedVecIntoIter<'static, T, W, E>

Which kind of iterator are we turning this into?

impl<T: Storable<W>, W, E: Endianness, B> MemDbgImpl for FixedVec<T, W, E, B>

where B: MemDbgImpl + AsRef<[W]>, usize: MemDbgImpl, W: MemDbgImpl + Word, PhantomData<(T, W, E)>: MemDbgImpl,

fn _mem_dbg_rec_on( &self, _memdbg_writer: &mut impl Write, _memdbg_total_size: usize, _memdbg_max_depth: usize, _memdbg_prefix: &mut String, _memdbg_is_last: bool, _memdbg_flags: DbgFlags, ) -> Result

fn _mem_dbg_depth_on( &self, writer: &mut impl Write, total_size: usize, max_depth: usize, prefix: &mut String, field_name: Option<&str>, is_last: bool, padded_size: usize, flags: DbgFlags, ) -> Result<(), Error>

impl<T: Storable<W>, W, E: Endianness, B> MemSize for FixedVec<T, W, E, B>

where B: MemSize + AsRef<[W]>, usize: MemSize, W: MemSize + Word, PhantomData<(T, W, E)>: MemSize,

fn mem_size(&self, _memsize_flags: SizeFlags) -> usize

Returns the (recursively computed) overall memory size of the structure in bytes.

impl<T, W, E, B, T2> PartialEq<&[T2]> for FixedVec<T, W, E, B>

where T: Storable<W> + PartialEq<T2>, W: Word, E: Endianness, B: AsRef<[W]>, T2: Clone,

Implements PartialEq for comparing a FixedVec with a standard slice.

fn eq(&self, other: &&[T2]) -> bool

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

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

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

impl<T, W, E, B, B2, V> PartialEq<&FixedVec<T, W, E, B2>> for FixedVecSlice<V>

where T: Storable<W> + PartialEq, W: Word, E: Endianness, B: AsRef<[W]>, B2: AsRef<[W]>, V: Deref<Target = FixedVec<T, W, E, B>>,

fn eq(&self, other: &&FixedVec<T, W, E, B2>) -> bool

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

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

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

impl<T, W, E, B, B2> PartialEq<FixedVec<T, W, E, B2>> for FixedVec<T, W, E, B>

where T: Storable<W> + PartialEq, W: Word, E: Endianness, B: AsRef<[W]>, B2: AsRef<[W]>,

fn eq(&self, other: &FixedVec<T, W, E, B2>) -> bool

Checks for equality between two FixedVec instances.

It first checks len and bit_width, then the underlying storage.

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

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

impl<T, W, E, B, B2, V> PartialEq<FixedVec<T, W, E, B2>> for FixedVecSlice<V>

where T: Storable<W> + PartialEq, W: Word, E: Endianness, B: AsRef<[W]>, B2: AsRef<[W]>, V: Deref<Target = FixedVec<T, W, E, B>>,

fn eq(&self, other: &FixedVec<T, W, E, B2>) -> bool

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

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

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

impl<T, W, E, B, B2, V> PartialEq<FixedVecSlice<V>> for FixedVec<T, W, E, B>

where T: Storable<W> + PartialEq, W: Word, E: Endianness, B: AsRef<[W]>, B2: AsRef<[W]>, V: Deref<Target = FixedVec<T, W, E, B2>>,

fn eq(&self, other: &FixedVecSlice<V>) -> bool

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

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

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

impl<'a, T> TryFrom<&'a [T]> for FixedVec<T, <T as DefaultParams>::W, <T as DefaultParams>::E>

where T: Storable<<T as DefaultParams>::W> + DefaultParams, <T as DefaultParams>::W: Word, <T as DefaultParams>::E: Endianness, BufBitWriter<<T as DefaultParams>::E, MemWordWriterVec<<T as DefaultParams>::W, Vec<<T as DefaultParams>::W>>>: BitWrite<<T as DefaultParams>::E, Error = Infallible>,

fn try_from(slice: &'a [T]) -> Result<Self, Self::Error>

Creates a FixedVec from a slice using BitWidth::Minimal and default parameters.

This is a convenience method equivalent to FixedVec::builder().build(slice). It uses the default Word (usize) and Endianness (LE) associated with the element type T.

Examples

use compressed_intvec::fixed::{UFixedVec, SFixedVec};
use std::convert::TryFrom;

// For unsigned types
let data_u: &[u32] = &[10, 20, 30];
let vec_u = UFixedVec::<u32>::try_from(data_u).unwrap();
assert_eq!(vec_u.bit_width(), 5);

// For signed types
let data_s: &[i16] = &[-10, 0, 10];
let vec_s = SFixedVec::<i16>::try_from(data_s).unwrap();
assert_eq!(vec_s.bit_width(), 5);

type Error = Error

The type returned in the event of a conversion error.