Struct tuplez::Tuple

source ·

pub struct Tuple<First, Other>(pub First, pub Other);

Expand description

The type used to represent tuples containing at least one element.

See Unit type which represents tuples containing no elements.

The TupleLike trait defines the basic mothods of all Tuple types and Unit type.

You can create a tuple quickly and easily using the tuple! macro:

use tuplez::*;
let tup = tuple!(1, "hello", 3.14);

Use ; to indicate repeated elements:

use tuplez::*;
assert_eq!(tuple!(1.0, 2;3, "3"), tuple!(1.0, 2, 2, 2, "3"));

Remember that macros do not directly evaluate expressions, so:

use tuplez::*;

let mut x = 0;
assert_eq!(tuple!({x += 1; x}; 3), tuple!(1, 2, 3));

§Representation

Unlike primitive tuple types, Tuple uses a recursive form of representation:

Primitive tuple representation:
    (T0, T1, T2, T3)
`Tuple` representation:
    Tuple<T0, Tuple<T1, Tuple<T2, Tuple<T3, Unit>>>>

… but don’t worry, in almost all cases Tuple will not take up more memory:

use std::mem::size_of;
use tuplez::*;
assert_eq!(size_of::<(i32, f64, &str)>(),
    size_of::<Tuple<i32, Tuple<f64, Tuple<&str, Unit>>>>());

The advantage of using the recursive form of representation is that we can implement a variety of methods on tuples of any length, instead of only implementing these methods on tuples of length less than 12 (or 32).

As a shorthand, we use Tuple<T0, T1, ... Tn> to represent a Tuple type containing N+1 elements in the following text, please keep in mind that this is not a true Tuple representation.

A Tuple can also be used as one of the elements of another Tuple, without restriction.

§Explicit tuple types

In most cases, Tuple or Tuple<_, _> is sufficient to meet the syntax requirements:

use tuplez::*;

let tup = Tuple::from((1, "hello", 3.14)); // or
let tup: Tuple<_, _> = From::from((1, "hello", 3.14));

But sometimes, you may still need to specify the complete tuple type explicitly. At this point, you can use the tuple_t! macro to generate it:

use tuplez::*;

let tup: tuple_t!(i32, String, f64) = Default::default();
assert_eq!(tup, tuple!(0, String::new(), 0.0));

let unit: tuple_t!() = Default::default();
assert_eq!(unit, tuple!());

fn use_tuple(tup: tuple_t!(i32, &dyn std::fmt::Debug, tuple_t!(String, String))) {
    todo!()
}

Use ; to indicate repeated types:

use tuplez::*;

let tup: tuple_t!(i32, f64;3, i32) = tuple!(1, 2.0, 3.0, 4.0, 5);

§Element access

There is a get! macro that can be used to get elements, the only restriction is that the index must be an integer literal:

use tuplez::*;

let tup = tuple!(1, "hello", 3.14);
assert_eq!(get!(tup; 0), 1);
assert_eq!(get!(tup; 1), "hello");
assert_eq!(get!(tup; 2), 3.14);

This macro will be expanded to standard member access syntax:

get!(tup; 0) => tup.0
get!(tup; 1) => tup.1.0
get!(tup; 2) => tup.1.1.0

… so, here’s an example of modifying elements:

use tuplez::*;

fn add_one(x: &mut i32) { *x += 1; }

let mut tup = tuple!(1, "hello", 3.14);
add_one(&mut get!(tup; 0));
assert_eq!(tup, tuple!(2, "hello", 3.14));

§Push, pop, join and split

Any tuple can push further elements, or join another one, with no length limit.

use tuplez::*;

let tup = tuple!();

let tup2 = tup.push(1);             // Push element to back
assert_eq!(tup2, tuple!(1));

let tup3 = tup2.push_back("hello"); // Same as `push`, push element to back
assert_eq!(tup3, tuple!(1, "hello"));

let tup4 = tup3.push_front(3.14);   // Push element to front
assert_eq!(tup4, tuple!(3.14, 1, "hello"));

let tup5 = tup3.join(tup4);         // Join two tuples
assert_eq!(tup5, tuple!(1, "hello", 3.14, 1, "hello"));

Units are not Popable, and all Tuples are Popable:

