Crate tuplez

Help

Expand description

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.

Crate tuplezCopy item path