Primitive Type tuple

A finite heterogeneous sequence, (T, U, ..).

Let’s cover each of those in turn:

Tuples are finite. In other words, a tuple has a length. Here’s a tuple of length 3:

("hello", 5, 'c');

‘Length’ is also sometimes called ‘arity’ here; each tuple of a different length is a different, distinct type.

Tuples are heterogeneous. This means that each element of the tuple can have a different type. In that tuple above, it has the type:

(&'static str, i32, char)

Tuples are a sequence. This means that they can be accessed by position; this is called ‘tuple indexing’, and it looks like this:

let tuple = ("hello", 5, 'c');

assert_eq!(tuple.0, "hello");
assert_eq!(tuple.1, 5);
assert_eq!(tuple.2, 'c');

The sequential nature of the tuple applies to its implementations of various traits. For example, in PartialOrd and Ord, the elements are compared sequentially until the first non-equal set is found.

For more about tuples, see the book.

Trait implementations

In this documentation the shorthand (T₁, T₂, …, Tₙ) is used to represent tuples of varying length. When that is used, any trait bound expressed on T applies to each element of the tuple independently. Note that this is a convenience notation to avoid repetitive documentation, not valid Rust syntax.

Due to a temporary restriction in Rust’s type system, the following traits are only implemented on tuples of arity 12 or less. In the future, this may change:

• PartialEq
• Eq
• PartialOrd
• Ord
• Debug
• Default
• Hash

The following traits are implemented for tuples of any length. These traits have implementations that are automatically generated by the compiler, so are not limited by missing language features.

• Clone
• Copy
• Send
• Sync
• Unpin
• UnwindSafe
• RefUnwindSafe

Examples

Basic usage:

let tuple = ("hello", 5, 'c');

assert_eq!(tuple.0, "hello");

Tuples are often used as a return type when you want to return more than one value:

fn calculate_point() -> (i32, i32) {
    // Don't do a calculation, that's not the point of the example
    (4, 5)
}

let point = calculate_point();

assert_eq!(point.0, 4);
assert_eq!(point.1, 5);

// Combining this with patterns can be nicer.

let (x, y) = calculate_point();

assert_eq!(x, 4);
assert_eq!(y, 5);

Trait Implementations

impl<T: Clone> Clone for (T₁, T₂, …, Tₙ)

This trait is implemented on arbitrary-length tuples.

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T> Debug for (T₁, T₂, …, Tₙ)where
    T: ?Sized + Debug,

This trait is implemented for tuples up to twelve items long.

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

Formats the value using the given formatter.

impl<T: Default> Default for (T₁, T₂, …, Tₙ)

This trait is implemented for tuples up to twelve items long.

fn default() -> (T,)

Returns the “default value” for a type.

impl<A, B, ExtendA, ExtendB> Extend<(A, B)> for (ExtendA, ExtendB)where
    ExtendA: Extend<A>,
    ExtendB: Extend<B>,

fn extend<T: IntoIterator<Item = (A, B)>>(&mut self, into_iter: T)

Allows to extend a tuple of collections that also implement Extend.

See also: Iterator::unzip

Examples

let mut tuple = (vec![0], vec![1]);
tuple.extend([(2, 3), (4, 5), (6, 7)]);
assert_eq!(tuple.0, [0, 2, 4, 6]);
assert_eq!(tuple.1, [1, 3, 5, 7]);

// also allows for arbitrarily nested tuples as elements
let mut nested_tuple = (vec![1], (vec![2], vec![3]));
nested_tuple.extend([(4, (5, 6)), (7, (8, 9))]);

let (a, (b, c)) = nested_tuple;
assert_eq!(a, [1, 4, 7]);
assert_eq!(b, [2, 5, 8]);
assert_eq!(c, [3, 6, 9]);

fn extend_one(&mut self, item: (A, B))

🔬This is a nightly-only experimental API. (extend_one #72631)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one #72631)

Reserves capacity in a collection for the given number of additional elements.

impl<T> Hash for (T₁, T₂, …, Tₙ)where
    T: ?Sized + Hash,

This trait is implemented for tuples up to twelve items long.

fn hash<S: Hasher>(&self, state: &mut S)

Feeds this value into the given Hasher.

impl<T> Ord for (T₁, T₂, …, Tₙ)where
    T: ?Sized + Ord,

This trait is implemented for tuples up to twelve items long.

fn cmp(&self, other: &(T,)) -> Ordering

This method returns an Ordering between self and other.

impl<T> PartialEq<(T,)> for (T₁, T₂, …, Tₙ)where
    T: ?Sized + PartialEq,

This trait is implemented for tuples up to twelve items long.

fn eq(&self, other: &(T,)) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &(T,)) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialOrd<(T,)> for (T₁, T₂, …, Tₙ)where
    T: ?Sized + PartialOrd + PartialEq,

This trait is implemented for tuples up to twelve items long.

fn partial_cmp(&self, other: &(T,)) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &(T,)) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &(T,)) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn ge(&self, other: &(T,)) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

fn gt(&self, other: &(T,)) -> bool

This method tests greater than (for self and other) and is used by the > operator.

impl<'a, T: ?Sized + 'a> RangeBounds<T> for (Bound<&'a T>, Bound<&'a T>)

fn start_bound(&self) -> Bound<&T>

Start index bound.

fn end_bound(&self) -> Bound<&T>

End index bound.

fn contains<U>(&self, item: &U) -> boolwhere
    T: PartialOrd<U>,
    U: ?Sized + PartialOrd<T>,

Returns true if item is contained in the range.

impl<T> RangeBounds<T> for (Bound<T>, Bound<T>)

fn start_bound(&self) -> Bound<&T>

Start index bound.

fn end_bound(&self) -> Bound<&T>

End index bound.

fn contains<U>(&self, item: &U) -> boolwhere
    T: PartialOrd<U>,
    U: ?Sized + PartialOrd<T>,

Returns true if item is contained in the range.

impl<T> SliceIndex<[T]> for (Bound<usize>, Bound<usize>)

type Output = [T]

The output type returned by methods.

fn get(self, slice: &[T]) -> Option<&Self::Output>

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a shared reference to the output at this location, if in bounds.

fn get_mut(self, slice: &mut [T]) -> Option<&mut Self::Output>

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable reference to the output at this location, if in bounds.

unsafe fn get_unchecked(self, slice: *const [T]) -> *const Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a shared reference to the output at this location, without performing any bounds checking. Calling this method with an out-of-bounds index or a dangling slice pointer is undefined behavior even if the resulting reference is not used.

unsafe fn get_unchecked_mut(self, slice: *mut [T]) -> *mut Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable reference to the output at this location, without performing any bounds checking. Calling this method with an out-of-bounds index or a dangling slice pointer is undefined behavior even if the resulting reference is not used.

fn index(self, slice: &[T]) -> &Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a shared reference to the output at this location, panicking if out of bounds.

fn index_mut(self, slice: &mut [T]) -> &mut Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable reference to the output at this location, panicking if out of bounds.

impl<T: Copy> Copy for (T₁, T₂, …, Tₙ)

This trait is implemented on arbitrary-length tuples.

impl<T> Eq for (T₁, T₂, …, Tₙ)where
    T: ?Sized + Eq,

This trait is implemented for tuples up to twelve items long.