Crate lhlist

Library for labeled heterogeneous lists.

This crate provides data structures and traits for assembling and using labeled heterogeneous lists. A heterogeneous list is a list of values where each value has a different types. These heterogeneous lists are implemented using cons-lists, which adds some usage flexibility over what is available with built-in Rust tuples.

Labels

Lists created in lhlist possess ‘labels’ used to identify and index into the list. Labels are unit-like structs which implement the Label trait and are typically created using the new_label macro.

use lhlist::Label;

new_label![MyLabel: u8];
assert_eq!(MyLabel::name(), "MyLabel");

See the new_label documentation for more examples of creating labels.

List Creation

Labeled lists are created using the lhlist macro, which takes a comma-separated list of label-value pairs. For example,

use lhlist::Label;

new_label![SomeNumbers: Vec<u64>];
new_label![SomeNames: Vec<&'static str>];
new_label![Flag: bool];

let my_list = lhlist![
    SomeNumbers = vec![0, 4, 5, 2],
    SomeNames = vec!["hello", "world!"],
    Flag = false,
];
assert_eq!(my_list[Flag], false);

Internally, the values are contained as LabeledValue structs which associate the label information to the added value.

Accessing via Label

The LabeledValue objects contained in a list can be accessed via the elem or elem_mut methods.

The contained values in a list (without the associated label information) can be accessed via the value or value_mut methods. Using list[Label] notation (via Index and IndexMut) is also supported.

More details and examples can be found in the documentation for the various accessor methods.

Iteration

Much like accessing individual element of a list, iteration over a list can be done in two contexts:

1. Calling iter to create a ConsIterator which iterates over the LabeledValue objects, or
2. Calling iter_values to create a ValuesIterator which iterates over the contained values.

These iterators both support mapping functionality for processing values using types that implement the MapFunc trait. See the MapAdapter documentation for more details and an example.

There are also two ways to collect the contents of an iterator into a new cons-list:

1. CollectIntoHList collects the contents of an iterator as-is. When this collection is performed on a ValuesIterator, the new cons-list does not contain any label information (since the ValueIterator only iterates over the contained values).
2. CollectIntoLabeledHList collects the contents of an iterator with a new provided set of labels. This is particularly useful when the types of elements have changed during the iterator process (via MapAdapter) and the old labels are no longer valid (since a label can only has one associated type).

An example of both kinds of collection can be see in the MapAdapter documentation.

Modules

iter

Iteration over heterogeneous cons-lists and labeled heterogeneous cons-lists.

Macros

Labels

Macro for creating type signature for a LCons label-only cons-list.

cons

Macro for creation of a Cons-list.

labels

Macro for creating an instance of an LCons label-only cons-lists.

lhlist

Macro for creating labeled heterogeneous lists.

new_label

Macro for easily creating a label struct.

Structs

Cons

Main buildling block of a heterogeneous list.

False

Marker struct signifying false.

LabeledValue

A value along with its label.

Nil

The end of a heterogeneous list.

True

Marker struct signifying true.

Traits

Bool

Trait for types that signify true or false.

HasLabels

Trait for extracting the labels (LCons) from a cons-list of elements which all implement Label.

Label

A trait with information about a label.

LabelEq

Label equality.

Len

Provides the length of a cons-list.

LookupElemByLabel

Lookup a specific element in a list by label.

Member

Check to see if a target label is a list member.

StrLabels

Generate a Vec containing the names of the labels in a labeled cons-list.

ToBool

Conversion trait for types that have a logical true or false meaning

Value

A trait that provides access to contained ‘values’.

Functions

cons

Create a new cons-list.

labeled

Creates a new LabeledValue object for placement into an LVCons list.

labeled_typearg

Creates a new LabeledValue object for placement into an LVCons list.

Type Aliases

LCons

A cons-list containing only labels.

LVCons

A cons-list containing a set of labeled values.

Attribute Macros

label