Primitive Type tuple
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
:
‘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:
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:
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.
§Examples
Basic usage:
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:
Trait Implementations§
1.0.0 · Source§impl<T> Debug for (T₁, T₂, …, Tₙ)
This trait is implemented for tuples up to twelve items long.
impl<T> Debug for (T₁, T₂, …, Tₙ)
This trait is implemented for tuples up to twelve items long.
1.0.0 · Source§impl<T> Default for (T₁, T₂, …, Tₙ)where
T: Default,
This trait is implemented for tuples up to twelve items long.
impl<T> Default for (T₁, T₂, …, Tₙ)where
T: Default,
This trait is implemented for tuples up to twelve items long.
1.2.0 · Source§impl<'a, K, V, A> Extend<(&'a K, &'a V)> for BTreeMap<K, V, A>
impl<'a, K, V, A> Extend<(&'a K, &'a V)> for BTreeMap<K, V, A>
1.4.0 · Source§impl<'a, K, V, S> Extend<(&'a K, &'a V)> for HashMap<K, V, S>
impl<'a, K, V, S> Extend<(&'a K, &'a V)> for HashMap<K, V, S>
Source§fn extend<T: IntoIterator<Item = (&'a K, &'a V)>>(&mut self, iter: T)
fn extend<T: IntoIterator<Item = (&'a K, &'a V)>>(&mut self, iter: T)
1.56.0 · Source§impl<A, EA> Extend<(A₁, A₂, …, Aₙ)> for (EA₁, EA₂, …, EAₙ)where
EA: Extend<A>,
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 CURRENT_RUSTC_VERSION.
impl<A, EA> Extend<(A₁, A₂, …, Aₙ)> for (EA₁, EA₂, …, EAₙ)where
EA: Extend<A>,
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 CURRENT_RUSTC_VERSION.
Source§fn extend<T>(&mut self, into_iter: T)where
T: IntoIterator<Item = (A,)>,
fn extend<T>(&mut self, into_iter: T)where
T: IntoIterator<Item = (A,)>,
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: (A,))
fn extend_one(&mut self, item: (A,))
extend_one
#72631)1.0.0 · Source§impl<K, V, A> Extend<(K, V)> for BTreeMap<K, V, A>
impl<K, V, A> Extend<(K, V)> for BTreeMap<K, V, A>
1.0.0 · Source§impl<K, V, S> Extend<(K, V)> for HashMap<K, V, S>
Inserts all new key-values from the iterator and replaces values with existing
keys with new values returned from the iterator.
impl<K, V, S> Extend<(K, V)> for HashMap<K, V, S>
Inserts all new key-values from the iterator and replaces values with existing keys with new values returned from the iterator.
1.71.0 · Source§impl<T> From<[T; N]> for (T₁, T₂, …, Tₙ)
This trait is implemented for tuples up to twelve items long.
impl<T> From<[T; N]> for (T₁, T₂, …, Tₙ)
This trait is implemented for tuples up to twelve items long.
1.17.0 · Source§impl<I> From<(I, u16)> for SocketAddr
impl<I> From<(I, u16)> for SocketAddr
Source§fn from(pieces: (I, u16)) -> 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
.
1.71.0 · Source§impl<T> From<(T₁, T₂, …, Tₙ)> for [T; N]
This trait is implemented for tuples up to twelve items long.
impl<T> From<(T₁, T₂, …, Tₙ)> for [T; N]
This trait is implemented for tuples up to twelve items long.
1.79.0 · Source§impl<A, B, AE, BE> FromIterator<(AE, BE)> for (A, B)
impl<A, B, AE, BE> FromIterator<(AE, BE)> for (A, B)
This is similar to Iterator::unzip
, but is also composable with other FromIterator
implementations:
1.0.0 · Source§impl<K, V, S> FromIterator<(K, V)> for HashMap<K, V, S>
impl<K, V, S> FromIterator<(K, V)> for HashMap<K, V, S>
1.0.0 · Source§impl<T> Hash for (T₁, T₂, …, Tₙ)
This trait is implemented for tuples up to twelve items long.
impl<T> Hash for (T₁, T₂, …, Tₙ)
This trait is implemented for tuples up to twelve items long.
1.0.0 · Source§impl<T> Ord for (T₁, T₂, …, Tₙ)
This trait is implemented for tuples up to twelve items long.
impl<T> Ord for (T₁, T₂, …, Tₙ)
This trait is implemented for tuples up to twelve items long.
1.0.0 · Source§impl<T> PartialEq for (T₁, T₂, …, Tₙ)
This trait is implemented for tuples up to twelve items long.
impl<T> PartialEq for (T₁, T₂, …, Tₙ)
This trait is implemented for tuples up to twelve items long.
1.0.0 · Source§impl<T> PartialOrd for (T₁, T₂, …, Tₙ)where
T: PartialOrd + ?Sized,
This trait is implemented for tuples up to twelve items long.
impl<T> PartialOrd for (T₁, T₂, …, Tₙ)where
T: PartialOrd + ?Sized,
This trait is implemented for tuples up to twelve items long.
1.28.0 · Source§impl<T> RangeBounds<T> for (Bound<T>, Bound<T>)
impl<T> RangeBounds<T> for (Bound<T>, Bound<T>)
1.53.0 · Source§impl<T> SliceIndex<[T]> for (Bound<usize>, Bound<usize>)
impl<T> SliceIndex<[T]> for (Bound<usize>, Bound<usize>)
Source§fn get(
self,
slice: &[T],
) -> Option<&<(Bound<usize>, Bound<usize>) as SliceIndex<[T]>>::Output>
fn get( self, slice: &[T], ) -> Option<&<(Bound<usize>, Bound<usize>) as SliceIndex<[T]>>::Output>
slice_index_methods
)Source§fn get_mut(
self,
slice: &mut [T],
) -> Option<&mut <(Bound<usize>, Bound<usize>) as SliceIndex<[T]>>::Output>
fn get_mut( self, slice: &mut [T], ) -> Option<&mut <(Bound<usize>, Bound<usize>) as SliceIndex<[T]>>::Output>
slice_index_methods
)Source§unsafe fn get_unchecked(
self,
slice: *const [T],
) -> *const <(Bound<usize>, Bound<usize>) as SliceIndex<[T]>>::Output
unsafe fn get_unchecked( self, slice: *const [T], ) -> *const <(Bound<usize>, Bound<usize>) as SliceIndex<[T]>>::Output
slice_index_methods
)Source§unsafe fn get_unchecked_mut(
self,
slice: *mut [T],
) -> *mut <(Bound<usize>, Bound<usize>) as SliceIndex<[T]>>::Output
unsafe fn get_unchecked_mut( self, slice: *mut [T], ) -> *mut <(Bound<usize>, Bound<usize>) as SliceIndex<[T]>>::Output
slice_index_methods
)1.73.0 · Source§impl SliceIndex<str> for (Bound<usize>, Bound<usize>)
Implements substring slicing for arbitrary bounds.
impl SliceIndex<str> for (Bound<usize>, Bound<usize>)
Implements substring slicing for arbitrary bounds.
Returns a slice of the given string bounded by the byte indices provided by each bound.
This operation is O(1).
§Panics
Panics if begin
or end
(if it exists and once adjusted for
inclusion/exclusion) does not point to the starting byte offset of
a character (as defined by is_char_boundary
), if begin > end
, or if
end > len
.
Source§fn get(self, slice: &str) -> Option<&str>
fn get(self, slice: &str) -> Option<&str>
slice_index_methods
)Source§fn get_mut(self, slice: &mut str) -> Option<&mut str>
fn get_mut(self, slice: &mut str) -> Option<&mut str>
slice_index_methods
)Source§unsafe fn get_unchecked(self, slice: *const str) -> *const str
unsafe fn get_unchecked(self, slice: *const str) -> *const str
slice_index_methods
)Source§unsafe fn get_unchecked_mut(self, slice: *mut str) -> *mut str
unsafe fn get_unchecked_mut(self, slice: *mut str) -> *mut str
slice_index_methods
)1.0.0 · Source§impl ToSocketAddrs for (&str, u16)
impl ToSocketAddrs for (&str, u16)
Source§type Iter = IntoIter<SocketAddr>
type Iter = IntoIter<SocketAddr>
Source§fn to_socket_addrs(&self) -> Result<IntoIter<SocketAddr>>
fn to_socket_addrs(&self) -> Result<IntoIter<SocketAddr>>
SocketAddr
s. Read more1.0.0 · Source§impl ToSocketAddrs for (IpAddr, u16)
impl ToSocketAddrs for (IpAddr, u16)
Source§type Iter = IntoIter<SocketAddr>
type Iter = IntoIter<SocketAddr>
Source§fn to_socket_addrs(&self) -> Result<IntoIter<SocketAddr>>
fn to_socket_addrs(&self) -> Result<IntoIter<SocketAddr>>
SocketAddr
s. Read more1.0.0 · Source§impl ToSocketAddrs for (Ipv4Addr, u16)
impl ToSocketAddrs for (Ipv4Addr, u16)
Source§type Iter = IntoIter<SocketAddr>
type Iter = IntoIter<SocketAddr>
Source§fn to_socket_addrs(&self) -> Result<IntoIter<SocketAddr>>
fn to_socket_addrs(&self) -> Result<IntoIter<SocketAddr>>
SocketAddr
s. Read more1.0.0 · Source§impl ToSocketAddrs for (Ipv6Addr, u16)
impl ToSocketAddrs for (Ipv6Addr, u16)
Source§type Iter = IntoIter<SocketAddr>
type Iter = IntoIter<SocketAddr>
Source§fn to_socket_addrs(&self) -> Result<IntoIter<SocketAddr>>
fn to_socket_addrs(&self) -> Result<IntoIter<SocketAddr>>
SocketAddr
s. Read more1.46.0 · Source§impl ToSocketAddrs for (String, u16)
impl ToSocketAddrs for (String, u16)
Source§type Iter = IntoIter<SocketAddr>
type Iter = IntoIter<SocketAddr>
Source§fn to_socket_addrs(&self) -> Result<IntoIter<SocketAddr>>
fn to_socket_addrs(&self) -> Result<IntoIter<SocketAddr>>
SocketAddr
s. Read moreimpl<T> ConstParamTy_ for (T₁, T₂, …, Tₙ)where
T: ConstParamTy_,
This trait is implemented for tuples up to twelve items long.
impl<T> Eq for (T₁, T₂, …, Tₙ)
This trait is implemented for tuples up to twelve items long.
impl<T> StructuralPartialEq for (T₁, T₂, …, Tₙ)
This trait is implemented for tuples up to twelve items long.
impl<T> UnsizedConstParamTy for (T₁, T₂, …, Tₙ)where
T: UnsizedConstParamTy,
This trait is implemented for tuples up to twelve items long.