src/libstd/num/mod.rs

   1 // Copyright 2012-2014 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 //! Numeric traits and functions for generic mathematics
  12 //!
  13 //! These are implemented for the primitive numeric types in `std::{u8, u16,
  14 //! u32, u64, usize, i8, i16, i32, i64, isize, f32, f64}`.
  15
  16 #![stable(feature = "rust1", since = "1.0.0")]
  17 #![allow(missing_docs)]
  18
  19 pub use core::num::{Zero, One};
  20 pub use core::num::{FpCategory, ParseIntError, ParseFloatError};
  21 pub use core::num::{wrapping, Wrapping};
  22
  23 #[cfg(test)] use cmp::PartialEq;
  24 #[cfg(test)] use fmt;
  25 #[cfg(test)] use marker::Copy;
  26 #[cfg(test)] use ops::{Add, Sub, Mul, Div, Rem};
  27
  28 /// Helper function for testing numeric operations
  29 #[cfg(test)]
  30 pub fn test_num<T>(ten: T, two: T) where
  31     T: PartialEq
  32      + Add<Output=T> + Sub<Output=T>
  33      + Mul<Output=T> + Div<Output=T>
  34      + Rem<Output=T> + fmt::Debug
  35      + Copy
  36 {
  37     assert_eq!(ten.add(two),  ten + two);
  38     assert_eq!(ten.sub(two),  ten - two);
  39     assert_eq!(ten.mul(two),  ten * two);
  40     assert_eq!(ten.div(two),  ten / two);
  41     assert_eq!(ten.rem(two),  ten % two);
  42 }
  43
  44 #[cfg(test)]
  45 mod tests {
  46     use super::*;
  47     use i8;
  48     use i16;
  49     use i32;
  50     use i64;
  51     use isize;
  52     use u8;
  53     use u16;
  54     use u32;
  55     use u64;
  56     use usize;
  57     use string::ToString;
  58     use ops::Mul;
  59
  60     #[test]
  61     fn test_saturating_add_uint() {
  62         use usize::MAX;
  63         assert_eq!(3_usize.saturating_add(5_usize), 8_usize);
  64         assert_eq!(3_usize.saturating_add(MAX-1), MAX);
  65         assert_eq!(MAX.saturating_add(MAX), MAX);
  66         assert_eq!((MAX-2).saturating_add(1), MAX-1);
  67     }
  68
  69     #[test]
  70     fn test_saturating_sub_uint() {
  71         use usize::MAX;
  72         assert_eq!(5_usize.saturating_sub(3_usize), 2_usize);
  73         assert_eq!(3_usize.saturating_sub(5_usize), 0_usize);
  74         assert_eq!(0_usize.saturating_sub(1_usize), 0_usize);
  75         assert_eq!((MAX-1).saturating_sub(MAX), 0);
  76     }
  77
  78     #[test]
  79     fn test_saturating_add_int() {
  80         use isize::{MIN,MAX};
  81         assert_eq!(3i32.saturating_add(5), 8);
  82         assert_eq!(3isize.saturating_add(MAX-1), MAX);
  83         assert_eq!(MAX.saturating_add(MAX), MAX);
  84         assert_eq!((MAX-2).saturating_add(1), MAX-1);
  85         assert_eq!(3i32.saturating_add(-5), -2);
  86         assert_eq!(MIN.saturating_add(-1), MIN);
  87         assert_eq!((-2isize).saturating_add(-MAX), MIN);
  88     }
  89
  90     #[test]
  91     fn test_saturating_sub_int() {
  92         use isize::{MIN,MAX};
  93         assert_eq!(3i32.saturating_sub(5), -2);
  94         assert_eq!(MIN.saturating_sub(1), MIN);
  95         assert_eq!((-2isize).saturating_sub(MAX), MIN);
  96         assert_eq!(3i32.saturating_sub(-5), 8);
  97         assert_eq!(3isize.saturating_sub(-(MAX-1)), MAX);
  98         assert_eq!(MAX.saturating_sub(-MAX), MAX);
  99         assert_eq!((MAX-2).saturating_sub(-1), MAX-1);
 100     }
 101
 102     #[test]
 103     fn test_checked_add() {
 104         let five_less = usize::MAX - 5;
 105         assert_eq!(five_less.checked_add(0), Some(usize::MAX - 5));
 106         assert_eq!(five_less.checked_add(1), Some(usize::MAX - 4));
 107         assert_eq!(five_less.checked_add(2), Some(usize::MAX - 3));
 108         assert_eq!(five_less.checked_add(3), Some(usize::MAX - 2));
 109         assert_eq!(five_less.checked_add(4), Some(usize::MAX - 1));
 110         assert_eq!(five_less.checked_add(5), Some(usize::MAX));
 111         assert_eq!(five_less.checked_add(6), None);
 112         assert_eq!(five_less.checked_add(7), None);
 113     }
 114
 115     #[test]
 116     fn test_checked_sub() {
 117         assert_eq!(5_usize.checked_sub(0), Some(5));
 118         assert_eq!(5_usize.checked_sub(1), Some(4));
 119         assert_eq!(5_usize.checked_sub(2), Some(3));
 120         assert_eq!(5_usize.checked_sub(3), Some(2));
 121         assert_eq!(5_usize.checked_sub(4), Some(1));
 122         assert_eq!(5_usize.checked_sub(5), Some(0));
 123         assert_eq!(5_usize.checked_sub(6), None);
 124         assert_eq!(5_usize.checked_sub(7), None);
 125     }
 126
 127     #[test]
 128     fn test_checked_mul() {
 129         let third = usize::MAX / 3;
 130         assert_eq!(third.checked_mul(0), Some(0));
 131         assert_eq!(third.checked_mul(1), Some(third));
 132         assert_eq!(third.checked_mul(2), Some(third * 2));
 133         assert_eq!(third.checked_mul(3), Some(third * 3));
 134         assert_eq!(third.checked_mul(4), None);
 135     }
 136
 137     macro_rules! test_is_power_of_two {
 138         ($test_name:ident, $T:ident) => (
 139             fn $test_name() {
 140                 #![test]
 141                 assert_eq!((0 as $T).is_power_of_two(), false);
 142                 assert_eq!((1 as $T).is_power_of_two(), true);
 143                 assert_eq!((2 as $T).is_power_of_two(), true);
 144                 assert_eq!((3 as $T).is_power_of_two(), false);
 145                 assert_eq!((4 as $T).is_power_of_two(), true);
 146                 assert_eq!((5 as $T).is_power_of_two(), false);
 147                 assert_eq!(($T::MAX / 2 + 1).is_power_of_two(), true);
 148             }
 149         )
 150     }
 151
 152     test_is_power_of_two!{ test_is_power_of_two_u8, u8 }
 153     test_is_power_of_two!{ test_is_power_of_two_u16, u16 }
 154     test_is_power_of_two!{ test_is_power_of_two_u32, u32 }
 155     test_is_power_of_two!{ test_is_power_of_two_u64, u64 }
 156     test_is_power_of_two!{ test_is_power_of_two_uint, usize }
 157
 158     macro_rules! test_next_power_of_two {
 159         ($test_name:ident, $T:ident) => (
 160             fn $test_name() {
 161                 #![test]
 162                 assert_eq!((0 as $T).next_power_of_two(), 1);
 163                 let mut next_power = 1;
 164                 for i in 1 as $T..40 {
 165                      assert_eq!(i.next_power_of_two(), next_power);
 166                      if i == next_power { next_power *= 2 }
 167                 }
 168             }
 169         )
 170     }
 171
 172     test_next_power_of_two! { test_next_power_of_two_u8, u8 }
 173     test_next_power_of_two! { test_next_power_of_two_u16, u16 }
 174     test_next_power_of_two! { test_next_power_of_two_u32, u32 }
 175     test_next_power_of_two! { test_next_power_of_two_u64, u64 }
 176     test_next_power_of_two! { test_next_power_of_two_uint, usize }
 177
 178     macro_rules! test_checked_next_power_of_two {
 179         ($test_name:ident, $T:ident) => (
 180             fn $test_name() {
 181                 #![test]
 182                 assert_eq!((0 as $T).checked_next_power_of_two(), Some(1));
 183                 assert!(($T::MAX / 2).checked_next_power_of_two().is_some());
 184                 assert_eq!(($T::MAX - 1).checked_next_power_of_two(), None);
 185                 assert_eq!($T::MAX.checked_next_power_of_two(), None);
 186                 let mut next_power = 1;
 187                 for i in 1 as $T..40 {
 188                      assert_eq!(i.checked_next_power_of_two(), Some(next_power));
 189                      if i == next_power { next_power *= 2 }
 190                 }
 191             }
 192         )
 193     }
 194
 195     test_checked_next_power_of_two! { test_checked_next_power_of_two_u8, u8 }
 196     test_checked_next_power_of_two! { test_checked_next_power_of_two_u16, u16 }
 197     test_checked_next_power_of_two! { test_checked_next_power_of_two_u32, u32 }
 198     test_checked_next_power_of_two! { test_checked_next_power_of_two_u64, u64 }
 199     test_checked_next_power_of_two! { test_checked_next_power_of_two_uint, usize }
 200
 201     #[test]
 202     fn test_pow() {
 203         fn naive_pow<T: Mul<Output=T> + One + Copy>(base: T, exp: usize) -> T {
 204             let one: T = T::one();
 205             (0..exp).fold(one, |acc, _| acc * base)
 206         }
 207         macro_rules! assert_pow {
 208             (($num:expr, $exp:expr) => $expected:expr) => {{
 209                 let result = $num.pow($exp);
 210                 assert_eq!(result, $expected);
 211                 assert_eq!(result, naive_pow($num, $exp));
 212             }}
 213         }
 214         assert_pow!((3u32,     0 ) => 1);
 215         assert_pow!((5u32,     1 ) => 5);
 216         assert_pow!((-4i32,    2 ) => 16);
 217         assert_pow!((8u32,     3 ) => 512);
 218         assert_pow!((2u64,     50) => 1125899906842624);
 219     }
 220
 221     #[test]
 222     fn test_uint_to_str_overflow() {
 223         let mut u8_val: u8 = 255;
 224         assert_eq!(u8_val.to_string(), "255");
 225
 226         u8_val = u8_val.wrapping_add(1);
 227         assert_eq!(u8_val.to_string(), "0");
 228
 229         let mut u16_val: u16 = 65_535;
 230         assert_eq!(u16_val.to_string(), "65535");
 231
 232         u16_val = u16_val.wrapping_add(1);
 233         assert_eq!(u16_val.to_string(), "0");
 234
 235         let mut u32_val: u32 = 4_294_967_295;
 236         assert_eq!(u32_val.to_string(), "4294967295");
 237
 238         u32_val = u32_val.wrapping_add(1);
 239         assert_eq!(u32_val.to_string(), "0");
 240
 241         let mut u64_val: u64 = 18_446_744_073_709_551_615;
 242         assert_eq!(u64_val.to_string(), "18446744073709551615");
 243
 244         u64_val = u64_val.wrapping_add(1);
 245         assert_eq!(u64_val.to_string(), "0");
 246     }
 247
 248     fn from_str<T: ::str::FromStr>(t: &str) -> Option<T> {
 249         ::str::FromStr::from_str(t).ok()
 250     }
 251
 252     #[test]
 253     fn test_uint_from_str_overflow() {
 254         let mut u8_val: u8 = 255;
 255         assert_eq!(from_str::<u8>("255"), Some(u8_val));
 256         assert_eq!(from_str::<u8>("256"), None);
 257
 258         u8_val = u8_val.wrapping_add(1);
 259         assert_eq!(from_str::<u8>("0"), Some(u8_val));
 260         assert_eq!(from_str::<u8>("-1"), None);
 261
 262         let mut u16_val: u16 = 65_535;
 263         assert_eq!(from_str::<u16>("65535"), Some(u16_val));
 264         assert_eq!(from_str::<u16>("65536"), None);
 265
 266         u16_val = u16_val.wrapping_add(1);
 267         assert_eq!(from_str::<u16>("0"), Some(u16_val));
 268         assert_eq!(from_str::<u16>("-1"), None);
 269
 270         let mut u32_val: u32 = 4_294_967_295;
 271         assert_eq!(from_str::<u32>("4294967295"), Some(u32_val));
 272         assert_eq!(from_str::<u32>("4294967296"), None);
 273
 274         u32_val = u32_val.wrapping_add(1);
 275         assert_eq!(from_str::<u32>("0"), Some(u32_val));
 276         assert_eq!(from_str::<u32>("-1"), None);
 277
 278         let mut u64_val: u64 = 18_446_744_073_709_551_615;
 279         assert_eq!(from_str::<u64>("18446744073709551615"), Some(u64_val));
 280         assert_eq!(from_str::<u64>("18446744073709551616"), None);
 281
 282         u64_val = u64_val.wrapping_add(1);
 283         assert_eq!(from_str::<u64>("0"), Some(u64_val));
 284         assert_eq!(from_str::<u64>("-1"), None);
 285     }
 286 }
 287
 288
 289 #[cfg(test)]
 290 mod bench {
 291     extern crate test;
 292     use self::test::Bencher;
 293     use prelude::v1::*;
 294
 295     #[bench]
 296     fn bench_pow_function(b: &mut Bencher) {
 297         let v = (0..1024).collect::<Vec<u32>>();
 298         b.iter(|| {v.iter().fold(0u32, |old, new| old.pow(*new as u32));});
 299     }
 300 }