use tuplez::*;

let tup = tuple!(1, "hello", 3.14, [1, 2, 3]);

let (tup2, arr) = tup.pop();        // Pop element from back
assert_eq!(tup2, tuple!(1, "hello", 3.14));
assert_eq!(arr, [1, 2, 3]);

let (tup3, pi) = tup2.pop_back();   // Same as `pop`, pop element from back
assert_eq!(tup3, tuple!(1, "hello"));
assert_eq!(pi, 3.14);

let (tup4, num) = tup3.pop_front();  // Pop element from front
assert_eq!(tup4, tuple!("hello"));
assert_eq!(num, 1);

let (unit, hello) = tup4.pop();
assert_eq!(unit, tuple!());
assert_eq!(hello, "hello");

// _ = unit.pop()                   // Error: cannot pop an `Unit`

You can use the split_at! macro to split a tuple into two parts. Like the get! macro, the index must be an integer literal:

use tuplez::*;

let tup = tuple!(1, "hello", 3.14, [1, 2, 3]);

let (left, right) = split_at!(tup; 2);
assert_eq!(left, tuple!(1, "hello"));
assert_eq!(right, tuple!(3.14, [1, 2, 3]));

let (left, right) = split_at!(tup; 0);
assert_eq!(left, tuple!());
assert_eq!(right, tup);

let (left, right) = split_at!(tup; 4);
assert_eq!(left, tup);
assert_eq!(right, tuple!());

§Trait implementations on `Tuple`

For Tuple<T0, T1, ... Tn>, when all types T0, T1, … Tn implement the Debug / Clone / Copy / PartialEq / Eq / PartialOrd / Ord / Hash / Default / Neg / Not trait(s), then the Tuple<T0, T1, ... Tn> also implements it/them.

For example:

use tuplez::*;

let tup = tuple!(false, true, 26u8);            // All elements implement `Not`
assert_eq!(!tup, tuple!(true, false, 229u8));   // So `Tuple` also implements `Not`

For Tuple<T0, T1, ... Tn> and Tuple<U0, U1, ... Un>, when each Ti implements Trait<Ui> if the Trait is Add / AddAssign / Sub / SubAssign / Mul / MulAssign / Div / DivAssign / Rem / RemAssign / BitAnd / BitAndAssign / BitOr / BitOrAssign / BitXor / BitXorAssign / Shl / ShlAssign / Shr / ShrAssign, then Tuple<T0, T1, ... Tn> also implements Trait<Tuple<U0, U1, ... Un>>.

For example:

use tuplez::*;

let tup1 = tuple!(5, "hello ".to_string());
let tup2 = tuple!(4, "world");
assert_eq!(tup1 + tup2, tuple!(9, "hello world".to_string()));

When you try to implement your own traits on Tuples, remember the key idea - recursion. You bound Other with the same trait, and implement that trait for Unit as the termination of recursion.

This is an example of generating Fibonacci numbers based on Tuples:

use tuplez::*;

trait Fibonacci {
    const CURRENT: usize;
    const NEXT: usize;

    fn fib(&self) -> Vec<usize>;
}

impl Fibonacci for Unit {
    const CURRENT: usize = 0;
    const NEXT: usize = 1;

    fn fib(&self) -> Vec<usize> {
        vec![]
    }
}

impl<First, Other> Fibonacci for Tuple<First, Other>
where
    Other: TupleLike + Fibonacci,
{
    const CURRENT: usize = Other::NEXT;
    const NEXT: usize = Other::CURRENT + Other::NEXT;

    fn fib(&self) -> Vec<usize> {
        let mut v = self.1.fib();
        v.push(Self::CURRENT);
        v
    }
}

assert_eq!(tuple!((); 10).fib(), vec![1, 1, 2, 3, 5, 8, 13, 21, 34, 55]);

§Traverse tuples

You can traverse tuples by foreach(), foreach_mut() and foreach_once().

Silimar to Fn / FnMut / FnOnce, foreach() will traverse all elements in the form of &T, foreach_mut() will traverse all elements in the form of &mut T, and foreach_once() will traverse all elements in the form of T, so foreach_once() will take the ownership of the tuple.

