Struct Registry

Source

pub struct Registry<T, S = RandomState>(/* private fields */);

Expand description

A registry for “type spec” values that uses types as keys.

This data structure is used for associating data type metadata with a Rust type which can be used to ensure the lifetime of the associated metadata.

The registry resembles an append-only HashMap.

The registry stores values behind a Box pointer to ensure pointers to the interior of the spec, like CString fields, are not invalidated as the underlying storage reallocates.

§Example

use mezzaluna_type_registry::Registry;

let mut reg: Registry<&'static str> = Registry::with_capacity(10);
reg.insert::<i32>(Box::new("Numeric"));
reg.insert::<Vec<u8>>(Box::new("String"));

assert_eq!(reg.get::<i32>(), Some(&"Numeric"));
assert_eq!(reg.get::<Vec<u8>>(), Some(&"String"));
assert_eq!(reg.get::<f64>(), None);

Implementations§

Source §

impl<T> Registry<T, RandomState>

Source

pub fn new() -> Self

Construct a new, empty registry.

The registry is initially created with a capacity of 0, so it will not allocate until it is first inserted into.

§Examples

use mezzaluna_type_registry::Registry;

let mut reg: Registry<&'static str> = Registry::new();

Source

pub fn with_capacity(capacity: usize) -> Self

Construct a new registry with at least the specified capacity.

§Examples

use mezzaluna_type_registry::Registry;

let mut reg: Registry<&'static str> = Registry::with_capacity(10);

Source §

impl<T, S> Registry<T, S>

Source

pub fn with_hasher(hash_builder: S) -> Self

Construct a new registry with the given hash_builder.

The created registry has the default initial capacity.

Warning: hash_builder is normally randomly generated, and is designed to allow registries to be resistant to attacks that cause many collisions and very poor performance. Setting it manually using this function can expose a DoS attack vector.

The hash_builder passed should implement the BuildHasher trait for the registry to be useful, see its documentation for details.

§Examples

use std::collections::hash_map::RandomState;
use mezzaluna_type_registry::Registry;

let s = RandomState::new();
let mut reg = Registry::with_hasher(s);
reg.insert::<i32>(Box::new("Numeric"));

Source

pub fn with_capacity_and_hasher(capacity: usize, hash_builder: S) -> Self

Construct a new registry with at least the specified capacity, using hasher to hash the types.

The registry will be able to hold at least capacity elements without reallocating. This method is allowed to allocate for more elements than capacity. If capacity is 0, the registry will not allocate.

Warning: hash_builder is normally randomly generated, and is designed to allow registries to be resistant to attacks that cause many collisions and very poor performance. Setting it manually using this function can expose a DoS attack vector.

The hash_builder passed should implement the BuildHasher trait for the registry to be useful, see its documentation for details.

§Examples

use std::collections::hash_map::RandomState;
use mezzaluna_type_registry::Registry;

let s = RandomState::new();
let mut reg = Registry::with_capacity_and_hasher(10, s);
reg.insert::<i32>(Box::new("Numeric"));

Source

pub fn capacity(&self) -> usize

Returns the number of type specs the registry can hold without reallocating.

This number is a lower bound; the registry might be able to hold more, but is guaranteed to be able to hold at least this many.

§Examples

use mezzaluna_type_registry::Registry;

let reg: Registry<&'static str> = Registry::with_capacity(100);
assert!(reg.capacity() >= 100);

Source

pub fn type_specs(&self) -> TypeSpecs<'_, T> ⓘ

An iterator of all type specs stored in the registry in arbitrary order. The iterator element type is &'a T.

§Examples

use mezzaluna_type_registry::Registry;

let mut reg: Registry<&'static str> = Registry::with_capacity(10);
reg.insert::<i32>(Box::new("Numeric"));
reg.insert::<Vec<u8>>(Box::new("String"));

for spec in reg.type_specs() {
    println!("{spec}");
}

Source

pub fn len(&self) -> usize

Returns the number of type specs in the registry.

§Examples

use mezzaluna_type_registry::Registry;

let mut reg: Registry<&'static str> = Registry::with_capacity(10);
assert_eq!(reg.len(), 0);
reg.insert::<i32>(Box::new("Numeric"));
assert_eq!(reg.len(), 1);

Source

pub fn is_empty(&self) -> bool

Returns true if the registry does not contain any type specs.

§Examples

use mezzaluna_type_registry::Registry;

