index_vec
Note: API still unstable during 0.0.x
A more type-safe version of using Vec, for when usizes are getting you down.
This crate lets you define "newtype"-style wrappers around usize (or other
integers), and Vec<T> so that some additional type safety can be gained at
zero runtime cost.
```rust use indexvec::{IndexVec, indexvec};
indexvec::defineindex_type! { // Define StrIdx to use only 32 bits internally (you can use usize, u16, // and even u8). pub struct StrIdx = u32; // The defaults are very reasonable, but this macro can let // you customize things quite a bit:
// By default, creating a StrIdx would check an incoming `usize against
// `u32::max_value()`, as u32 is the wrapped index type. Lets imagine that
// StrIdx has to interface with an external system that uses signed ints.
// We can change the checking behavior to complain on i32::max_value()
// instead:
MAX_INDEX = i32::max_value() as usize;
// We can also disable checking all-together if we are more concerned with perf
// than any overflow problems, or even do so, but only for debug builds: Quite
// pointless here, but an okay example
DISABLE_MAX_INDEX_CHECK = cfg!(not(debug_assertions));
// And more too, see this macro's docs for more info.
}
// Create a vector which can be accessed using StrIdxs.
let mut strs: IndexVec
// l is a StrIdx
let l = strs.lastidx();
asserteq!(strs[l], "baz");
let newi = strs.push("quux"); asserteq!(strs[new_i], "quux");
// Indices are mostly interoperable with usize, and support
// a lot of what you might want to do to an index. (Note that
// it does not support these with other index wrappers --
// that seems too likely to lead to bugs).
// Comparison asserteq!(StrIdx::new(0), 0usize); // Addition asserteq!(StrIdx::new(0) + 1, 1usize);
// Subtraction (Note that by default, the index will panic on overflow, // but that can be configured in the macro) assert_eq!(StrIdx::new(1) - 1, 0usize);
// Wrapping assert_eq!(StrIdx::new(5) % strs.len(), 1usize); // ... ```
The goal is to replace the pattern of using a type FooIdx = usize to access a
Vec<Foo> with something that can statically prevent using a FooIdx in a
Vec<Bar>. It's most useful if you have a bunch of indices referring to
different sorts of vectors.
Much of the code for this is taken from rustc's IndexVec code, however it's
diverged a decent amount at this point. The largest differences are:
u32 (usize, u32, u16, and u8 are
all supported).The indexed_vec crate predates this,
and is a much closer copy of the code from rustc. Unfortunately, this means it
does not compile on stable.
If you're looking for something further from a vec and closer to a map, you might find handy, slotmap, or slab to be closer what you want.
This is based on code from rustc's source, and retains it's status as
dual-licensed under MIT (LICENSE-MIT) / Apache 2.0 (LICENSE-APACHE).