Struct BSTSmallArray

#[repr(C)]
pub struct BSTSmallArray<T, const N: usize = 1, A = TESGlobalAlloc>
where
    A: SelflessAllocator,
{ /* private fields */ }

Use stack while within the specified size, and use heap if it is larger.

This is the same purpose as smallvec crate and other optimizations, except that the memory layout is for TES.

It is effective when most of the memory can be fit in the stack, except for some exceptions, but it slows down the process if there are frequent fallbacks to the heap.

• smallvec crate

• N: element length (not bytes size)

Examples

let mut array = BSTSmallArray::<i32, 1>::new();
array.push(1); // push on stack.
array.push(2); // change to heap.
assert_eq!(array[0], 1);
assert_eq!(array[1], 2);
assert_eq!(array.len(), 2);
array.clear(); // reuse heap. grow to capacity 4.
assert_eq!(array.len(), 0);
assert_eq!(array.capacity(), 4); // Capacity is preserved

Implementations

impl<T, const N: usize, A> BSTSmallArray<T, N, A>

where A: SelflessAllocator,

pub const fn new() -> Self

Creates a new, empty BSTSmallArray<T, N, A> with the specified allocator.

The array will not allocate until elements are pushed.

Example

let array = BSTSmallArray::<i32, 10>::new();
assert!(array.is_empty());

pub const fn len(&self) -> usize

Returns the number of elements in the array.

This is also referred to as the array’s “length”.

Example

let array = BSTSmallArray::<i32, 10>::new();
assert_eq!(array.len(), 0);

pub const fn is_empty(&self) -> bool

Returns true if the array contains no elements.

Example

let array = BSTSmallArray::<i32, 10>::new();
assert!(array.is_empty());

pub const fn capacity(&self) -> usize

Returns the total number of elements the array can hold without reallocating.

This is the allocated capacity, which may be larger than the current length.

Example

let mut array = BSTSmallArray::<i32, 10>::new();
assert!(array.capacity() == 10); // stack size

pub fn shrink_to_fit(&mut self)

Shrinks the capacity of the array as much as possible.

It will drop any excess capacity not used by the current elements.

Examples

let mut array = BSTSmallArray::<_, 4>::new(); // auto i32
array.push(1);
array.push(2);
array.push(3);
array.push(4);
array.push(5); // change to heap
assert_eq!(array.len(), 5);
array.shrink_to_fit();
assert!(array.capacity() == array.len());

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

Appends an element to the back of the array.

Panics

Panics if the array is at fixed capacity and cannot grow.

Example

let mut array = BSTSmallArray::<i32, 10>::new();
array.push(5);
assert_eq!(array[0], 5);

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

Removes the last element from the array and returns it, or None if it’s empty.

Example

let mut array = BSTSmallArray::<i32, 10>::new();
array.push(1);
assert_eq!(array.pop(), Some(1));
assert_eq!(array.pop(), None);

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

Returns a reference to the element at the given index, if it exists.

Example

let mut array = BSTSmallArray::<i32, 10>::new();
array.push(42);
assert_eq!(array.get(0), Some(&42));
assert_eq!(array.get(1), None);

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

Returns a mutable reference to the element at the given index, if it exists.

Example

let mut array = BSTSmallArray::<i32, 1>::new();
array.push(10);
if let Some(x) = array.get_mut(0) {
    *x += 1;
}
assert_eq!(array[0], 11);

pub fn clear(&mut self)

Clears the array, removing all elements but preserving the capacity.

Examples

let mut array = BSTSmallArray::<i32, 1>::new();
array.push(1); // push on stack.
array.push(2); // change to heap.
assert_eq!(array.len(), 2);
array.clear(); // reuse heap.
assert_eq!(array.len(), 0);
assert_eq!(array.capacity(), 4); // Capacity is preserved

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

Returns a non null pointer of the array’s buffer.

pub fn as_const_non_null_ptr(&self) -> Option<ConstNonNull<T>>

Returns a non null pointer of the array’s buffer.

pub fn contains(&self, value: &T) -> bool

where T: PartialEq,

Checks if the array contains the given element.

Returns true if the element is present in the array, and false otherwise.

Examples

let mut array = BSTSmallArray::<i32, 10>::new();
array.push(1);
array.push(2);
assert!(array.contains(&1));
assert!(!array.contains(&3));

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

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

Retains only the elements that satisfy the predicate.

This method takes a closure that accepts an element of the array and returns a boolean. Elements for which the closure returns true will be kept, while elements for which it returns false will be removed.

Examples

let mut array = BSTSmallArray::<i32, 10>::new();
array.push(1);
array.push(2);
array.push(3);
array.retain(|&x| x > 1);
assert_eq!(array.len(), 2);
assert!(array.contains(&2));
assert!(array.contains(&3));

