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
• From<[T; N]>

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);

Homogenous tuples can be created from arrays of appropriate length:

let array: [u32; 3] = [1, 2, 3];
let tuple: (u32, u32, u32) = array.into();

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: Debug + ?Sized,

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

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

Formats the value using the given formatter.

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

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

fn default() -> (T,)

Returns the “default value” for a type.

impl<'a, K, V, A> Extend<(&'a K, &'a V)> for BTreeMap<K, V, A>where K: Ord + Copy, V: Copy, A: Allocator + Clone,

fn extend<I>(&mut self, iter: I)where I: IntoIterator<Item = (&'a K, &'a V)>,

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, _: (&'a K, &'a V))

🔬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<'a, K, V, S> Extend<(&'a K, &'a V)> for HashMap<K, V, S>where K: Eq + Hash + Copy, V: Copy, S: BuildHasher,

fn extend<T: IntoIterator<Item = (&'a K, &'a V)>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, (k, v): (&'a K, &'a V))

🔬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<A, B, ExtendA, ExtendB> Extend<(A, B)> for (ExtendA, ExtendB)where ExtendA: Extend<A>, ExtendB: Extend<B>,

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

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<K, V, A> Extend<(K, V)> for BTreeMap<K, V, A>where K: Ord, A: Allocator + Clone,

fn extend<T>(&mut self, iter: T)where T: IntoIterator<Item = (K, V)>,

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, _: (K, V))

🔬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<K, V, S> Extend<(K, V)> for HashMap<K, V, S>where K: Eq + Hash, S: BuildHasher,

Inserts all new key-values from the iterator and replaces values with existing keys with new values returned from the iterator.

fn extend<T: IntoIterator<Item = (K, V)>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, (k, v): (K, V))

🔬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> From<[T; 1]> for (T,)

fn from(array: [T; 1]) -> (T,)

Converts to this type from the input type.

impl<T> From<[T; 10]> for (T, T, T, T, T, T, T, T, T, T)

fn from(array: [T; 10]) -> (T, T, T, T, T, T, T, T, T, T)

Converts to this type from the input type.

impl<T> From<[T; 11]> for (T, T, T, T, T, T, T, T, T, T, T)

fn from(array: [T; 11]) -> (T, T, T, T, T, T, T, T, T, T, T)

Converts to this type from the input type.

impl<T> From<[T; 12]> for (T, T, T, T, T, T, T, T, T, T, T, T)

fn from(array: [T; 12]) -> (T, T, T, T, T, T, T, T, T, T, T, T)

Converts to this type from the input type.

impl<T> From<[T; 2]> for (T, T)

fn from(array: [T; 2]) -> (T, T)

Converts to this type from the input type.

impl<T> From<[T; 3]> for (T, T, T)

fn from(array: [T; 3]) -> (T, T, T)

Converts to this type from the input type.

impl<T> From<[T; 4]> for (T, T, T, T)

fn from(array: [T; 4]) -> (T, T, T, T)

Converts to this type from the input type.

impl<T> From<[T; 5]> for (T, T, T, T, T)

fn from(array: [T; 5]) -> (T, T, T, T, T)

Converts to this type from the input type.

impl<T> From<[T; 6]> for (T, T, T, T, T, T)

fn from(array: [T; 6]) -> (T, T, T, T, T, T)

Converts to this type from the input type.

impl<T> From<[T; 7]> for (T, T, T, T, T, T, T)

fn from(array: [T; 7]) -> (T, T, T, T, T, T, T)

Converts to this type from the input type.

impl<T> From<[T; 8]> for (T, T, T, T, T, T, T, T)

fn from(array: [T; 8]) -> (T, T, T, T, T, T, T, T)

Converts to this type from the input type.

impl<T> From<[T; 9]> for (T, T, T, T, T, T, T, T, T)

fn from(array: [T; 9]) -> (T, T, T, T, T, T, T, T, T)

Converts to this type from the input type.

impl<I> From<(I, u16)> for SocketAddrwhere I: Into<IpAddr>,

fn from(pieces: (I, u16)) -> SocketAddr

Converts a tuple struct (Into<IpAddr>, u16) into a SocketAddr.

This conversion creates a SocketAddr::V4 for an IpAddr::V4 and creates a SocketAddr::V6 for an IpAddr::V6.

u16 is treated as port of the newly created SocketAddr.

impl<T> From<(T,)> for [T; 1]

fn from(tuple: (T,)) -> [T; 1]

Converts to this type from the input type.

impl<T> From<(T, T)> for [T; 2]

fn from(tuple: (T, T)) -> [T; 2]

Converts to this type from the input type.

impl<T> From<(T, T, T)> for [T; 3]

fn from(tuple: (T, T, T)) -> [T; 3]

Converts to this type from the input type.

