core/
tuple.rs

1// See core/src/primitive_docs.rs for documentation.
2
3use crate::cmp::Ordering::{self, *};
4use crate::marker::{ConstParamTy_, StructuralPartialEq, UnsizedConstParamTy};
5
6// Recursive macro for implementing n-ary tuple functions and operations
7//
8// Also provides implementations for tuples with lesser arity. For example, tuple_impls!(A B C)
9// will implement everything for (A, B, C), (A, B) and (A,).
10macro_rules! tuple_impls {
11    // Stopping criteria (1-ary tuple)
12    ($T:ident) => {
13        tuple_impls!(@impl $T);
14    };
15    // Running criteria (n-ary tuple, with n >= 2)
16    ($T:ident $( $U:ident )+) => {
17        tuple_impls!($( $U )+);
18        tuple_impls!(@impl $T $( $U )+);
19    };
20    // "Private" internal implementation
21    (@impl $( $T:ident )+) => {
22        maybe_tuple_doc! {
23            $($T)+ @
24            #[stable(feature = "rust1", since = "1.0.0")]
25            impl<$($T: PartialEq),+> PartialEq for ($($T,)+)
26            where
27                last_type!($($T,)+): ?Sized
28            {
29                #[inline]
30                fn eq(&self, other: &($($T,)+)) -> bool {
31                    $( ${ignore($T)} self.${index()} == other.${index()} )&&+
32                }
33                #[inline]
34                fn ne(&self, other: &($($T,)+)) -> bool {
35                    $( ${ignore($T)} self.${index()} != other.${index()} )||+
36                }
37            }
38        }
39
40        maybe_tuple_doc! {
41            $($T)+ @
42            #[stable(feature = "rust1", since = "1.0.0")]
43            impl<$($T: Eq),+> Eq for ($($T,)+)
44            where
45                last_type!($($T,)+): ?Sized
46            {}
47        }
48
49        maybe_tuple_doc! {
50            $($T)+ @
51            #[unstable(feature = "adt_const_params", issue = "95174")]
52            impl<$($T: ConstParamTy_),+> ConstParamTy_ for ($($T,)+)
53            {}
54        }
55
56        maybe_tuple_doc! {
57            $($T)+ @
58            #[unstable(feature = "unsized_const_params", issue = "95174")]
59            impl<$($T: UnsizedConstParamTy),+> UnsizedConstParamTy for ($($T,)+)
60            {}
61        }
62
63        maybe_tuple_doc! {
64            $($T)+ @
65            #[unstable(feature = "structural_match", issue = "31434")]
66            impl<$($T),+> StructuralPartialEq for ($($T,)+)
67            {}
68        }
69
70        maybe_tuple_doc! {
71            $($T)+ @
72            #[stable(feature = "rust1", since = "1.0.0")]
73            impl<$($T: PartialOrd),+> PartialOrd for ($($T,)+)
74            where
75                last_type!($($T,)+): ?Sized
76            {
77                #[inline]
78                fn partial_cmp(&self, other: &($($T,)+)) -> Option<Ordering> {
79                    lexical_partial_cmp!($( ${ignore($T)} self.${index()}, other.${index()} ),+)
80                }
81                #[inline]
82                fn lt(&self, other: &($($T,)+)) -> bool {
83                    lexical_ord!(lt, Less, $( ${ignore($T)} self.${index()}, other.${index()} ),+)
84                }
85                #[inline]
86                fn le(&self, other: &($($T,)+)) -> bool {
87                    lexical_ord!(le, Less, $( ${ignore($T)} self.${index()}, other.${index()} ),+)
88                }
89                #[inline]
90                fn ge(&self, other: &($($T,)+)) -> bool {
91                    lexical_ord!(ge, Greater, $( ${ignore($T)} self.${index()}, other.${index()} ),+)
92                }
93                #[inline]
94                fn gt(&self, other: &($($T,)+)) -> bool {
95                    lexical_ord!(gt, Greater, $( ${ignore($T)} self.${index()}, other.${index()} ),+)
96                }
97            }
98        }
99
100        maybe_tuple_doc! {
101            $($T)+ @
102            #[stable(feature = "rust1", since = "1.0.0")]
103            impl<$($T: Ord),+> Ord for ($($T,)+)
104            where
105                last_type!($($T,)+): ?Sized
106            {
107                #[inline]
108                fn cmp(&self, other: &($($T,)+)) -> Ordering {
109                    lexical_cmp!($( ${ignore($T)} self.${index()}, other.${index()} ),+)
110                }
111            }
112        }
113
114        maybe_tuple_doc! {
115            $($T)+ @
116            #[stable(feature = "rust1", since = "1.0.0")]
117            impl<$($T: Default),+> Default for ($($T,)+) {
118                #[inline]
119                fn default() -> ($($T,)+) {
120                    ($({ let x: $T = Default::default(); x},)+)
121                }
122            }
123        }
124
125        maybe_tuple_doc! {
126            $($T)+ @
127            #[stable(feature = "array_tuple_conv", since = "1.71.0")]
128            impl<T> From<[T; ${count($T)}]> for ($(${ignore($T)} T,)+) {
129                #[inline]
130                #[allow(non_snake_case)]
131                fn from(array: [T; ${count($T)}]) -> Self {
132                    let [$($T,)+] = array;
133                    ($($T,)+)
134                }
135            }
136        }
137
138        maybe_tuple_doc! {
139            $($T)+ @
140            #[stable(feature = "array_tuple_conv", since = "1.71.0")]
141            impl<T> From<($(${ignore($T)} T,)+)> for [T; ${count($T)}] {
142                #[inline]
143                #[allow(non_snake_case)]
144                fn from(tuple: ($(${ignore($T)} T,)+)) -> Self {
145                    let ($($T,)+) = tuple;
146                    [$($T,)+]
147                }
148            }
149        }
150    }
151}
152
153// If this is a unary tuple, it adds a doc comment.
154// Otherwise, it hides the docs entirely.
155macro_rules! maybe_tuple_doc {
156    ($a:ident @ #[$meta:meta] $item:item) => {
157        #[doc(fake_variadic)]
158        #[doc = "This trait is implemented for tuples up to twelve items long."]
159        #[$meta]
160        $item
161    };
162    ($a:ident $($rest_a:ident)+ @ #[$meta:meta] $item:item) => {
163        #[doc(hidden)]
164        #[$meta]
165        $item
166    };
167}
168
169// Constructs an expression that performs a lexical ordering using method `$rel`.
170// The values are interleaved, so the macro invocation for
171// `(a1, a2, a3) < (b1, b2, b3)` would be `lexical_ord!(lt, opt_is_lt, a1, b1,
172// a2, b2, a3, b3)` (and similarly for `lexical_cmp`)
173//
174// `$ne_rel` is only used to determine the result after checking that they're
175// not equal, so `lt` and `le` can both just use `Less`.
176macro_rules! lexical_ord {
177    ($rel: ident, $ne_rel: ident, $a:expr, $b:expr, $($rest_a:expr, $rest_b:expr),+) => {{
178        let c = PartialOrd::partial_cmp(&$a, &$b);
179        if c != Some(Equal) { c == Some($ne_rel) }
180        else { lexical_ord!($rel, $ne_rel, $($rest_a, $rest_b),+) }
181    }};
182    ($rel: ident, $ne_rel: ident, $a:expr, $b:expr) => {
183        // Use the specific method for the last element
184        PartialOrd::$rel(&$a, &$b)
185    };
186}
187
188macro_rules! lexical_partial_cmp {
189    ($a:expr, $b:expr, $($rest_a:expr, $rest_b:expr),+) => {
190        match ($a).partial_cmp(&$b) {
191            Some(Equal) => lexical_partial_cmp!($($rest_a, $rest_b),+),
192            ordering => ordering
193        }
194    };
195    ($a:expr, $b:expr) => { ($a).partial_cmp(&$b) };
196}
197
198macro_rules! lexical_cmp {
199    ($a:expr, $b:expr, $($rest_a:expr, $rest_b:expr),+) => {
200        match ($a).cmp(&$b) {
201            Equal => lexical_cmp!($($rest_a, $rest_b),+),
202            ordering => ordering
203        }
204    };
205    ($a:expr, $b:expr) => { ($a).cmp(&$b) };
206}
207
208macro_rules! last_type {
209    ($a:ident,) => { $a };
210    ($a:ident, $($rest_a:ident,)+) => { last_type!($($rest_a,)+) };
211}
212
213tuple_impls!(E D C B A Z Y X W V U T);