Crate tuplez

Tuples represented in recursive form rather than parallel form.

Motivation

The primitive tuple types are represented in parallel form, like:

(a, b, c, d ...)

Since Rust doesn’t support variadic generics, we cannot add methods to primitive tuples with any number of elements.

Currently, most tuple crates use declarative macros to implement methods for tuples whose number of elements is less than a certain limit (usually 32).

To solve this, tuplez introduces a Tuple type represented in recursive form, like:

Tuple(a, Tuple(b, Tuple(c, Tuple(d, ...))))

The advantage of this representation is that you can implement methods recursively for all tuples, and there is no longer a limit on the number of tuple’s elements. And, in almost all cases, the Tuple takes no more memory than the primitive tuples.

Functionality

• Create tuples with any number of elements.
• Access elements in a tuple at any index, or by their types.
• Push element to a tuple or pop element from a tuple.
• Join two tuples or split a tuple into two parts.
• Rich tuple operations, e.g.: reverse, left rotate, zip.
• Get subsequences.
• If all element types implement a Trait (e.g. Eq, Add), then the Tuple also implement that Trait. See which traits are supported and learn how to implement your custom traits for Tuple.
• Traverse all elements of a tuple, or fold a tuple.
• When the number of elements of a tuple doesn’t exceed 32, then it can be converted from/to a primitive tuple or a primitive array.

Optional features

• unwrap : (by default) Allows converting a tuple whose elements are all wrappers into a tuple of the values those wrappers contain.
• uninit: Add APIs for tuples consisting of MaybeUninit elements.
• serde: Derive Serialize and Deserialize for tuples.
• std: (by default) Use standard library. It also enables std feature of serde.
• alloc: Use standard alloc library. It also enables alloc feature of serde. This feature is usually used when std is disabled.
• any_array: (nightly) Use Rust’s unstable feature to implement conversion from/to primitive arrays on tuples with any number of elements. This feature requires compiling with rustc released to nightly channel.

Bundles:

• default: Enable default features, which are: std, unwrap.
• full-no-std: Enable all features available on stable Rust without std, which are: serde, uninit and unwrap. Note that default-features = false is necessary.
• full: Enable all features available on stable Rust, which are: serde, std, uninit and unwrap.
• full-nightly: Enable all features (requires nightly Rust).

Examples

use tuplez::*;

let tup = tuple!(1, "hello".to_string(), 3.14);
let tup2 = Tuple::from((2, " world", -3.14));
let tup3 = tup + tup2;
assert_eq!(tup3, tuple!(3, "hello world".to_string(), 0.0));

let tup4 = tup3.push(Some([1, 2, 3]));
let (tup5, popped) = tup4.pop_front();
assert_eq!(
    tup5,
    tuple!("hello world".to_string(), 0.0, Some([1, 2, 3]))
);
assert_eq!(popped, 3);

let tup6 = tup5.rev();
assert_eq!(
    tup6,
    tuple!(Some([1, 2, 3]), 0.0, "hello world".to_string())
);
let tup7 = tup6.rot_l();
assert_eq!(
    tup7,
    tuple!(0.0, "hello world".to_string(), Some([1, 2, 3]))
);

let tup8 = tup7.foreach(mapper! {
    |x: f64| -> String { x.to_string() }
    |x: Option<[i32; 3]>| -> String { format!("{:?}", x.unwrap()) }
    |x: String| { x }
});
let arr = tup8.to_array();
assert_eq!(
    arr,
    [
        "0".to_string(),
        "hello world".to_string(),
        "[1, 2, 3]".to_string()
    ]
);

let tup9 = tuple!(1, "2", 3.0);
let result = tup9.fold(
    tuple!(
        |acc, x| (acc + x) as f64,
        |acc: f64, x: &str| acc.to_string() + x,
        |acc: String, x| acc.parse::<i32>().unwrap() + x as i32,
    ),
    0,
);
assert_eq!(result, 15);

Please check Tuple’s documentation page for detailed usage.

Modules

• fold
  Provides the ability to fold tuples.
• foreach
  Provides the ability to traverse tuples.
• ops
  Provides some operations between two tuples.
• predicate
  Provides the ability to test tuples.
• search
  Provides the ability to search tuple elements by type.
• uninituninit
  Provide operations on tuples consisting of MaybeUninit elements.
• unwrapunwrap
  Provides the ability to unwrap elements of tuples.

Macros

• apply
  Pass the elements of a tuple as arguments to a function or method.
• folder
  Provides a simple way to build a folder that implements Folder.
• get
  Get the element at a specific index of the tuple.
• mapper
  Provides a simple way to build a mapper that implements Mapper.
• pick
  Pick some elements from a tuple.
• split_at
  Split the tuple into two tuples at a specific index.
• swap_at
  Swap two parts of a tuple.
• take
  Take the element at a specific index of the tuple and get the remainder.
• tuple
  Generate a tuple from a list of expressions.
• tuple_pat
  Generate patterns for tuples.
• tuple_t
  Generate the complete type signature for tuples.
• unary_pred
  Provides a simple way to build a unary predicate that implements UnaryPredicate.

Structs

• Tuple
  The type used to represent tuples containing at least one element.
• Unit
  The unit type that represents tuples of zero elements.

Traits

• ToArray
  Convert from tuples to primitive arrays, if all elements of the tuple are of the same type.
• ToPrimitive
  Convert from tuples to primitive tuples.
• TupleLenEqTo
  A Marker trait to indicate that two tuple types have the same number of elements.
• TupleLike
  Define the basic methods of tuples.
• Tupleize
  Convert between Tuple and struct types.

Derive Macros

• Tupleize
  Derive Tupleize on struct.