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