Struct Capacity

pub struct Capacity<const N: usize> { /* private fields */ }

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

impl<const N: usize> Capacity<N>

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].

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].

pub fn total(&self) -> usize

Reference the total capacity specified.

For definitions on kinds of capacity, see [Kinds of capacity].

pub fn dynamic(&self) -> usize

Reference the dynamic capacity specified.

For definitions on kinds of capacity, see [Kinds of capacity].

pub fn sizeof_n() -> usize

Reference the size of N.

Trait Implementations

impl<const N: usize> Clone for Capacity<N>

fn clone(&self) -> Capacity<N>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<const N: usize> Debug for Capacity<N>

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

Formats the value using the given formatter.

impl<const N: usize> Default for Capacity<N>

fn default() -> Self

Returns the “default value” for a type.

impl<const N: usize> Display for Capacity<N>

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

Formats the value using the given formatter.

impl<I, const N: usize> From<I> for Capacity<N>

where I: Into<usize>,

fn from(total_capacity: I) -> Self

Converts to this type from the input type.

impl<const N: usize> Hash for Capacity<N>

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<const N: usize> Ord for Capacity<N>

fn cmp(&self, other: &Capacity<N>) -> 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<const N: usize> PartialEq for Capacity<N>

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

fn partial_cmp(&self, other: &Capacity<N>) -> 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<const N: usize> Copy for Capacity<N>

impl<const N: usize> Eq for Capacity<N>

impl<const N: usize> StructuralPartialEq for Capacity<N>