impl<T> From<(T, T, T, T)> for [T; 4]

fn from(tuple: (T, T, T, T)) -> [T; 4]

Converts to this type from the input type.

impl<T> From<(T, T, T, T, T)> for [T; 5]

fn from(tuple: (T, T, T, T, T)) -> [T; 5]

Converts to this type from the input type.

impl<T> From<(T, T, T, T, T, T)> for [T; 6]

fn from(tuple: (T, T, T, T, T, T)) -> [T; 6]

Converts to this type from the input type.

impl<T> From<(T, T, T, T, T, T, T)> for [T; 7]

fn from(tuple: (T, T, T, T, T, T, T)) -> [T; 7]

Converts to this type from the input type.

impl<T> From<(T, T, T, T, T, T, T, T)> for [T; 8]

fn from(tuple: (T, T, T, T, T, T, T, T)) -> [T; 8]

Converts to this type from the input type.

impl<T> From<(T, T, T, T, T, T, T, T, T)> for [T; 9]

fn from(tuple: (T, T, T, T, T, T, T, T, T)) -> [T; 9]

Converts to this type from the input type.

impl<T> From<(T, T, T, T, T, T, T, T, T, T)> for [T; 10]

fn from(tuple: (T, T, T, T, T, T, T, T, T, T)) -> [T; 10]

Converts to this type from the input type.

impl<T> From<(T, T, T, T, T, T, T, T, T, T, T)> for [T; 11]

fn from(tuple: (T, T, T, T, T, T, T, T, T, T, T)) -> [T; 11]

Converts to this type from the input type.

impl<T> From<(T, T, T, T, T, T, T, T, T, T, T, T)> for [T; 12]

fn from(tuple: (T, T, T, T, T, T, T, T, T, T, T, T)) -> [T; 12]

Converts to this type from the input type.

impl<K, V> FromIterator<(K, V)> for BTreeMap<K, V, Global>where K: Ord,

fn from_iter<T>(iter: T) -> BTreeMap<K, V, Global>where T: IntoIterator<Item = (K, V)>,

Creates a value from an iterator.

impl<K, V, S> FromIterator<(K, V)> for HashMap<K, V, S>where K: Eq + Hash, S: BuildHasher + Default,

fn from_iter<T: IntoIterator<Item = (K, V)>>(iter: T) -> HashMap<K, V, S>

Creates a value from an iterator.

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

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

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

Feeds this value into the given Hasher.

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

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: PartialEq<T> + ?Sized,

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: PartialOrd<T> + ?Sized,

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> RangeBounds<T> for (Bound<&'a T>, Bound<&'a T>)where T: 'a + ?Sized,

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: PartialOrd<T> + ?Sized,

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: PartialOrd<T> + ?Sized,

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<&<(Bound<usize>, Bound<usize>) as SliceIndex<[T]>>::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 <(Bound<usize>, Bound<usize>) as SliceIndex<[T]>>::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 <(Bound<usize>, Bound<usize>) as SliceIndex<[T]>>::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 <(Bound<usize>, Bound<usize>) as SliceIndex<[T]>>::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] ) -> &<(Bound<usize>, Bound<usize>) as SliceIndex<[T]>>::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 <(Bound<usize>, Bound<usize>) as SliceIndex<[T]>>::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 ToSocketAddrs for (&str, u16)

type Iter = IntoIter<SocketAddr, Global>

Returned iterator over socket addresses which this type may correspond to.

fn to_socket_addrs(&self) -> Result<IntoIter<SocketAddr>>

Converts this object to an iterator of resolved SocketAddrs.

impl ToSocketAddrs for (IpAddr, u16)

type Iter = IntoIter<SocketAddr>

Returned iterator over socket addresses which this type may correspond to.

fn to_socket_addrs(&self) -> Result<IntoIter<SocketAddr>>

Converts this object to an iterator of resolved SocketAddrs.

impl ToSocketAddrs for (Ipv4Addr, u16)

type Iter = IntoIter<SocketAddr>

Returned iterator over socket addresses which this type may correspond to.

fn to_socket_addrs(&self) -> Result<IntoIter<SocketAddr>>

Converts this object to an iterator of resolved SocketAddrs.

impl ToSocketAddrs for (Ipv6Addr, u16)

type Iter = IntoIter<SocketAddr>

Returned iterator over socket addresses which this type may correspond to.

fn to_socket_addrs(&self) -> Result<IntoIter<SocketAddr>>

Converts this object to an iterator of resolved SocketAddrs.

impl ToSocketAddrs for (String, u16)

type Iter = IntoIter<SocketAddr, Global>

Returned iterator over socket addresses which this type may correspond to.

fn to_socket_addrs(&self) -> Result<IntoIter<SocketAddr>>

Converts this object to an iterator of resolved SocketAddrs.

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: Eq + ?Sized,

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