Panics

array ptr is null

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

where T: Clone,

Resizes the array to the specified length.

If the array is resized to a larger length, the new elements will be initialized using the default constructor for T. If the array is resized to a smaller length, elements at the end will be dropped.

Examples

let mut array = BSTSmallArray::<i32, 10>::new();
array.push(1);
array.push(2);
array.resize(5, 0);
assert_eq!(array.len(), 5);
assert_eq!(array[3], 0);

pub fn drain<R>(&mut self, range: R) -> BSTDrain<'_, T, N, A>

where R: RangeBounds<usize>,

Removes a range of elements from the array, returning them as a vector.

This method removes the elements within the specified range and returns them as a Vec<T>. The range must be within the bounds of the array.

Examples

let mut array = BSTSmallArray::<i32, 10>::new();
array.push(1);
array.push(2);
array.push(3);
array.push(4);
array.push(5);
let drained = array.drain(0..2);
assert_eq!(drained.collect::<Vec<_>>(), vec![1, 2]);
assert_eq!(array.len(), 3);
assert_eq!(array[0], 3);
assert_eq!(array[1], 4);
assert_eq!(array[2], 5);

Panics

Panics if the range is out of bounds.

pub fn as_slice(&self) -> &[T]

Returns a slice of all elements in the array.

pub fn as_mut_slice(&mut self) -> &mut [T]

Returns a mutable slice of all elements in the array.

pub const fn iter(&self) -> BSTSmallArrayIterator<'_, T, N, A>

Returns an iterator over the elements of the array.

This iterator yields references to the elements in the array.

Examples

let mut array = BSTSmallArray::<i32, 10>::new();
array.push(1);
array.push(2);
let sum: i32 = array.iter().sum();
assert_eq!(sum, 3);

Trait Implementations

impl<T: Clone, const N: usize, A> Clone for BSTSmallArray<T, N, A>

where A: SelflessAllocator + Clone,

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T, const N: usize, A> Debug for BSTSmallArray<T, N, A>

where T: Debug, A: SelflessAllocator,

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

Formats the value using the given formatter.

impl<T, const N: usize> Default for BSTSmallArray<T, N>

fn default() -> Self

Returns the “default value” for a type.

impl<T, const N: usize, A> Drop for BSTSmallArray<T, N, A>

where A: SelflessAllocator,

fn drop(&mut self)

Executes the destructor for this type.

impl<T, const N: usize, A> Extend<T> for BSTSmallArray<T, N, A>

where A: SelflessAllocator,

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

Extends a collection with the contents of an iterator.

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, const N: usize, A> Hash for BSTSmallArray<T, N, A>

where T: Hash, A: SelflessAllocator,

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T, const N: usize, A> Index<usize> for BSTSmallArray<T, N, A>

where A: SelflessAllocator,

type Output = T

The returned type after indexing.

fn index(&self, index: usize) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<T, const N: usize, A> IndexMut<usize> for BSTSmallArray<T, N, A>

where A: SelflessAllocator,

fn index_mut(&mut self, index: usize) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<'a, T, const N: usize, A> IntoIterator for &'a BSTSmallArray<T, N, A>

where A: SelflessAllocator,

type Item = &'a T

The type of the elements being iterated over.

type IntoIter = BSTSmallArrayIterator<'a, T, N, A>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, T, const N: usize, A> IntoIterator for &'a mut BSTSmallArray<T, N, A>

where A: SelflessAllocator,

type Item = &'a mut T

The type of the elements being iterated over.

type IntoIter = BSTSmallArrayIterMut<'a, T, N, A>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T, const N: usize, A> IntoIterator for BSTSmallArray<T, N, A>

where A: SelflessAllocator,

type Item = T

The type of the elements being iterated over.

type IntoIter = BSTSmallArrayIntoIterator<T, N, A>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T, const N: usize, A> Ord for BSTSmallArray<T, N, A>

where T: Ord, A: SelflessAllocator,

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<T, const N: usize, A> PartialEq<&[T]> for BSTSmallArray<T, N, A>

where T: PartialEq, A: SelflessAllocator,

fn eq(&self, other: &&[T]) -> 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, const N: usize, A> PartialEq<Vec<T>> for BSTSmallArray<T, N, A>

where T: PartialEq, A: SelflessAllocator,

fn eq(&self, other: &Vec<T>) -> 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, const N: usize, A> PartialEq for BSTSmallArray<T, N, A>

where T: PartialEq, A: SelflessAllocator,

fn eq(&self, other: &Self) -> 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, const N: usize, A> PartialOrd for BSTSmallArray<T, N, A>

where T: PartialOrd, A: SelflessAllocator,

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T, const N: usize, A> Eq for BSTSmallArray<T, N, A>

where T: Eq, A: SelflessAllocator,