Call foreach() / foreach_mut() / foreach_once() on a tuple requires a functor implementing Mapper / MapperMut / MapperOnce as the paramter. Check their documentation pages for examples.

However, here are mapper! / mapper_mut! / mapper_once! macros that can help you quickly generate a simple functor:

use tuplez::*;

fn to_string<T: ToString>(v: T) -> String {
    v.to_string()
}

let tup = tuple!(1, "hello", 3.14);
let tup2 = tup.foreach_once(mapper_once!{
    _ => String: to_string where ToString
});     // Currently, the bounds of the function must be written explicitly within the macro
assert_eq!(tup2, tuple!("1".to_string(), "hello".to_string(), "3.14".to_string()));

let tup3 = tup.foreach(mapper!{
   x: i32 => i64: *x as i64;
   x: f32 => String: x.to_string();
   x, 'a: &'a str => &'a [u8]: x.as_bytes()
});     // Reference types need to explicitly introduce its lifetime parameters
assert_eq!(tup3, tuple!(1i64, b"hello" as &[u8], "3.14".to_string()));

Check the documentation pages of these macros for detailed syntax.

§Convert from/to primitive tuples

Okay, we’re finally talking about the only interfaces of Tuple that limits the maximum number of elements.

Since Rust does not have a way to represent primitive tuple types with an arbitrary number of elements, the interfaces for converting from/to primitive tuple types is only implemented for Tuples with no more than 32 elements.

use tuplez::*;

let tup = tuple!(1, "hello", 3.14);
let prim_tup = (1, "hello", 3.14);
assert_eq!(tup.primitive(), prim_tup);
assert_eq!(tup, Tuple::from(prim_tup));

let unit = tuple!();
let prim_unit = ();
assert_eq!(unit.primitive(), prim_unit);
assert_eq!(unit, <tuple_t!()>::from(prim_unit));

§Convert from/to primitive arrays

If all elements of a tuple are of the same type, then it can be converted from/to primitive arrays.

Currently we can’t convert tuple from/to primitive arrays with no limit on the number of elements, since the generic constant expressions feature is still unstable yet.

Therefore, by default only tuples with no more than 32 elements are supported to be converted from/to primitive arrays.

However, if you are OK with using rustc released to nightly channel to compile codes with unstable features, you can enable the any_array feature, then tuplez will use unstable features to implement conversion from/to primitive arrays on tuples of any number of elements.

tuplez = { features = [ "any_array" ] }

For examples:

// Enable Rust's `generic_const_exprs` feature if you enable tuplez's `any_array` feature.
#![cfg_attr(feature = "any_array", feature(generic_const_exprs))]

use tuplez::*;

assert_eq!(tuple!(1, 2, 3, 4, 5, 6).to_array(), [1, 2, 3, 4, 5, 6]);
assert_eq!(<tuple_t!(i32; 4)>::from([1, 2, 3, 4]), tuple!(1, 2, 3, 4));

// `Unit` can be converted from/to array of any element type
let _ : [i32; 0] = tuple!().to_array();
let _ : [String; 0] = tuple!().to_array();
let _ = <tuple_t!()>::from([3.14; 0]);
let _ = <tuple_t!()>::from([""; 0]);

Tuple Fields§

§0: First

First element.

§1: Other

Other elements. See representation.

Struct tuplez::Tuple

§Representation

§Explicit tuple types

§Element access

§Push, pop, join and split

§Trait implementations on Tuple

§Traverse tuples

§Convert from/to primitive tuples

§Convert from/to primitive arrays

Tuple Fields§

Implementations§

impl<First, Other> Tuple<First, Other>where Other: TupleLike + Unwrap, First: Unwrap,

pub fn try_unwrap(self) -> Option<<Self as Unwrap>::Output>

§Example

Trait Implementations§

impl<First1, Other1, First2, Other2> Add<Tuple<First2, Other2>> for Tuple<First1, Other1>where First1: Add<First2>, Other1: Add<Other2>,

type Output = Tuple<<First1 as Add<First2>>::Output, <Other1 as Add<Other2>>::Output>

fn add(self, rhs: Tuple<First2, Other2>) -> Self::Output

