src/libstd/num.rs

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