tuplities

Tuple utilities in Rust, fractioned across several crates to improve compile times. There is a main crate tuplities that re-exports traits from subcrates in its prelude module, so that the subcrates may be compiled in parallel cutting down on overall build times.

This library is #[no_std] compatible, making it suitable for embedded systems and other environments without the standard library.

[dependencies]
tuplities = "0.1.4"

The library provides several traits for working with tuples:

• TupleClone: Provides a tuple_clone() method to clone tuples. All elements must implement Clone.
• TupleCopy: Provides a tuple_copy() method to copy tuples. All elements must implement Copy.
• TupleDebug: Provides a tuple_debug() method that returns a debug string representation of the tuple. All elements must implement Debug.
• TupleDefault: Provides a tuple_default() method to create default instances of tuples. All elements must implement Default.
• TupleReplicate<T>: Provides a tuple_replicate(value) method to create tuples by replicating a single value across all positions. The value must implement Clone for tuples with 2+ elements, but not for empty tuples or single-element tuples.
• TupleHash: Provides a tuple_hash<H: Hasher>() method to hash tuples with any hasher. All elements must implement Hash.
• TuplePartialEq: Provides a tuple_eq() method to compare tuples for partial equality. All elements must implement PartialEq.
• TupleEq: Provides a tuple_eq() method to compare tuples for total equality. All elements must implement Eq.
• TuplePartialOrd: Provides a tuple_partial_cmp() method to compare tuples for partial ordering. All elements must implement PartialOrd.
• TupleOrd: Provides a tuple_cmp() method to compare tuples for total ordering. All elements must implement Ord.
• TupleOption: Provides a transpose() method to transpose a tuple of options into an option of a tuple. All elements must be Option<T>.
• IntoTupleOption: Provides an into_options() method to convert a tuple into a tuple of options.
• NestedTupleOption: Provides a transpose() method to transpose nested tuples of options into options of nested tuples.
• IntoNestedTupleOption: Provides an into_options() method to convert nested tuples into nested tuples of options.
• NestedTupleOptionWith<H>: Provides first_none_with, first_some_with, and transpose_or helpers which operate with a parallel homogeneous nested tuple of H used for result/error mapping.
• NestedTupleTryFrom<T, E>: Provides a nested_tuple_try_from() method to fallibly convert nested tuple types element-wise using TryFrom conversions.
• NestedTupleTryInto<T, E>: Provides a nested_tuple_try_into() convenience method to perform fallible conversions using NestedTupleTryFrom.
• NestedTupleFrom<T>: Provides an infallible nested_tuple_from() method to convert nested tuples using From element-wise.
• NestedTupleInto<T>: Provides an infallible nested_tuple_into() convenience method to perform conversions using NestedTupleFrom.
• NestedTupleOptionFrom<T>: Provides a nested_tuple_option_from() method to convert nested tuples of Options using From element-wise.
• NestedTupleOptionInto<T>: Provides a nested_tuple_option_into() convenience method to perform conversions using NestedTupleOptionFrom.
• NestedTupleOptionTryFrom<T, E>: Provides a nested_tuple_option_try_from() method to fallibly convert nested tuples of Options using TryFrom conversions.
• NestedTupleOptionTryInto<T, E>: Provides a nested_tuple_option_try_into() convenience method to perform fallible conversions using NestedTupleOptionTryFrom.
• NestedTupleReplicate<T>: Provides a nested_tuple_replicate(value) method to create nested tuples by replicating a single value across all positions.
• TupleRef: Provides a tuple_ref() method to get references to each element in the tuple.
• TupleMut: Provides a tuple_mut() method to get mutable references to each element in the tuple.
• TupleRefMap: Provides a tuple_ref_map() method to apply TupleRef to each element of a tuple of tuples, returning a tuple of tuples of references.
• TupleMutMap: Provides a tuple_mut_map() method to apply TupleMut to each element of a tuple of tuples, returning a tuple of tuples of mutable references.
• TuplePopFront: Provides a pop_front() method to remove and return the first element of the tuple along with the remaining elements as a new tuple.
• TuplePopBack: Provides a pop_back() method to remove and return the last element of the tuple along with the remaining elements as a new tuple.
• TuplePushFront<T>: Provides a push_front(element) method to add an element to the front of the tuple, returning a new tuple.
• TuplePushBack<T>: Provides a push_back(element) method to add an element to the back of the tuple, returning a new tuple.
• TupleRemove<Idx>: Provides a remove() method to remove and return the element at the specified index typenum's Idx of the tuple along with the remaining elements as a new tuple.
• TupleInsert<Idx, T>: Provides an insert() method to insert an element at the specified index typenum's Idx into the tuple, returning the tuple with the element inserted.
• TupleSplit<Idx>: Provides a split() method to split a tuple at the specified compile-time index typenum's Idx, returning two tuples containing the elements before and at/after the index.
• TupleReverse: Provides a reverse() method to reverse the order of elements in a tuple.
• TupleTryFrom<T>: Provides a tuple_try_from() method to fallibly convert from other types into tuples.
• TupleTryInto<T>: Provides a tuple_try_into() method to fallibly convert tuples into other types.
• TupleFrom<T>: Provides a tuple_from() method to infallibly convert from other types into tuples.
• TupleInto<T>: Provides a tuple_into() method to infallibly convert tuples into other types.
• FlattenNestedTuple: Provides a flatten() method to convert nested tuples like (A, (B, (C,))) into flat tuples like (A, B, C).
• NestTuple: Provides a nest() method to convert flat tuples like (A, B, C) into nested tuples like (A, (B, (C,))).
• NestedTupleIndex<Idx>: Provides a nested_index() method to access elements at flat indices in nested tuples using typenum's Idx.
• NestedTupleIndexMut<Idx>: Provides a nested_index_mut() method to access mutable elements at flat indices in nested tuples using typenum's Idx.
• NestedTupleRef: Provides a nested_tuple_ref() method to get nested references to each leaf value of a nested tuple.
• NestedTupleMut: Provides a nested_tuple_mut() method to get nested mutable references to each leaf value of a nested tuple.
• NestedTuplePopFront: Provides a nested_pop_front() method to pop the front element of nested tuples.
• NestedTuplePopBack: Provides a nested_pop_back() method to pop the back element of nested tuples.
• NestedTuplePushFront<T>: Provides a nested_push_front(element) method to push an element to the front of a nested tuple.
• NestedTuplePushBack<T>: Provides a nested_push_back(element) method to push an element to the back of a nested tuple.
• NestedTupleRow<Idx>: Provides a nested_tuple_row() method to access elements at the specified index across a nested tuple-of-tuples, returning a nested row tuple by value.
• NestedTupleRow<Idx>: Provides a nested_tuple_row() method to access elements at the specified index across a nested tuple-of-tuples, returning a nested row tuple of references (analogous to TupleRow).
• NestedTupleRowMut<Idx>: Provides nested_tuple_row_mut() for mutable nested row access.
• NestedTupleStartsWith<Other>: A marker trait for compile-time verification that a nested tuple starts with the same types as another nested tuple. For example, (A, (B, (C,))) implements NestedTupleStartsWith<(A,)> and NestedTupleStartsWith<(A, (B,))>.
• NestTupleMatrix: Provides a nest_matrix() method to convert flat tuples of flat tuples like ((A, B), (C, D)) into nested tuples of nested tuples like ((A, (B,)), ((C, (D,)),)).
• FlattenNestedTupleMatrix: Provides a flatten_matrix() method to convert nested tuples of nested tuples back into flat tuples of flat tuples.
• TupleLen: Provides the length of the tuple as a compile-time typenum::Unsigned type.
• UnitTuple: A marker trait implemented for empty tuples () with TupleLen<Len = U0>.
• SingletonTuple: A marker trait implemented for single-element tuples (T,) with TupleLen<Len = U1>.
• PairTuple: A marker trait implemented for two-element tuples (T1, T2) with TupleLen<Len = U2>.
• TupleIndex<Idx>: Provides an index() method to access the element at the specified index typenum's Idx of the tuple.
• TupleIndexMut<Idx>: Provides an index_mut() method to access a mutable reference to the element at the specified index typenum's Idx of the tuple.
• FirstTupleIndex: A convenience trait providing a first_tuple_index() method to access the first element of a tuple.
• LastTupleIndex: A convenience trait providing a last_tuple_index() method to access the last element of a tuple.
• TupleRow<Idx>: Provides a tuple_row() method to access elements at the specified index across all tuples in a tuple of tuples (row-wise indexing).
• TupleRowMut<Idx>: Provides a tuple_row_mut() method to access mutable elements at the specified index across all tuples in a tuple of tuples (mutable row-wise indexing).
• FirstTupleRow: A convenience trait providing a first_tuple_row() method to access the first element of each tuple in a tuple of tuples.
• LastTupleRow: A convenience trait providing a last_tuple_row() method to access the last element of each tuple in a tuple of tuples.

