tuple - Rust
Skip to main content tuple Primitive Type tuple 1.0.0 Expand description 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 ); Homogeneous 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 § Source § impl<T: CloneFromCell > CloneFromCell for (T₁, T₂, …, Tₙ) This trait is implemented for tuples up to twelve items long.
Source § impl<T: ConstParamTy_ > ConstParamTy_ for (T₁, T₂, …, Tₙ) This trait is implemented for tuples up to twelve items long. 1.0.0 · Source § impl<T: Debug > Debug for (T₁, T₂, …, Tₙ) This trait is implemented for tuples up to twelve items long. Source § fn fmt (&self, f: &mut Formatter <'_>) -> Result Formats the value using the given formatter. Read more 1.0.0 (const: unstable ) · Source § impl<T: Default > Default for (T₁, T₂, …, Tₙ) This trait is implemented for tuples up to twelve items long.
Source § fn default () -> (T,) Returns the “default value” for a type. Read more 1.0.0 (const: unstable ) · Source § impl<T: Eq > Eq for (T₁, T₂, …, Tₙ) This trait is implemented for tuples up to twelve items long. 1.56.0 · Source § impl<T, ExtendT> Extend < (T₁, T₂, …, Tₙ) > for (ExtendT₁, ExtendT₂, …, ExtendTₙ) where ExtendT: Extend <T>, This trait is implemented for tuples up to twelve items long.
The impl s for 1- and 3- through 12-ary tuples were stabilized after 2-tuples, in 1.85.0. Source § fn extend <I: IntoIterator <Item = (T,) >>(&mut self, iter: I) Allows to extend a tuple of collections that also implement Extend . See also: Iterator::unzip § Examples // Example given for a 2-tuple, but 1- through 12-tuples are supported 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 ]); Source § fn extend_one (&mut self, item: (T,) ) 🔬 This is a nightly-only experimental API. ( extend_one #72631 ) Extends a collection with exactly one element.
Source § 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. Read more 1.17.0 (const: unstable ) · Source § impl<I: Into < IpAddr >> From <(I, u16 )> for SocketAddr Source § 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 . 1.71.0 · Source § impl<T> From < (T₁, T₂, …, Tₙ) > for [T; N] This trait is implemented for tuples up to twelve items long. Source § fn from (tuple: (T,) ) -> Self Converts to this type from the input type. 1.71.0 · Source § impl<T> From < [T; N] > for (T₁, T₂, …, Tₙ) This trait is implemented for tuples up to twelve items long.
Source § fn from (array: [T; 1] ) -> Self Converts to this type from the input type. 1.79.0 · Source § impl<T, ExtendT> FromIterator < (T₁, T₂, …, Tₙ) > for (ExtendT₁, ExtendT₂, …, ExtendTₙ) where ExtendT: Default + Extend <T>, This implementation turns an iterator of tuples into a tuple of types which implement Default and Extend . This is similar to Iterator::unzip , but is also composable with other FromIterator implementations: let string = "1,2,123,4" ; // Example given for a 2-tuple, but 1- through 12-tuples are supported let (numbers, lengths): (Vec< _ >, Vec< _ >) = string .split( ',' ) .map(|s| s.parse().map(|n: u32| (n, s.len()))) .collect::< Result < _ , _ >>() ? ; assert_eq! (numbers, [ 1 , 2 , 123 , 4 ]); assert_eq! (lengths, [ 1 , 1 , 3 , 1 ]); Source § fn from_iter <Iter: IntoIterator <Item = (T,) >>(iter: Iter) -> Self Creates a value from an iterator.
Read more 1.0.0 · Source § impl<T: Hash > Hash for (T₁, T₂, …, Tₙ) This trait is implemented for tuples up to twelve items long. Source § fn hash <S: Hasher >(&self, state: &mut S ) Feeds this value into the given Hasher . Read more 1.3.0 · Source § fn hash_slice <H: Hasher >(data: &[Self], state: &mut H ) where Self: Sized , Feeds a slice of this type into the given Hasher . Read more Source § impl<T> IntoBounds <T> for ( Bound <T>, Bound <T>) Source § fn into_bounds (self) -> ( Bound <T>, Bound <T>) 🔬 This is a nightly-only experimental API. ( range_into_bounds #136903 ) Convert this range into the start and end bounds.
Returns (start_bound, end_bound) . Read more Source § fn intersect <R>(self, other: R) -> ( Bound <T>, Bound <T>) where Self: Sized , T: Ord , R: Sized + IntoBounds <T>, 🔬 This is a nightly-only experimental API. ( range_into_bounds #136903 ) Compute the intersection of self and other . Read more 1.0.0 (const: unstable ) · Source § impl<T: Ord > Ord for (T₁, T₂, …, Tₙ) This trait is implemented for tuples up to twelve items long.
Source § fn cmp (&self, other: & (T,) ) -> Ordering This method returns an Ordering between self and other . Read more 1.21.0 (const: unstable ) · Source § fn max (self, other: Self) -> Self where Self: Sized , Compares and returns the maximum of two values. Read more 1.21.0 (const: unstable ) · Source § fn min (self, other: Self) -> Self where Self: Sized , Compares and returns the minimum of two values. Read more 1.50.0
The rest of this page is on the live site.