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: 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<I: Into<IpAddr>> From<(I, u16)> for SocketAddr

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<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.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type 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.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

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 !=.

impl<T> PartialOrd<(T,)> for (T₁, T₂, …, Tₙ) where
    T: PartialOrd<T> + PartialEq<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<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) -> bool where
    T: PartialOrd<U>,
    U: PartialOrd<T> + ?Sized, 

Returns true if item is contained in the range.

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) -> bool where
    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 (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 (&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 (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.