Features

The crate provides optional features to enable specific traits. All features are enabled by default for convenience, but can be selectively disabled to reduce compile time and binary size.

Trait Features

The following features enable individual trait crates:

• clone: Enables TupleClone trait
• copy: Enables TupleCopy trait
• debug: Enables TupleDebug trait
• tuple-default: Enables TupleDefault trait
• eq: Enables TupleEq trait
• flatten-nest: Enables FlattenNestedTuple, NestTuple, NestedTupleIndex, NestedTupleIndexMut, NestedTupleTryFrom, NestedTupleTryInto, NestTupleMatrix, FlattenNestedTupleMatrix, NestedTupleOption, IntoNestedTupleOption, and NestedTupleOptionWith traits
• from: Enables TupleFrom and TupleInto traits
• hash: Enables TupleHash trait
• mut: Enables TupleMut and TupleMutMap traits
• option: Enables TupleOption and IntoTupleOption traits
• ord: Enables TupleOrd trait
• partial-eq: Enables TuplePartialEq trait
• partial-ord: Enables TuplePartialOrd trait
• remove: Enables TupleRemove trait
• insert: Enables TupleInsert trait
• len: Enables TupleLen, UnitTuple, SingletonTuple, and PairTuple traits
• index: Enables TupleIndex, TupleIndexMut, FirstTupleIndex, and LastTupleIndex traits
• pop-front: Enables TuplePopFront, TupleRefFront, and TupleMutFront traits
• pop-back: Enables TuplePopBack, TupleRefBack, and TupleMutBack traits
• push-front: Enables TuplePushFront trait
• push-back: Enables TuplePushBack trait
• ref: Enables TupleRef and TupleRefMap traits
• replicate: Enables TupleReplicate trait
• reverse: Enables TupleReverse trait
• row: Enables TupleRow, TupleRowMut, FirstTupleRow, and LastTupleRow traits
• split: Enables TupleSplit trait
• try-from: Enables TupleTryFrom and TupleTryInto traits

Size Features

Additionally, the crate provides features to generate trait implementations for tuples up to different sizes: 8 (default), 16, 32, 48, 64, 96, or 128 elements. Use the size-XX features to enable larger tuple support.

[dependencies]
tuplities = { version = "0.1.4", default-features = false, features = ["clone", "index", "size-32"] }

Performance

Compile times scale with tuple size due to code generation. Below are measured build times for different maximum tuple sizes captured via the project's measure_compile_times.sh script on a typical development machine. Values are approximate and represent wall-clock real times. If you only plan to use variadic nested tuples, you may prefer to use only the tuplities-flatten-nest crate, which has significantly lower compile times.

tuplities (root crate)

tuplities-flatten-nest (flatten-nest crate only)

Architecture

The project is split into multiple crates for improved compile times:

• tuplities/: Main crate that re-exports traits from subcrates
• tuplities-{trait_name}/: Individual crates providing specific traits
• tuplities-derive/: Procedural macro crate that generates trait implementations

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contribution

Contributions are welcome! Please open issues or pull requests on the GitHub repository.