pub struct Capacity<const N: usize> { /* private fields */ }
Expand description
Defines the capacity for a data structure, considering the non-empty nature of data structures in this crate.
Many data structures provide a with_capacity
or similar constructor to enable pre-allocation.
This has the potential to become confusing for users of a non-empty data structure:
is this capacity the full capacity, or the additional capacity?
To prevent this confusion, this crate uses Capacity
for these types of methods.
N
constant
The N
constant is the capacity size of the statically sized portion of the data structure.
For example, unzero::Vec<T>
statically stores one T
, so its value for N
is 1.
Kinds of capacity
total
: Total capacity means “this is the total size of the data structure, including the statically sized portion maintained by the non-empty data structure”.dynamic
: Dynamic capacity means “this is the size of the dynamic portion of the data structure”. Most non-empty data structures are backed by some other dynamically growable structure, this size represents the size of that structure directly.
For example, consider the following cases (Vec
in the table below refers to [unempty::Vec
]):
Constructor | Total Capacity | Dynamic Capacity |
---|---|---|
Vec::new(()) | 1 | 0 |
Vec::with_capacity(10.into()) | 10 | 9 |
let v = Vec::new(()); v.push(()); | 2 | 1 |
From
conversions
The From
conversions provided for this data structure take the more conservative route and
treat the original value being converted from as total capacity.
Implementations
sourceimpl<const N: usize> Capacity<N>
impl<const N: usize> Capacity<N>
sourcepub fn new_total(capacity: usize) -> Self
pub fn new_total(capacity: usize) -> Self
Create a Capacity
with the provided total capacity.
If the provided total capacity is less than N
, it is increased to N
.
For definitions on kinds of capacity, see [Kinds of capacity].
sourcepub fn new_dynamic(capacity: usize) -> Self
pub fn new_dynamic(capacity: usize) -> Self
Create a Capacity
with the provided capacity for the dynamic portion of the data structure.
If the provided dynamic capacity would cause an integer overflow when accounting for N
,
the dynamic capacity is reduced to usize::MAX - N
.
For definitions on kinds of capacity, see [Kinds of capacity].
sourcepub fn total(&self) -> usize
pub fn total(&self) -> usize
Reference the total capacity specified.
For definitions on kinds of capacity, see [Kinds of capacity].
Trait Implementations
sourceimpl<const N: usize> Ord for Capacity<N>
impl<const N: usize> Ord for Capacity<N>
1.21.0 · sourcefn max(self, other: Self) -> Self
fn max(self, other: Self) -> Self
Compares and returns the maximum of two values. Read more
1.21.0 · sourcefn min(self, other: Self) -> Self
fn min(self, other: Self) -> Self
Compares and returns the minimum of two values. Read more
1.50.0 · sourcefn clamp(self, min: Self, max: Self) -> Self where
Self: PartialOrd<Self>,
fn clamp(self, min: Self, max: Self) -> Self where
Self: PartialOrd<Self>,
Restrict a value to a certain interval. Read more
sourceimpl<const N: usize> PartialEq<Capacity<N>> for Capacity<N>
impl<const N: usize> PartialEq<Capacity<N>> for Capacity<N>
sourceimpl<const N: usize> PartialOrd<Capacity<N>> for Capacity<N>
impl<const N: usize> PartialOrd<Capacity<N>> for Capacity<N>
sourcefn partial_cmp(&self, other: &Capacity<N>) -> Option<Ordering>
fn partial_cmp(&self, other: &Capacity<N>) -> Option<Ordering>
This method returns an ordering between self
and other
values if one exists. Read more
1.0.0 · sourcefn lt(&self, other: &Rhs) -> bool
fn lt(&self, other: &Rhs) -> bool
This method tests less than (for self
and other
) and is used by the <
operator. Read more
1.0.0 · sourcefn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
impl<const N: usize> Copy for Capacity<N>
impl<const N: usize> Eq for Capacity<N>
impl<const N: usize> StructuralEq for Capacity<N>
impl<const N: usize> StructuralPartialEq for Capacity<N>
Auto Trait Implementations
impl<const N: usize> RefUnwindSafe for Capacity<N>
impl<const N: usize> Send for Capacity<N>
impl<const N: usize> Sync for Capacity<N>
impl<const N: usize> Unpin for Capacity<N>
impl<const N: usize> UnwindSafe for Capacity<N>
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more