Struct Arena 

pub struct Arena<T: ?Sized, Storage = T, H = DefaultBuildHasher, I = u32> { /* private fields */ }

Interning arena for values of type T, storing them with the given Storage type (that needs to be Sized).

For Sized values, Storage = T is a good default that incurs no overhead. For non-Sized values such as dyn Trait, you need to specify a Sized storage type, such as Box<dyn Trait>.

Implementations

impl<T, Storage, H, I> Arena<T, Storage, H, I>

where T: Ord + ?Sized, Storage: Borrow<T>, I: Index,

pub fn sort(&self) -> Mapping<I>

Returns a sorted mapping of the items in this arena.

impl<T: ?Sized, Storage, H, I> Arena<T, Storage, H, I>

where I: Index,

pub fn identity(&self) -> Mapping<I>

Returns the identity mapping of the items in this arena.

This can be useful to rehash the arena.

pub fn retain( &self, filter: impl Fn(Interned<T, Storage, H, I>) -> bool, ) -> Mapping<I>

Returns a mapping to build an arena containing only the items of this arena that satisfy the given predicate.

pub fn retain_values( &self, values: impl Iterator<Item = Interned<T, Storage, H, I>>, ) -> Mapping<I>

Available on crate feature retain only.

Returns a mapping to build an arena containing only the given items.

See also retain_builder() if you need a more flexible way of adding items to retain.

pub fn retain_builder(&self) -> RetainBuilder<T, Storage, H, I>

Available on crate feature retain only.

Returns a builder allowing to select items to retain, and create an arena containing only these.

impl<T, Storage, H, I> Arena<T, Storage, H, I>

where T: Eq + Hash + ?Sized, Storage: Borrow<T> + Clone, I: Index,

pub fn map(&self, mapping: &ReverseMapping<I>) -> Self

where H: Default + BuildHasher,

Returns a re-ordered version of this arena based on the given mapping.

See also map_rehash() to use a different hash function in the resulting arena.

pub fn map_rehash<HH>( &self, mapping: &ReverseMapping<I>, ) -> Arena<T, Storage, HH, I>

where HH: Default + BuildHasher,

Returns a re-ordered version of this arena based on the given mapping.

See also map() if the resulting arena uses the same hash function.

pub fn map2( &self, mapping: &ReverseMapping<I>, f: impl Fn(&T) -> Storage, ) -> Self

where H: Default + BuildHasher,

Returns a re-ordered version of this arena based on the given mapping, where each item is additionally transformed according to the given function f.

The transformation function should be injective, i.e. different inputs should map to different outputs. Otherwise a value may appear twice in the resulting arena.

See also map2_rehash() to use a different hash function in the resulting arena.

pub fn map2_rehash<HH>( &self, mapping: &ReverseMapping<I>, f: impl Fn(&T) -> Storage, ) -> Arena<T, Storage, HH, I>

where HH: Default + BuildHasher,

Returns a re-ordered version of this arena based on the given mapping, where each item is additionally transformed according to the given function f.

The transformation function should be injective, i.e. different inputs should map to different outputs. Otherwise a value may appear twice in the resulting arena.

See also map2() if the resulting arena uses the same hash function.

impl<T: ?Sized, Storage, H, I> Arena<T, Storage, H, I>

where H: Default,

pub fn with_capacity(len: usize) -> Self

Creates a new arena with pre-allocated space to store at least len values of type T.

impl<T: ?Sized, Storage, H, I> Arena<T, Storage, H, I>

pub fn len(&self) -> usize

Returns the number of values in this arena.

Note that because Arena is a concurrent data structure, this is only a snapshot as viewed by this thread, and the result may change if other threads are inserting values.

pub fn is_empty(&self) -> bool

Checks if this arena is empty.

Note that because Arena is a concurrent data structure, this is only a snapshot as viewed by this thread, and the result may change if other threads are inserting values.

pub fn snapshot(&self) -> Snapshot<'_, T, Storage, H, I>

Returns a snapshot of this arena.

Note that because Arena is a concurrent data structure, this is only a snapshot as viewed by this thread.

Snapshots can be diffed into a SnapshotDiff, which is useful to serialize an arena incrementally as values are added to it.

impl<T: ?Sized, Storage, H, I> Arena<T, Storage, H, I>

where Storage: Borrow<T>, I: Index,

pub fn iter(&self) -> impl ExactSizeIterator<Item = &T>

Available on crate feature raw only.

Returns an iterator over all items in this arena, in indexing order.

Note that because Arena is a concurrent data structure, this is only a snapshot. Once this iterator has been created, for performance reasons it will not iterate over items added afterwards, even on the same thread.

impl<T, Storage, H, I> Arena<T, Storage, H, I>

where T: Eq + Hash + ?Sized, Storage: Borrow<T>, H: BuildHasher, I: Index,

pub fn find(&self, value: &T) -> Option<Interned<T, Storage, H, I>>

Returns the given value’s Interned handle if it is already interned.

Otherwise, this simply returns None without adding the value to this arena.

See also find_mut(), which is more efficient if you hold a mutable reference to this arena as it avoids acquiring locks.

pub fn find_mut(&mut self, value: &T) -> Option<Interned<T, Storage, H, I>>

Returns the given value’s Interned handle if it is already interned.

Otherwise, this simply returns None without adding the value to this arena.

Contrary to find(), no locks are held internally because this function already takes an exclusive mutable reference to this arena.

impl<T, Storage, H, I> Arena<T, Storage, H, I>

where T: Eq + Hash + ?Sized, Storage: Borrow<T>, H: BuildHasher, I: Index,

