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 //! # Examples
  37 //!
  38 //! Using methods:
  39 //!
  40 //! ```
  41 //! #[allow(deprecated)]
  42 //! # fn main() {
  43 //! let pair = ("pi", 3.14f64);
  44 //! assert_eq!(pair.val0(), "pi");
  45 //! assert_eq!(pair.val1(), 3.14f64);
  46 //! # }
  47 //! ```
  48 //!
  49 //! Using traits implemented for tuples:
  50 //!
  51 //! ```
  52 //! use std::default::Default;
  53 //!
  54 //! let a = (1i, 2i);
  55 //! let b = (3i, 4i);
  56 //! assert!(a != b);
  57 //!
  58 //! let c = b.clone();
  59 //! assert!(b == c);
  60 //!
  61 //! let d : (u32, f32) = Default::default();
  62 //! assert_eq!(d, (0u32, 0.0f32));
  63 //! ```
  64
  65 #![stable]
  66
  67 #[unstable = "this is just a documentation module and should not be part \
  68               of the public api"]
  69
  70 use clone::Clone;
  71 use cmp::*;
  72 use cmp::Ordering::*;
  73 use default::Default;
  74 use option::Option;
  75 use option::Option::Some;
  76
  77 // FIXME(#19630) Remove this work-around
  78 macro_rules! e {
  79     ($e:expr) => { $e }
  80 }
  81
  82 // macro for implementing n-ary tuple functions and operations
  83 macro_rules! tuple_impls {
  84     ($(
  85         $Tuple:ident {
  86             $(($valN:ident, $refN:ident, $mutN:ident, $idx:tt) -> $T:ident)+
  87         }
  88     )+) => {
  89         $(
  90             #[allow(missing_docs)]
  91             #[deprecated]
  92             pub trait $Tuple<$($T),+> {
  93                 $(
  94                     #[deprecated = "use tuple indexing: `tuple.N`"]
  95                     fn $valN(self) -> $T;
  96                     #[deprecated = "use tuple indexing: `&tuple.N`"]
  97                     fn $refN<'a>(&'a self) -> &'a $T;
  98                     #[deprecated = "use tuple indexing: `&mut tuple.N`"]
  99                     fn $mutN<'a>(&'a mut self) -> &'a mut $T;
 100                  )+
 101             }
 102
 103             impl<$($T),+> $Tuple<$($T),+> for ($($T,)+) {
 104                 $(
 105                     #[inline]
 106                     #[allow(unused_variables)]
 107                     #[deprecated = "use tuple indexing: `tuple.N`"]
 108                     fn $valN(self) -> $T {
 109                         e!(self.$idx)
 110                     }
 111
 112                     #[inline]
 113                     #[allow(unused_variables)]
 114                     #[deprecated = "use tuple indexing: `&tuple.N`"]
 115                     fn $refN<'a>(&'a self) -> &'a $T {
 116                         e!(&self.$idx)
 117                     }
 118
 119                     #[inline]
 120                     #[allow(unused_variables)]
 121                     #[deprecated = "use tuple indexing: &mut tuple.N"]
 122                     fn $mutN<'a>(&'a mut self) -> &'a mut $T {
 123                         e!(&mut self.$idx)
 124                     }
 125                 )+
 126             }
 127
 128             #[stable]
 129             impl<$($T:Clone),+> Clone for ($($T,)+) {
 130                 fn clone(&self) -> ($($T,)+) {
 131                     ($(e!(self.$idx.clone()),)+)
 132                 }
 133             }
 134
 135             #[stable]
 136             impl<$($T:PartialEq),+> PartialEq for ($($T,)+) {
 137                 #[inline]
 138                 fn eq(&self, other: &($($T,)+)) -> bool {
 139                     e!($(self.$idx == other.$idx)&&+)
 140                 }
 141                 #[inline]
 142                 fn ne(&self, other: &($($T,)+)) -> bool {
 143                     e!($(self.$idx != other.$idx)||+)
 144                 }
 145             }
 146
 147             #[stable]
 148             impl<$($T:Eq),+> Eq for ($($T,)+) {}
 149
 150             #[stable]
 151             impl<$($T:PartialOrd + PartialEq),+> PartialOrd for ($($T,)+) {
 152                 #[inline]
 153                 fn partial_cmp(&self, other: &($($T,)+)) -> Option<Ordering> {
 154                     lexical_partial_cmp!($(self.$idx, other.$idx),+)
 155                 }
 156                 #[inline]
 157                 fn lt(&self, other: &($($T,)+)) -> bool {
 158                     lexical_ord!(lt, $(self.$idx, other.$idx),+)
 159                 }
 160                 #[inline]
 161                 fn le(&self, other: &($($T,)+)) -> bool {
 162                     lexical_ord!(le, $(self.$idx, other.$idx),+)
 163                 }
 164                 #[inline]
 165                 fn ge(&self, other: &($($T,)+)) -> bool {
 166                     lexical_ord!(ge, $(self.$idx, other.$idx),+)
 167                 }
 168                 #[inline]
 169                 fn gt(&self, other: &($($T,)+)) -> bool {
 170                     lexical_ord!(gt, $(self.$idx, other.$idx),+)
 171                 }
 172             }
 173
 174             #[stable]
 175             impl<$($T:Ord),+> Ord for ($($T,)+) {
 176                 #[inline]
 177                 fn cmp(&self, other: &($($T,)+)) -> Ordering {
 178                     lexical_cmp!($(self.$idx, other.$idx),+)
 179                 }
 180             }
 181
 182             #[stable]
 183             impl<$($T:Default),+> Default for ($($T,)+) {
 184                 #[stable]
 185                 #[inline]
 186                 fn default() -> ($($T,)+) {
 187                     ($({ let x: $T = Default::default(); x},)+)
 188                 }
 189             }
 190         )+
 191     }
 192 }
 193
 194 // Constructs an expression that performs a lexical ordering using method $rel.
 195 // The values are interleaved, so the macro invocation for
 196 // `(a1, a2, a3) < (b1, b2, b3)` would be `lexical_ord!(lt, a1, b1, a2, b2,
 197 // a3, b3)` (and similarly for `lexical_cmp`)
 198 macro_rules! lexical_ord {
 199     ($rel: ident, $a:expr, $b:expr, $($rest_a:expr, $rest_b:expr),+) => {
 200         if $a != $b { lexical_ord!($rel, $a, $b) }
 201         else { lexical_ord!($rel, $($rest_a, $rest_b),+) }
 202     };
 203     ($rel: ident, $a:expr, $b:expr) => { ($a) . $rel (& $b) };
 204 }
 205
 206 macro_rules! lexical_partial_cmp {
 207     ($a:expr, $b:expr, $($rest_a:expr, $rest_b:expr),+) => {
 208         match ($a).partial_cmp(&$b) {
 209             Some(Equal) => lexical_partial_cmp!($($rest_a, $rest_b),+),
 210             ordering   => ordering
 211         }
 212     };
 213     ($a:expr, $b:expr) => { ($a).partial_cmp(&$b) };
 214 }
 215
 216 macro_rules! lexical_cmp {
 217     ($a:expr, $b:expr, $($rest_a:expr, $rest_b:expr),+) => {
 218         match ($a).cmp(&$b) {
 219             Equal => lexical_cmp!($($rest_a, $rest_b),+),
 220             ordering   => ordering
 221         }
 222     };
 223     ($a:expr, $b:expr) => { ($a).cmp(&$b) };
 224 }
 225
 226 tuple_impls! {
 227     Tuple1 {
 228         (val0, ref0, mut0, 0) -> A
 229     }
 230     Tuple2 {
 231         (val0, ref0, mut0, 0) -> A
 232         (val1, ref1, mut1, 1) -> B
 233     }
 234     Tuple3 {
 235         (val0, ref0, mut0, 0) -> A
 236         (val1, ref1, mut1, 1) -> B
 237         (val2, ref2, mut2, 2) -> C
 238     }
 239     Tuple4 {
 240         (val0, ref0, mut0, 0) -> A
 241         (val1, ref1, mut1, 1) -> B
 242         (val2, ref2, mut2, 2) -> C
 243         (val3, ref3, mut3, 3) -> D
 244     }
 245     Tuple5 {
 246         (val0, ref0, mut0, 0) -> A
 247         (val1, ref1, mut1, 1) -> B
 248         (val2, ref2, mut2, 2) -> C
 249         (val3, ref3, mut3, 3) -> D
 250         (val4, ref4, mut4, 4) -> E
 251     }
 252     Tuple6 {
 253         (val0, ref0, mut0, 0) -> A
 254         (val1, ref1, mut1, 1) -> B
 255         (val2, ref2, mut2, 2) -> C
 256         (val3, ref3, mut3, 3) -> D
 257         (val4, ref4, mut4, 4) -> E
 258         (val5, ref5, mut5, 5) -> F
 259     }
 260     Tuple7 {
 261         (val0, ref0, mut0, 0) -> A
 262         (val1, ref1, mut1, 1) -> B
 263         (val2, ref2, mut2, 2) -> C
 264         (val3, ref3, mut3, 3) -> D
 265         (val4, ref4, mut4, 4) -> E
 266         (val5, ref5, mut5, 5) -> F
 267         (val6, ref6, mut6, 6) -> G
 268     }
 269     Tuple8 {
 270         (val0, ref0, mut0, 0) -> A
 271         (val1, ref1, mut1, 1) -> B
 272         (val2, ref2, mut2, 2) -> C
 273         (val3, ref3, mut3, 3) -> D
 274         (val4, ref4, mut4, 4) -> E
 275         (val5, ref5, mut5, 5) -> F
 276         (val6, ref6, mut6, 6) -> G
 277         (val7, ref7, mut7, 7) -> H
 278     }
 279     Tuple9 {
 280         (val0, ref0, mut0, 0) -> A
 281         (val1, ref1, mut1, 1) -> B
 282         (val2, ref2, mut2, 2) -> C
 283         (val3, ref3, mut3, 3) -> D
 284         (val4, ref4, mut4, 4) -> E
 285         (val5, ref5, mut5, 5) -> F
 286         (val6, ref6, mut6, 6) -> G
 287         (val7, ref7, mut7, 7) -> H
 288         (val8, ref8, mut8, 8) -> I
 289     }
 290     Tuple10 {
 291         (val0, ref0, mut0, 0) -> A
 292         (val1, ref1, mut1, 1) -> B
 293         (val2, ref2, mut2, 2) -> C
 294         (val3, ref3, mut3, 3) -> D
 295         (val4, ref4, mut4, 4) -> E
 296         (val5, ref5, mut5, 5) -> F
 297         (val6, ref6, mut6, 6) -> G
 298         (val7, ref7, mut7, 7) -> H
 299         (val8, ref8, mut8, 8) -> I
 300         (val9, ref9, mut9, 9) -> J
 301     }
 302     Tuple11 {
 303         (val0, ref0, mut0, 0) -> A
 304         (val1, ref1, mut1, 1) -> B
 305         (val2, ref2, mut2, 2) -> C
 306         (val3, ref3, mut3, 3) -> D
 307         (val4, ref4, mut4, 4) -> E
 308         (val5, ref5, mut5, 5) -> F
 309         (val6, ref6, mut6, 6) -> G
 310         (val7, ref7, mut7, 7) -> H
 311         (val8, ref8, mut8, 8) -> I
 312         (val9, ref9, mut9, 9) -> J
 313         (val10, ref10, mut10, 10) -> K
 314     }
 315     Tuple12 {
 316         (val0, ref0, mut0, 0) -> A
 317         (val1, ref1, mut1, 1) -> B
 318         (val2, ref2, mut2, 2) -> C
 319         (val3, ref3, mut3, 3) -> D
 320         (val4, ref4, mut4, 4) -> E
 321         (val5, ref5, mut5, 5) -> F
 322         (val6, ref6, mut6, 6) -> G
 323         (val7, ref7, mut7, 7) -> H
 324         (val8, ref8, mut8, 8) -> I
 325         (val9, ref9, mut9, 9) -> J
 326         (val10, ref10, mut10, 10) -> K
 327         (val11, ref11, mut11, 11) -> L
 328     }
 329 }