src/libcore/tuple.rs

   1 // Copyright 2012 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 //! Operations on tuples
  12 //!
  13 //! To access a single element of a tuple one can use the following
  14 //! methods:
  15 //!
  16 //! * `valN` - returns a value of _N_-th element
  17 //! * `refN` - returns a reference to _N_-th element
  18 //! * `mutN` - returns a mutable reference to _N_-th element
  19 //!
  20 //! Indexing starts from zero, so `val0` returns first value, `val1`
  21 //! returns second value, and so on. In general, a tuple with _S_
  22 //! elements provides aforementioned methods suffixed with numbers
  23 //! from `0` to `S-1`. Traits which contain these methods are
  24 //! implemented for tuples with up to 12 elements.
  25 //!
  26 //! If every type inside a tuple implements one of the following
  27 //! traits, then a tuple itself also implements it.
  28 //!
  29 //! * `Clone`
  30 //! * `PartialEq`
  31 //! * `Eq`
  32 //! * `PartialOrd`
  33 //! * `Ord`
  34 //! * `Default`
  35
  36 #![stable]
  37
  38 #[unstable = "this is just a documentation module and should not be part \
  39               of the public api"]
  40
  41 use clone::Clone;
  42 use cmp::*;
  43 use cmp::Ordering::*;
  44 use default::Default;
  45 use option::Option;
  46 use option::Option::Some;
  47
  48 // FIXME(#19630) Remove this work-around
  49 macro_rules! e {
  50     ($e:expr) => { $e }
  51 }
  52
  53 // macro for implementing n-ary tuple functions and operations
  54 macro_rules! tuple_impls {
  55     ($(
  56         $Tuple:ident {
  57             $(($valN:ident, $refN:ident, $mutN:ident, $idx:tt) -> $T:ident)+
  58         }
  59     )+) => {
  60         $(
  61             #[allow(missing_docs)]
  62             #[deprecated]
  63             pub trait $Tuple<$($T),+> {
  64                 $(
  65                     #[deprecated = "use tuple indexing: `tuple.N`"]
  66                     fn $valN(self) -> $T;
  67                     #[deprecated = "use tuple indexing: `&tuple.N`"]
  68                     fn $refN<'a>(&'a self) -> &'a $T;
  69                     #[deprecated = "use tuple indexing: `&mut tuple.N`"]
  70                     fn $mutN<'a>(&'a mut self) -> &'a mut $T;
  71                  )+
  72             }
  73
  74             impl<$($T),+> $Tuple<$($T),+> for ($($T,)+) {
  75                 $(
  76                     #[inline]
  77                     #[allow(unused_variables)]
  78                     #[deprecated = "use tuple indexing: `tuple.N`"]
  79                     fn $valN(self) -> $T {
  80                         e!(self.$idx)
  81                     }
  82
  83                     #[inline]
  84                     #[allow(unused_variables)]
  85                     #[deprecated = "use tuple indexing: `&tuple.N`"]
  86                     fn $refN<'a>(&'a self) -> &'a $T {
  87                         e!(&self.$idx)
  88                     }
  89
  90                     #[inline]
  91                     #[allow(unused_variables)]
  92                     #[deprecated = "use tuple indexing: &mut tuple.N"]
  93                     fn $mutN<'a>(&'a mut self) -> &'a mut $T {
  94                         e!(&mut self.$idx)
  95                     }
  96                 )+
  97             }
  98
  99             #[stable]
 100             impl<$($T:Clone),+> Clone for ($($T,)+) {
 101                 fn clone(&self) -> ($($T,)+) {
 102                     ($(e!(self.$idx.clone()),)+)
 103                 }
 104             }
 105
 106             #[stable]
 107             impl<$($T:PartialEq),+> PartialEq for ($($T,)+) {
 108                 #[inline]
 109                 fn eq(&self, other: &($($T,)+)) -> bool {
 110                     e!($(self.$idx == other.$idx)&&+)
 111                 }
 112                 #[inline]
 113                 fn ne(&self, other: &($($T,)+)) -> bool {
 114                     e!($(self.$idx != other.$idx)||+)
 115                 }
 116             }
 117
 118             #[stable]
 119             impl<$($T:Eq),+> Eq for ($($T,)+) {}
 120
 121             #[stable]
 122             impl<$($T:PartialOrd + PartialEq),+> PartialOrd for ($($T,)+) {
 123                 #[inline]
 124                 fn partial_cmp(&self, other: &($($T,)+)) -> Option<Ordering> {
 125                     lexical_partial_cmp!($(self.$idx, other.$idx),+)
 126                 }
 127                 #[inline]
 128                 fn lt(&self, other: &($($T,)+)) -> bool {
 129                     lexical_ord!(lt, $(self.$idx, other.$idx),+)
 130                 }
 131                 #[inline]
 132                 fn le(&self, other: &($($T,)+)) -> bool {
 133                     lexical_ord!(le, $(self.$idx, other.$idx),+)
 134                 }
 135                 #[inline]
 136                 fn ge(&self, other: &($($T,)+)) -> bool {
 137                     lexical_ord!(ge, $(self.$idx, other.$idx),+)
 138                 }
 139                 #[inline]
 140                 fn gt(&self, other: &($($T,)+)) -> bool {
 141                     lexical_ord!(gt, $(self.$idx, other.$idx),+)
 142                 }
 143             }
 144
 145             #[stable]
 146             impl<$($T:Ord),+> Ord for ($($T,)+) {
 147                 #[inline]
 148                 fn cmp(&self, other: &($($T,)+)) -> Ordering {
 149                     lexical_cmp!($(self.$idx, other.$idx),+)
 150                 }
 151             }
 152
 153             #[stable]
 154             impl<$($T:Default),+> Default for ($($T,)+) {
 155                 #[stable]
 156                 #[inline]
 157                 fn default() -> ($($T,)+) {
 158                     ($({ let x: $T = Default::default(); x},)+)
 159                 }
 160             }
 161         )+
 162     }
 163 }
 164
 165 // Constructs an expression that performs a lexical ordering using method $rel.
 166 // The values are interleaved, so the macro invocation for
 167 // `(a1, a2, a3) < (b1, b2, b3)` would be `lexical_ord!(lt, a1, b1, a2, b2,
 168 // a3, b3)` (and similarly for `lexical_cmp`)
 169 macro_rules! lexical_ord {
 170     ($rel: ident, $a:expr, $b:expr, $($rest_a:expr, $rest_b:expr),+) => {
 171         if $a != $b { lexical_ord!($rel, $a, $b) }
 172         else { lexical_ord!($rel, $($rest_a, $rest_b),+) }
 173     };
 174     ($rel: ident, $a:expr, $b:expr) => { ($a) . $rel (& $b) };
 175 }
 176
 177 macro_rules! lexical_partial_cmp {
 178     ($a:expr, $b:expr, $($rest_a:expr, $rest_b:expr),+) => {
 179         match ($a).partial_cmp(&$b) {
 180             Some(Equal) => lexical_partial_cmp!($($rest_a, $rest_b),+),
 181             ordering   => ordering
 182         }
 183     };
 184     ($a:expr, $b:expr) => { ($a).partial_cmp(&$b) };
 185 }
 186
 187 macro_rules! lexical_cmp {
 188     ($a:expr, $b:expr, $($rest_a:expr, $rest_b:expr),+) => {
 189         match ($a).cmp(&$b) {
 190             Equal => lexical_cmp!($($rest_a, $rest_b),+),
 191             ordering   => ordering
 192         }
 193     };
 194     ($a:expr, $b:expr) => { ($a).cmp(&$b) };
 195 }
 196
 197 tuple_impls! {
 198     Tuple1 {
 199         (val0, ref0, mut0, 0) -> A
 200     }
 201     Tuple2 {
 202         (val0, ref0, mut0, 0) -> A
 203         (val1, ref1, mut1, 1) -> B
 204     }
 205     Tuple3 {
 206         (val0, ref0, mut0, 0) -> A
 207         (val1, ref1, mut1, 1) -> B
 208         (val2, ref2, mut2, 2) -> C
 209     }
 210     Tuple4 {
 211         (val0, ref0, mut0, 0) -> A
 212         (val1, ref1, mut1, 1) -> B
 213         (val2, ref2, mut2, 2) -> C
 214         (val3, ref3, mut3, 3) -> D
 215     }
 216     Tuple5 {
 217         (val0, ref0, mut0, 0) -> A
 218         (val1, ref1, mut1, 1) -> B
 219         (val2, ref2, mut2, 2) -> C
 220         (val3, ref3, mut3, 3) -> D
 221         (val4, ref4, mut4, 4) -> E
 222     }
 223     Tuple6 {
 224         (val0, ref0, mut0, 0) -> A
 225         (val1, ref1, mut1, 1) -> B
 226         (val2, ref2, mut2, 2) -> C
 227         (val3, ref3, mut3, 3) -> D
 228         (val4, ref4, mut4, 4) -> E
 229         (val5, ref5, mut5, 5) -> F
 230     }
 231     Tuple7 {
 232         (val0, ref0, mut0, 0) -> A
 233         (val1, ref1, mut1, 1) -> B
 234         (val2, ref2, mut2, 2) -> C
 235         (val3, ref3, mut3, 3) -> D
 236         (val4, ref4, mut4, 4) -> E
 237         (val5, ref5, mut5, 5) -> F
 238         (val6, ref6, mut6, 6) -> G
 239     }
 240     Tuple8 {
 241         (val0, ref0, mut0, 0) -> A
 242         (val1, ref1, mut1, 1) -> B
 243         (val2, ref2, mut2, 2) -> C
 244         (val3, ref3, mut3, 3) -> D
 245         (val4, ref4, mut4, 4) -> E
 246         (val5, ref5, mut5, 5) -> F
 247         (val6, ref6, mut6, 6) -> G
 248         (val7, ref7, mut7, 7) -> H
 249     }
 250     Tuple9 {
 251         (val0, ref0, mut0, 0) -> A
 252         (val1, ref1, mut1, 1) -> B
 253         (val2, ref2, mut2, 2) -> C
 254         (val3, ref3, mut3, 3) -> D
 255         (val4, ref4, mut4, 4) -> E
 256         (val5, ref5, mut5, 5) -> F
 257         (val6, ref6, mut6, 6) -> G
 258         (val7, ref7, mut7, 7) -> H
 259         (val8, ref8, mut8, 8) -> I
 260     }
 261     Tuple10 {
 262         (val0, ref0, mut0, 0) -> A
 263         (val1, ref1, mut1, 1) -> B
 264         (val2, ref2, mut2, 2) -> C
 265         (val3, ref3, mut3, 3) -> D
 266         (val4, ref4, mut4, 4) -> E
 267         (val5, ref5, mut5, 5) -> F
 268         (val6, ref6, mut6, 6) -> G
 269         (val7, ref7, mut7, 7) -> H
 270         (val8, ref8, mut8, 8) -> I
 271         (val9, ref9, mut9, 9) -> J
 272     }
 273     Tuple11 {
 274         (val0, ref0, mut0, 0) -> A
 275         (val1, ref1, mut1, 1) -> B
 276         (val2, ref2, mut2, 2) -> C
 277         (val3, ref3, mut3, 3) -> D
 278         (val4, ref4, mut4, 4) -> E
 279         (val5, ref5, mut5, 5) -> F
 280         (val6, ref6, mut6, 6) -> G
 281         (val7, ref7, mut7, 7) -> H
 282         (val8, ref8, mut8, 8) -> I
 283         (val9, ref9, mut9, 9) -> J
 284         (val10, ref10, mut10, 10) -> K
 285     }
 286     Tuple12 {
 287         (val0, ref0, mut0, 0) -> A
 288         (val1, ref1, mut1, 1) -> B
 289         (val2, ref2, mut2, 2) -> C
 290         (val3, ref3, mut3, 3) -> D
 291         (val4, ref4, mut4, 4) -> E
 292         (val5, ref5, mut5, 5) -> F
 293         (val6, ref6, mut6, 6) -> G
 294         (val7, ref7, mut7, 7) -> H
 295         (val8, ref8, mut8, 8) -> I
 296         (val9, ref9, mut9, 9) -> J
 297         (val10, ref10, mut10, 10) -> K
 298         (val11, ref11, mut11, 11) -> L
 299     }
 300 }