Struct ArenaStr 

pub struct ArenaStr<H = DefaultBuildHasher, I = u32> { /* private fields */ }

Interning arena for strings.

Implementations

impl<H, I> ArenaStr<H, I>

where I: Index,

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

Returns a sorted mapping of the items in this arena.

pub fn retain(&self, filter: impl Fn(InternedStr<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 = InternedStr<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) -> RetainStrBuilder<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<H, I> ArenaStr<H, I>

where 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>) -> ArenaStr<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.

impl<H, I> ArenaStr<H, I>

where H: Default, I: Index,

pub fn with_capacity(strings: usize, bytes: usize) -> Self

Creates a new arena with pre-allocated space to store at least the given number of strings, totalling the given number of bytes.

Panics

This function panics if the capacity exceeds the maximum allocation size for an arena indexed by I. Use try_with_capacity for a fallible API.

pub fn try_with_capacity(strings: usize, bytes: usize) -> Option<Self>

Creates a new arena with pre-allocated space to store at least the given number of strings, totalling the given number of bytes.

This returns None if the capacity exceeds the maximum allocation size for an arena indexed by I.

impl<H, I> ArenaStr<H, I>

pub fn strings(&self) -> usize

Returns the number of strings in this arena.

Note that because ArenaStr 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 bytes(&self) -> usize

Returns the total number of bytes in this arena.

Note that because ArenaStr 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 ArenaStr 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) -> SnapshotStr<'_, H, I>

Returns a snapshot of this arena.

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

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

impl<H, I: Index> ArenaStr<H, I>

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

Available on crate feature raw only.

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

Note that because ArenaStr 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.

If you only need to access byte slices, iter_bytes() may be more efficient.

pub fn iter_bytes(&self) -> impl ExactSizeIterator<Item = &[u8]>

Available on crate feature raw only.

Returns an iterator over all strings (viewed as byte slices) in this arena, in indexing order.

Note that because ArenaStr 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<H, I> ArenaStr<H, I>

where H: BuildHasher, I: Index,

pub fn find(&self, value: &str) -> Option<InternedStr<H, I>>

Returns the given string’s InternedStr handle if it is already interned.

Otherwise, this simply returns None without adding the string 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: &str) -> Option<InternedStr<H, I>>

Returns the given string’s InternedStr handle if it is already interned.

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

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

pub fn push_mut(&mut self, value: &str) -> 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<H, I> ArenaStr<H, I>

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<H, I> ArenaStr<H, I>

pub fn references(&self) -> usize

Available on crate feature debug only.

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

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

impl<H, I> ArenaStr<H, I>

where H: BuildHasher, I: Index,

pub fn intern(&self, value: &str) -> InternedStr<H, I>

Available on crate feature sync only.

Interns the given value in this arena.

If the value was already interned in this arena, its interning index will simply be returned. Otherwise it will be stored 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.

Panics

This function panics if the arena is full (based on the index type I). Use try_intern() for a fallible API.

pub fn try_intern(&self, value: &str) -> Option<InternedStr<H, I>>

Available on crate feature sync only.

Interns the given value in this arena.

If the value was already interned in this arena, its interning index will simply be returned. Otherwise it will be stored into the arena.

This returns None if the arena is full (based on the index type I).

See also try_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: &str) -> InternedStr<H, I>

Interns the given value in this arena.

If the value was already interned in this arena, its interning index will simply be returned. Otherwise it will be stored into the arena.

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

Panics

This function panics if the arena is full (based on the index type I). Use try_intern_mut() for a fallible API.

pub fn try_intern_mut(&mut self, value: &str) -> Option<InternedStr<H, I>>

Interns the given value in this arena.

If the value was already interned in this arena, its interning index will simply be returned. Otherwise it will be stored into the arena.

This returns None if the arena is full (based on the index type I).

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

impl<H, I: Index> ArenaStr<H, I>

pub fn lookup(&self, interned: InternedStr<H, I>) -> &str

Retrieves the given InternedStr 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.

If you only need to access the bytes, lookup_bytes() may be more efficient.

Panics

This function panics if the interned handle is out of bounds for this arena, for example because the arena was truncated, or because the interned handle was deserialized from untrusted data. Use try_lookup for a fallible API.

pub fn try_lookup(&self, interned: InternedStr<H, I>) -> Option<&str>

Retrieves the given InternedStr 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.

This returns None if the interned handle is out of bounds for this arena, for example because the arena was truncated, or because the interned handle was deserialized from untrusted data.

If you only need to access the bytes, try_lookup_bytes() may be more efficient.

pub fn lookup_bytes(&self, interned: InternedStr<H, I>) -> &[u8]

Retrieves the bytes for the given InternedStr 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.

Panics

This function panics if the interned handle is out of bounds for this arena, for example because the arena was truncated, or because the interned handle was deserialized from untrusted data. Use try_lookup_bytes for a fallible API.

pub fn try_lookup_bytes(&self, interned: InternedStr<H, I>) -> Option<&[u8]>

Retrieves the bytes for the given InternedStr 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.

This returns None if the interned handle is out of bounds for this arena, for example because the arena was truncated, or because the interned handle was deserialized from untrusted data.

impl<H, I> ArenaStr<H, I>

where H: BuildHasher, I: Index,

pub fn truncate(&mut self, snapshot: SnapshotStrMark<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<H, I> Clone for ArenaStr<H, I>

where 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<H, I: Index> Debug for ArenaStr<H, I>

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

Formats the value using the given formatter.

impl<H, I> Default for ArenaStr<H, I>

where H: Default,

fn default() -> Self

Returns the “default value” for a type.

impl<'de, H, I> Deserialize<'de> for ArenaStr<H, I>

where H: Default + BuildHasher, I: Index + Deserialize<'de>,

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<H, I: Index> Eq for ArenaStr<H, I>

impl<H, I> GetSize for ArenaStr<H, I>

where 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<H, I: Index> PartialEq for ArenaStr<H, I>

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

Equality operator ==.

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

Inequality operator !=.

impl<H, I> Schema for ArenaStr<H, I>

where I: Schema,

Available on crate feature postcard-schema only.

const SCHEMA: &'static NamedType

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

impl<H, I> Serialize for ArenaStr<H, I>

where I: Index + Serialize,

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.