Expand description
Indexical: Human-Friendly Indexed Collections
Indexical is a library for conveniently and efficiently working with indexed collections of objects. “Indexed” means that the domain of objects is finite, and you can assign a numeric index to each object. This enables the use of efficient data structures like bit-sets.
Indexical is a layer on top of existing bit-set libraries like bitvec
and rustc_index::bit_set
.
Those data structures only “understand” indexes, not the objects represented by the index.
Indexical provides utilities for converting between the object domain and the index domain.
Example
use indexical::{
IndexedDomain, IndexedValue, define_index_type,
impls::BitvecIndexSet as IndexSet
};
use std::rc::Rc;
// First, define a custom type.
#[derive(PartialEq, Eq, Clone, Hash)]
pub struct MyString(String);
// Second, define a new index for your custom type.
define_index_type! {
pub struct StringIndex for MyString = u32;
}
// Third, create an immutable indexed domain from a collection of objects.
// By default this is Rc-wrapped, but you can also use Arc or &-refs.
let domain = Rc::new(IndexedDomain::from_iter([
MyString(String::from("Hello")), MyString(String::from("world"))
]));
// Finally, you can make a set! Notice how you can pass either a `MyString`
// or a `StringIndex` to `set.insert(..)` and `set.contains(..)`.
let mut set = IndexSet::new(&domain);
set.insert(MyString(String::from("Hello")));
set.insert(StringIndex::from_usize(1));
assert!(set.contains(MyString(String::from("world"))));
For further details, see: https://docs.rs/indexical
Design
The key idea is that the IndexedDomain
is shared pervasively
across all Indexical types. All types can then use the IndexedDomain
to convert between indexes and objects, usually via the ToIndex
trait.
IndexSet
and IndexMatrix
are generic with respect to two things:
- The choice of bit-set implementation. By default, Indexical includes the [
bitvec
] crate and provides the [impls::BitvecIndexSet
] type. You can provide your own bit-set implementation via theBitSet
trait. - The choice of domain pointer. By default, Indexical uses the
Rc
pointer via theRcFamily
type. You can choose to use theArcFamily
if you need concurrency, or theRefFamily
if you want to avoid reference-counting.
Re-exports
pub use index_vec;
Modules
- Implementations of the
BitSet
trait for different backends.
Macros
- Creates a new index type and associates it with an object type.
Structs
- Family of
Arc
pointers. - An unordered collections of pairs
(R, C)
, implemented with a sparse bit-matrix. - An unordered collections of
T
s, implemented with a bit-set. - An indexed collection of objects, implemented with an
IndexVec
. - Coherence hack for the
ToIndex
trait. - Coherence hack for the
ToIndex
trait. - Coherence hack for the
ToIndex
trait. - Family of
Rc
pointers. - Family of
&
-references.
Traits
- Interface for bit-set implementations.
- Extension trait for iterators producing index sets.
- Links a type to its index.
- Abstraction over smart pointers with
'static
interiors. - Implicit conversions from elements to indexes. Commonly used in the
IndexSet
andIndexMatrix
interfaces.