[−][src]Crate index_vec
index_vec
A more type-safe version of Vec
, for when usize
just isn't cutting it
anymore.
Example / Overview
use index_vec::{IndexVec, index_vec}; // Define a custom index type. index_vec::define_index_type! { // In this case, use a u32 instead of a usize. pub struct StrIdx(u32); // Note that this macro has a decent amount of configurability, so // be sure to read its documentation if you think it's doing // something you don't want. } // Create a vector which can be accessed using `StrIdx`s. let mut strs: IndexVec<StrIdx, &'static str> = index_vec!["strs", "bar", "baz"]; // l is a `StrIdx` let l = strs.last_idx(); assert_eq!(strs[l], "baz"); let new_i = strs.push("quux"); assert_eq!(strs[new_i], "quux"); // Indices are mostly interoperable with `usize`, and support // a lot of what you might want to do to an index. // Comparison assert_eq!(StrIdx::new(0), 0usize); // Addition assert_eq!(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);
Background
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. Some notable changes:
- No usage of unstable features.
- Different syntax for defining index types.
- More complete mirroring of Vec's API.
- Allows use of using other index types than
u32
/usize
. - More flexible behavior around how strictly some checks are performed,
Other crates
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.
Modules
example_generated | This module is just for documentation purposes, and is hidden behind the
|
Macros
define_index_type | Generate the boilerplate for a newtyped index struct, for use with
|
index_vec | A macro equivalent to the stdlib's |
Structs
IndexVec | A Vec that only accepts indices of a specific type. |
Traits
Idx | Represents a wrapped value convertable to and from a |