Crate enumoid

Enumoid

This crate is a Rust library which can establish a mapping between the values that inhabit a type and the integers between 0 and n, where n is the number of distinct values. This is used to provide a range of utility functions for traversing the space of values and several container data structures indexed by such values.

Dependency

[dependencies]
enumoid = "0.4"

Deriving Enumoid

In order to use a type with this crate, it must implement the Enumoid trate using the eponymous derive proc macro.

Enumoid can be derived for enum types with unit variants:

use enumoid::Enumoid;

#[derive(Enumoid)]
enum Weekday { Monday, Tuesday, Wednesday, Thursday, Friday }

Enumoid can also be derived for tuple variants with a single field whose type also implements Enumoid:

#[derive(Enumoid)]
enum Day { Work(Weekday), Rest(Weekend) }

#[derive(Enumoid)]
enum Weekend { Saturday, Sunday }

The field may not have a generic type as this would require currently unstable aspects of const generics.

Enumoids can also be derived for unit structs and for tuple structs with a single field whose type implements Enumoid:

#[derive(Enumoid)]
struct AnyDay;

#[derive(Enumoid)]
struct EveryDay(Day);

By default, a u8 is used to represent the number of values inhabiting an Enumoid. If you want to derive Enumoid for a type with more than 255 values, you can specify a wider type with the index_type helper attribute.

#[derive(Enumoid)]
#[index_type(u32)]
enum Massive { A, /*...*/ }

Traversing Enumoids

The Enumoid trait provides a range of utility functions for traversing through value space. They allow you to find the next or previous value, with or without wrapping. For example:

let tomorrow = Day::Work(Weekday::Friday).next();
assert_eq!(tomorrow, Some(Day::Rest(Weekend::Saturday)));

let yesterday = Day::Work(Weekday::Monday).prev_wrapped();
assert_eq!(yesterday, Day::Rest(Weekend::Sunday));

Another useful operation is to iterate through all the values:

assert_eq!(
    Weekend::iter().collect::<Vec<Weekend>>(),
    vec![Weekend::Saturday, Weekend::Sunday])

Enumoid-indexed Containers

This crate provides a range of container types which use an Enumoid as a key. They are all backed internally by fixed-size arrays and so do not allocate. For example, EnumMap provides a total mapping from the values of an Enumoid to some other type T:

let mut map = EnumMap::<FooBar, String>::new();
map[FooBar::Foo] = "Hello".to_string();

EnumOptionMap is similar, but it provides a partial mapping wherein elements may be absent. EnumVec is also a partial mapping, but operates like a vector wherein any present elements are contiguous with the first value of the Enumoid.

EnumSet is specialised for storing set membership:

let mut set = EnumSet::<FooBar>::new();
set.insert(FooBar::Foo);
set.insert(FooBar::Bar);
assert_eq!(set.count(), 2);

Licence

This crate is licensed under the Apache License, Version 2.0 (see LICENCE-APACHE or http://www.apache.org/licenses/LICENSE-2.0) or the MIT licence (see LICENCE-MIT or http://opensource.org/licenses/MIT), at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Structs

EnumIndex

A counter between 0 and the highest index into the values inhabiting T.

EnumMap

A total map from enumoid T to values V.

EnumOptionMap

A partial map from enumoid T to values V.

EnumSet

A set of enumoid T’s members.

EnumSize

A counter between 0 and the number of values inhabiting T.

EnumVec

A vector of values V indexed by enumoid T.

Traits

EnumArrayHelper

Workaround for const generics not supporting associated consts yet.

EnumSetHelper

Workaround for const generics not supporting associated consts yet.

Enumoid

Trait for enumerable types.

Derive Macros

Enumoid

Derive macro which implements the Enumoid, EnumArrayHelper<V>, EnumSetHelper<BitsetWord>, and From<EnumIndex<T>> traits for a type.