tuplities

Tuple utilities in Rust, fractioned across several crates to improve compile times, providing several useful traits for both variadic programming with tuples as well as flat tuple manipulation.

The main crate tuplities 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.

Variadic Programming with Nested Tuples

One of the most powerful features of tuplities is the ability to perform variadic programming on tuples of arbitrary length by converting them to a nested representation (Head, (Tail...)). This allows you to define traits recursively without needing to implement them for every possible tuple size using macros.

It is important to note that "true" variadic generics are not yet available in Rust. As such, there is still a limit on how large the flat tuples can be, determined by which size-XX feature flags are enabled in this crate. However, this nested approach nevertheless allows for an arbitrary level of recursion while maintaining performant compile times, typically in the order of a few seconds even for large tuple sizes.

Here is an example of how to define a trait that works on tuples of any size where all elements implement Display:

use tuplities::prelude::*;
use core::fmt::Display;

// 1. Define flat & nested traits
trait PrintTuple {
    fn print_tuple(&self);
}
trait PrintNested {
    fn print_nested(&self);
}

// 2. Implement for the base cases
impl PrintNested for () {
    fn print_nested(&self) {}
}
impl<Head: Display> PrintNested for (Head,) {
    fn print_nested(&self) {
        println!("{}", self.0);
    }
}

// 3. Implement for the recursive case
impl<Head, Tail> PrintNested for (Head, Tail)
where
    Head: Display, // Current constraint
    Tail: PrintNested, // Recursive constraint
{
    fn print_nested(&self) {
        println!("{}", self.0);
        self.1.print_nested();
    }
}

// 4. Blanket implementation for nestable tuples
//    whose nested form implements PrintNested
impl<T> PrintTuple for T
where
    for<'a> &'a T: NestTuple<Nested: PrintNested>,
{
    fn print_tuple(&self) {
        self.nest().print_nested();
    }
}

// Usage
let tuple = (42, "hello", true);
tuple.print_tuple();
let another_tuple = ();
another_tuple.print_tuple();
let yet_another_tuple = ("only one element",);
yet_another_tuple.print_tuple();

This pattern is extensively used in libraries like diesel-builders to build complex, type-safe abstractions over tuples of varying sizes.

Comparison with Macro-based Approach

Without nested tuples, achieving the same result typically requires defining a recursive macro that implements the trait for every tuple size up to a maximum limit. This approach has several downsides:

1. Code Bloat: The macro generates a separate implementation for each tuple size, leading to a large amount of generated code.
2. Compile Times & Quadratic Bounds Growth: The compiler has to process all these implementations, which significantly increases compile times. The number of trait bounds generated increases quadratically with the maximum tuple size N (proportional to N^2), as the macro generates implementations for all sizes from 0 to N, and size k requires k bounds.
3. Maintenance: Writing and maintaining complex macros can be error-prone and difficult to debug.
4. Code Coverage: Code coverage tools often struggle to provide meaningful information for code generated via macros, making it harder to ensure your variadic logic is fully tested.

Here is how the same trait would be implemented using macros:

use core::fmt::Display;

trait PrintTuple {
    fn print_tuple(&self);
}

macro_rules! impl_print_tuple {
    // Base case: empty tuple
    () => {
        impl PrintTuple for () {
            fn print_tuple(&self) {}
        }
    };
    // Recursive step: implement for (Head, Tail...) and recurse
    ($Head:ident $(, $Tail:ident)*) => {
        impl<$Head: Display, $($Tail: Display),*> PrintTuple for ($Head, $($Tail,)*) {
            fn print_tuple(&self) {
                #[allow(non_snake_case)]
                let ($Head, $($Tail,)*) = self;
                println!("{}", $Head);
                $(println!("{}", $Tail);)*
            }
        }

        // Recurse for smaller tuple size
        impl_print_tuple!($($Tail),*);
    };
}

// Invoke once for the maximum size you want to support (e.g., 12)
impl_print_tuple!(T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12);

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)

Max Tuple Size	Compile Time
8 (default)	~4.07s
16	~2.71s
32	~3.29s
48	~4.55s
64	~6.83s
96	~15.75s
128	~32.44s

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

Max Tuple Size	Compile Time
8 (default)	~3.18s
16	~2.45s
32	~2.60s
48	~2.86s
64	~3.40s
96	~5.46s
128	~9.52s

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.