let mut reg: Registry<&'static str> = Registry::with_capacity(10);
assert!(reg.is_empty());
reg.insert::<i32>(Box::new("Numeric"));
assert!(!reg.is_empty());

Source

pub fn hasher(&self) -> &S

Returns a reference to the registry’s BuildHasher.

§Examples

use std::collections::hash_map::RandomState;
use mezzaluna_type_registry::Registry;

let s = RandomState::new();
let reg: Registry<&'static str> = Registry::with_hasher(s);
let hasher: &RandomState = reg.hasher();

Source §

impl<T, S> Registry<T, S>
where T: Debug, S: BuildHasher,

Source

pub fn contains<K>(&self) -> bool
where K: Any,

Returns true if the registry contains a type spec for the specified type.

§Examples

use mezzaluna_type_registry::Registry;

let mut reg: Registry<&'static str> = Registry::with_capacity(10);
reg.insert::<i32>(Box::new("Numeric"));
assert_eq!(reg.contains::<i32>(), true);
assert_eq!(reg.contains::<Vec<u8>>(), false);

Source

pub fn insert<K>(&mut self, spec: Box<T>)
where K: Any,

Inserts a type-type spec pair into the registry.

This operation will only succeed if K has never been inserted into the registry.

§Panics

If insert has previously been called with type K, this function will panic. The registry is append-only and does not allow mutations.

§Examples

use mezzaluna_type_registry::Registry;

let mut reg: Registry<&'static str> = Registry::with_capacity(10);
reg.insert::<i32>(Box::new("Numeric"));
assert_eq!(reg.is_empty(), false);

Source

pub fn get<K>(&self) -> Option<&T>
where K: Any,

Returns a reference to the type spec corresponding to the type key.

If the type K has not been registered, None is returned.

§Examples

use mezzaluna_type_registry::Registry;

let mut reg: Registry<&'static str> = Registry::with_capacity(10);
reg.insert::<i32>(Box::new("Numeric"));
assert_eq!(reg.get::<i32>(), Some(&"Numeric"));
assert_eq!(reg.get::<Vec<u8>>(), None);

Source

pub fn reserve(&mut self, additional: usize)

Reserves capacity for at least additional more elements to be inserted in the registry. The collection may reserve more space to speculatively avoid frequent reallocations. After calling reserve, capacity will be greater than or equal to self.len() + additional. Does nothing if capacity is already sufficient.

§Panics

Panics if the new allocation size overflows usize.

§Examples

use mezzaluna_type_registry::Registry;

let mut reg: Registry<&'static str> = Registry::new();
reg.reserve(10);
assert!(reg.capacity() >= 10);

Source

pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError>

Tries to reserve capacity for at least additional more elements to be inserted in the registry. The collection may reserve more space to speculatively avoid frequent reallocations. After calling try_reserve, capacity will be greater than or equal to self.len() + additional if it returns Ok(()). Does nothing if capacity is already sufficient.

§Errors

If the capacity overflows, or the allocator reports a failure, then an error is returned.

§Examples

use mezzaluna_type_registry::Registry;

let mut reg: Registry<&'static str> = Registry::new();
reg.try_reserve(10).expect("cannot OOM the doctest harness");
assert!(reg.capacity() >= 10);

Source

pub fn shrink_to_fit(&mut self)

Shrinks the capacity of the registry as much as possible. It will drop down as much as possible while maintaining the internal rules and possibly leaving some space in accordance with the resize policy.

§Examples

use mezzaluna_type_registry::Registry;

let mut reg: Registry<&'static str> = Registry::with_capacity(100);
reg.insert::<i32>(Box::new("Numeric"));
reg.insert::<Vec<u8>>(Box::new("String"));
assert!(reg.capacity() >= 100);
reg.shrink_to_fit();
assert!(reg.capacity() >= 2);

Source

pub fn shrink_to(&mut self, min_capacity: usize)

Shrinks the capacity of the registry with a lower limit. It will drop down no lower than the supplied limit while maintaining the internal rules and possibly leaving some space in accordance with the resize policy.

If the current capacity is less than the lower limit, this is a no-op.

§Examples

use mezzaluna_type_registry::Registry;

let mut reg: Registry<&'static str> = Registry::with_capacity(100);
reg.insert::<i32>(Box::new("Numeric"));
reg.insert::<Vec<u8>>(Box::new("String"));
assert!(reg.capacity() >= 100);
reg.shrink_to(10);
assert!(reg.capacity() >= 10);
reg.shrink_to(0);
assert!(reg.capacity() >= 2);