impl<First1, Other1, First2, Other2> AddAssign<Tuple<First2, Other2>> for Tuple<First1, Other1>where First1: AddAssign<First2>, Other1: AddAssign<Other2>,

fn add_assign(&mut self, rhs: Tuple<First2, Other2>)

impl<First1, Other1, First2, Other2> BitAnd<Tuple<First2, Other2>> for Tuple<First1, Other1>where First1: BitAnd<First2>, Other1: BitAnd<Other2>,

type Output = Tuple<<First1 as BitAnd<First2>>::Output, <Other1 as BitAnd<Other2>>::Output>

fn bitand(self, rhs: Tuple<First2, Other2>) -> Self::Output

impl<First1, Other1, First2, Other2> BitAndAssign<Tuple<First2, Other2>> for Tuple<First1, Other1>where First1: BitAndAssign<First2>, Other1: BitAndAssign<Other2>,

fn bitand_assign(&mut self, rhs: Tuple<First2, Other2>)

impl<First1, Other1, First2, Other2> BitOr<Tuple<First2, Other2>> for Tuple<First1, Other1>where First1: BitOr<First2>, Other1: BitOr<Other2>,

type Output = Tuple<<First1 as BitOr<First2>>::Output, <Other1 as BitOr<Other2>>::Output>

fn bitor(self, rhs: Tuple<First2, Other2>) -> Self::Output

impl<First1, Other1, First2, Other2> BitOrAssign<Tuple<First2, Other2>> for Tuple<First1, Other1>where First1: BitOrAssign<First2>, Other1: BitOrAssign<Other2>,

fn bitor_assign(&mut self, rhs: Tuple<First2, Other2>)

impl<First1, Other1, First2, Other2> BitXor<Tuple<First2, Other2>> for Tuple<First1, Other1>where First1: BitXor<First2>, Other1: BitXor<Other2>,

type Output = Tuple<<First1 as BitXor<First2>>::Output, <Other1 as BitXor<Other2>>::Output>

fn bitxor(self, rhs: Tuple<First2, Other2>) -> Self::Output

impl<First1, Other1, First2, Other2> BitXorAssign<Tuple<First2, Other2>> for Tuple<First1, Other1>where First1: BitXorAssign<First2>, Other1: BitXorAssign<Other2>,

fn bitxor_assign(&mut self, rhs: Tuple<First2, Other2>)

impl<First: Clone, Other: Clone> Clone for Tuple<First, Other>

fn clone(&self) -> Tuple<First, Other>

fn clone_from(&mut self, source: &Self)

impl<First: Debug, Other: Debug> Debug for Tuple<First, Other>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

impl<First: Default, Other: Default> Default for Tuple<First, Other>

fn default() -> Tuple<First, Other>

impl<First1, Other1, First2, Other2> Div<Tuple<First2, Other2>> for Tuple<First1, Other1>where First1: Div<First2>, Other1: Div<Other2>,

type Output = Tuple<<First1 as Div<First2>>::Output, <Other1 as Div<Other2>>::Output>

fn div(self, rhs: Tuple<First2, Other2>) -> Self::Output

impl<First1, Other1, First2, Other2> DivAssign<Tuple<First2, Other2>> for Tuple<First1, Other1>where First1: DivAssign<First2>, Other1: DivAssign<Other2>,

fn div_assign(&mut self, rhs: Tuple<First2, Other2>)

impl<F, First, Other> Foreach<F> for Tuple<First, Other>where F: Mapper<First>, Other: Foreach<F>,

type Output = Tuple<<F as Mapper<First>>::Output, <Other as Foreach<F>>::Output>

fn foreach(&self, f: &mut F) -> Self::Output

impl<F, First, Other> ForeachMut<F> for Tuple<First, Other>where F: MapperMut<First>, Other: ForeachMut<F>,

type Output = Tuple<<F as MapperMut<First>>::Output, <Other as ForeachMut<F>>::Output>

fn foreach_mut(&mut self, f: &mut F) -> Self::Output

impl<F, First, Other> ForeachOnce<F> for Tuple<First, Other>where F: MapperOnce<First>, Other: ForeachOnce<F>,

type Output = Tuple<<F as MapperOnce<First>>::Output, <Other as ForeachOnce<F>>::Output>

fn foreach_once(self, f: &mut F) -> Self::Output