pub fn push_mut(&mut self, value: Storage) -> I

Available on crate feature raw only.

Unconditionally push a value, without validating that it’s already interned.

Calling this function multiple times with the same value doesn’t violate safety, but the value will be stored multiple times in the arena.

impl<T: ?Sized, Storage, H, I> Arena<T, Storage, H, I>

where Storage: GetSize,

pub fn print_summary(&self, prefix: &str, title: &str, total_bytes: usize)

Available on crate features debug and std only.

Prints a summary of the storage used by this arena to stdout.

impl<T: ?Sized, Storage, H, I> Arena<T, Storage, H, I>

pub fn references(&self) -> usize

Available on crate feature debug only.

Returns the total number of references to items in this arena.

The underlying counter is incremented each time a value is interned, whether it was already previously in the arena or not.

impl<T, Storage, H, I> Arena<T, Storage, H, I>

where T: Eq + Hash + ?Sized, Storage: Borrow<T>, H: BuildHasher, I: Index,

pub fn intern( &self, value: impl Borrow<T> + Into<Storage>, ) -> Interned<T, Storage, H, I>

Available on crate feature sync only.

Interns the given value in this arena.

If the value was already interned in this arena, it will simply be borrowed to retrieve its interning index. Otherwise it will then be converted to store it into the arena.

See also intern_mut(), which is more efficient if you hold a mutable reference to this arena as it avoids acquiring locks.

pub fn intern_mut( &mut self, value: impl Borrow<T> + Into<Storage>, ) -> Interned<T, Storage, H, I>

Interns the given value in this arena.

If the value was already interned in this arena, it will simply be borrowed to retrieve its interning index. Otherwise it will then be converted to store it into the arena.

Contrary to intern(), no locks are held internally because this function already takes an exclusive mutable reference to this arena.

impl<T: ?Sized, Storage, H, I> Arena<T, Storage, H, I>

where Storage: Clone, I: Index,

pub fn lookup(&self, interned: Interned<T, Storage, H, I>) -> Storage

Retrieves the given Interned value from this arena.

The caller is responsible for ensuring that the same arena was used to intern this value, otherwise an arbitrary value will be returned or a panic will happen.

See also lookup_ref() if you only need a reference.

impl<T: ?Sized, Storage, H, I> Arena<T, Storage, H, I>

where Storage: Borrow<T>, I: Index,

pub fn lookup_ref(&self, interned: Interned<T, Storage, H, I>) -> &T

Retrieves a reference to the given Interned value from this arena.

The caller is responsible for ensuring that the same arena was used to intern this value, otherwise an arbitrary value will be returned or a panic will happen.

See also lookup() if you need an owned value.

impl<T, Storage, H, I> Arena<T, Storage, H, I>

where T: Eq + Hash + ?Sized, Storage: Borrow<T>, H: BuildHasher, I: Index,

pub fn truncate(&mut self, snapshot: SnapshotMark<T, Storage, H, I>)

Truncates this interner back to the given snapshot mark.

This is a no-op if the snapshot mark is larger than this interner (for example because the interner was already truncated to a smaller snapshot in the meantime).

Trait Implementations

impl<T, Storage, H, I> Clone for Arena<T, Storage, H, I>

where T: Eq + Hash + ?Sized, Storage: Borrow<T> + Clone, H: Default + BuildHasher, I: Index,

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T, Storage, H, I> Debug for Arena<T, Storage, H, I>

where T: Debug + ?Sized, Storage: Borrow<T>, I: Index,

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

Formats the value using the given formatter.

impl<T: ?Sized, Storage, H, I> Default for Arena<T, Storage, H, I>

where H: Default,

fn default() -> Self

Returns the “default value” for a type.

impl<'de, T, Storage, H, I> Deserialize<'de> for Arena<T, Storage, H, I>

where T: Eq + Hash + ?Sized, Storage: Borrow<T> + Deserialize<'de>, H: Default + BuildHasher, I: Index,

Available on crate feature serde only.

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T, Storage, H, I> Eq for Arena<T, Storage, H, I>

where T: Eq + ?Sized, Storage: Borrow<T>, I: Index,

impl<T: ?Sized, Storage, H, I> GetSize for Arena<T, Storage, H, I>

where Storage: GetSize, I: GetSize,

Available on crate feature get-size2 only.

fn get_heap_size_with_tracker<Tr: GetSizeTracker>( &self, tracker: Tr, ) -> (usize, Tr)

Determines how many bytes this object occupies inside the heap while using a tracker.

fn get_stack_size() -> usize

Determines how may bytes this object occupies inside the stack.

fn get_heap_size(&self) -> usize

Determines how many bytes this object occupies inside the heap.

fn get_size(&self) -> usize

Determines the total size of the object.

fn get_size_with_tracker<T>(&self, tracker: T) -> (usize, T)

where T: GetSizeTracker,

Determines the total size of the object while using a tracker.

impl<T, Storage, H, I> PartialEq for Arena<T, Storage, H, I>

where T: Eq + ?Sized, Storage: Borrow<T>, I: Index,

fn eq(&self, other: &Self) -> bool

Equality operator ==.

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

Inequality operator !=.

impl<T, Storage, H, I> Schema for Arena<T, Storage, H, I>

where T: Schema + ?Sized,

Available on crate feature postcard-schema only.

const SCHEMA: &'static NamedType

A recursive data structure that describes the schema of the given type.

impl<T, Storage, H, I> Serialize for Arena<T, Storage, H, I>

where T: Serialize + ?Sized, Storage: Borrow<T>, I: Index,

Available on crate feature serde only.

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.