impl<T> From<[T; 1]> for Tuple<T, Unit>

fn from(arr: [T; 1]) -> Self

impl<T> From<[T; 10]> for Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Unit>>>>>>>>>>

fn from(arr: [T; 10]) -> Self

impl<T> From<[T; 11]> for Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Unit>>>>>>>>>>>

fn from(arr: [T; 11]) -> Self

impl<T> From<[T; 12]> for Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Unit>>>>>>>>>>>>

fn from(arr: [T; 12]) -> Self

impl<T> From<[T; 13]> for Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Unit>>>>>>>>>>>>>

fn from(arr: [T; 13]) -> Self

impl<T> From<[T; 14]> for Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Unit>>>>>>>>>>>>>>

fn from(arr: [T; 14]) -> Self

impl<T> From<[T; 15]> for Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Unit>>>>>>>>>>>>>>>

fn from(arr: [T; 15]) -> Self

impl<T> From<[T; 16]> for Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Unit>>>>>>>>>>>>>>>>

fn from(arr: [T; 16]) -> Self

impl<T> From<[T; 17]> for Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Unit>>>>>>>>>>>>>>>>>

fn from(arr: [T; 17]) -> Self

impl<T> From<[T; 18]> for Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Unit>>>>>>>>>>>>>>>>>>

fn from(arr: [T; 18]) -> Self

impl<T> From<[T; 19]> for Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Tuple<T, Unit>>>>>>>>>>>>>>>>>>>

fn from(arr: [T; 19]) -> Self

impl<T> From<[T; 2]> for Tuple<T, Tuple<T, Unit>>

fn from(arr: [T; 2]) -> Self

§Trait implementations on `Tuple`

impl<First, Other> Tuple<First, Other>
where Other: TupleLike + Unwrap, First: Unwrap,

impl<First1, Other1, First2, Other2> Add<Tuple<First2, Other2>> for Tuple<First1, Other1>
where First1: Add<First2>, Other1: Add<Other2>,

impl<First1, Other1, First2, Other2> AddAssign<Tuple<First2, Other2>> for Tuple<First1, Other1>
where First1: AddAssign<First2>, Other1: AddAssign<Other2>,

impl<First1, Other1, First2, Other2> BitAnd<Tuple<First2, Other2>> for Tuple<First1, Other1>
where First1: BitAnd<First2>, Other1: BitAnd<Other2>,

impl<First1, Other1, First2, Other2> BitAndAssign<Tuple<First2, Other2>> for Tuple<First1, Other1>
where First1: BitAndAssign<First2>, Other1: BitAndAssign<Other2>,

impl<First1, Other1, First2, Other2> BitOr<Tuple<First2, Other2>> for Tuple<First1, Other1>
where First1: BitOr<First2>, Other1: BitOr<Other2>,

impl<First1, Other1, First2, Other2> BitOrAssign<Tuple<First2, Other2>> for Tuple<First1, Other1>
where First1: BitOrAssign<First2>, Other1: BitOrAssign<Other2>,

impl<First1, Other1, First2, Other2> BitXor<Tuple<First2, Other2>> for Tuple<First1, Other1>
where First1: BitXor<First2>, Other1: BitXor<Other2>,

impl<First1, Other1, First2, Other2> BitXorAssign<Tuple<First2, Other2>> for Tuple<First1, Other1>
where First1: BitXorAssign<First2>, Other1: BitXorAssign<Other2>,

impl<First1, Other1, First2, Other2> Div<Tuple<First2, Other2>> for Tuple<First1, Other1>
where First1: Div<First2>, Other1: Div<Other2>,

impl<First1, Other1, First2, Other2> DivAssign<Tuple<First2, Other2>> for Tuple<First1, Other1>
where First1: DivAssign<First2>, Other1: DivAssign<Other2>,

impl<F, First, Other> Foreach<F> for Tuple<First, Other>
where F: Mapper<First>, Other: Foreach<F>,

impl<F, First, Other> ForeachMut<F> for Tuple<First, Other>
where F: MapperMut<First>, Other: ForeachMut<F>,

impl<F, First, Other> ForeachOnce<F> for Tuple<First, Other>
where F: MapperOnce<First>, Other: ForeachOnce<F>,