1 //! Definitions of integer that is known not to equal zero. 2 3 use crate::fmt; 4 use crate::ops::{BitOr, BitOrAssign, Div, Rem}; 5 use crate::str::FromStr; 6 7 use super::from_str_radix; 8 use super::{IntErrorKind, ParseIntError}; 9 use crate::intrinsics; 10 11 macro_rules! impl_nonzero_fmt { 12 ( #[$stability: meta] ( $( $Trait: ident ),+ ) for $Ty: ident ) => { 13 $( 14 #[$stability] 15 impl fmt::$Trait for $Ty { 16 #[inline] 17 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 18 self.get().fmt(f) 19 } 20 } 21 )+ 22 } 23 } 24 25 macro_rules! nonzero_integers { 26 ( $( #[$stability: meta] #[$const_new_unchecked_stability: meta] $Ty: ident($Int: ty); )+ ) => { 27 $( 28 /// An integer that is known not to equal zero. 29 /// 30 /// This enables some memory layout optimization. 31 #[doc = concat!("For example, `Option<", stringify!($Ty), ">` is the same size as `", stringify!($Int), "`:")] 32 /// 33 /// ```rust 34 /// use std::mem::size_of; 35 #[doc = concat!("assert_eq!(size_of::<Option<core::num::", stringify!($Ty), ">>(), size_of::<", stringify!($Int), ">());")] 36 /// ``` 37 #[$stability] 38 #[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)] 39 #[repr(transparent)] 40 #[rustc_layout_scalar_valid_range_start(1)] 41 #[rustc_nonnull_optimization_guaranteed] 42 pub struct $Ty($Int); 43 44 impl $Ty { 45 /// Creates a non-zero without checking whether the value is non-zero. 46 /// This results in undefined behaviour if the value is zero. 47 /// 48 /// # Safety 49 /// 50 /// The value must not be zero. 51 #[$stability] 52 #[$const_new_unchecked_stability] 53 #[must_use] 54 #[inline] 55 pub const unsafe fn new_unchecked(n: $Int) -> Self { 56 // SAFETY: this is guaranteed to be safe by the caller. 57 unsafe { Self(n) } 58 } 59 60 /// Creates a non-zero if the given value is not zero. 61 #[$stability] 62 #[rustc_const_stable(feature = "const_nonzero_int_methods", since = "1.47.0")] 63 #[must_use] 64 #[inline] 65 pub const fn new(n: $Int) -> Option<Self> { 66 if n != 0 { 67 // SAFETY: we just checked that there's no `0` 68 Some(unsafe { Self(n) }) 69 } else { 70 None 71 } 72 } 73 74 /// Returns the value as a primitive type. 75 #[$stability] 76 #[inline] 77 #[rustc_const_stable(feature = "nonzero", since = "1.34.0")] 78 pub const fn get(self) -> $Int { 79 self.0 80 } 81 82 } 83 84 #[stable(feature = "from_nonzero", since = "1.31.0")] 85 #[rustc_const_unstable(feature = "const_num_from_num", issue = "87852")] 86 impl const From<$Ty> for $Int { 87 #[doc = concat!("Converts a `", stringify!($Ty), "` into an `", stringify!($Int), "`")] 88 #[inline] 89 fn from(nonzero: $Ty) -> Self { 90 nonzero.0 91 } 92 } 93 94 #[stable(feature = "nonzero_bitor", since = "1.45.0")] 95 #[rustc_const_unstable(feature = "const_ops", issue = "90080")] 96 impl const BitOr for $Ty { 97 type Output = Self; 98 #[inline] 99 fn bitor(self, rhs: Self) -> Self::Output { 100 // SAFETY: since `self` and `rhs` are both nonzero, the 101 // result of the bitwise-or will be nonzero. 102 unsafe { $Ty::new_unchecked(self.get() | rhs.get()) } 103 } 104 } 105 106 #[stable(feature = "nonzero_bitor", since = "1.45.0")] 107 #[rustc_const_unstable(feature = "const_ops", issue = "90080")] 108 impl const BitOr<$Int> for $Ty { 109 type Output = Self; 110 #[inline] 111 fn bitor(self, rhs: $Int) -> Self::Output { 112 // SAFETY: since `self` is nonzero, the result of the 113 // bitwise-or will be nonzero regardless of the value of 114 // `rhs`. 115 unsafe { $Ty::new_unchecked(self.get() | rhs) } 116 } 117 } 118 119 #[stable(feature = "nonzero_bitor", since = "1.45.0")] 120 #[rustc_const_unstable(feature = "const_ops", issue = "90080")] 121 impl const BitOr<$Ty> for $Int { 122 type Output = $Ty; 123 #[inline] 124 fn bitor(self, rhs: $Ty) -> Self::Output { 125 // SAFETY: since `rhs` is nonzero, the result of the 126 // bitwise-or will be nonzero regardless of the value of 127 // `self`. 128 unsafe { $Ty::new_unchecked(self | rhs.get()) } 129 } 130 } 131 132 #[stable(feature = "nonzero_bitor", since = "1.45.0")] 133 #[rustc_const_unstable(feature = "const_ops", issue = "90080")] 134 impl const BitOrAssign for $Ty { 135 #[inline] 136 fn bitor_assign(&mut self, rhs: Self) { 137 *self = *self | rhs; 138 } 139 } 140 141 #[stable(feature = "nonzero_bitor", since = "1.45.0")] 142 #[rustc_const_unstable(feature = "const_ops", issue = "90080")] 143 impl const BitOrAssign<$Int> for $Ty { 144 #[inline] 145 fn bitor_assign(&mut self, rhs: $Int) { 146 *self = *self | rhs; 147 } 148 } 149 150 impl_nonzero_fmt! { 151 #[$stability] (Debug, Display, Binary, Octal, LowerHex, UpperHex) for $Ty 152 } 153 )+ 154 } 155 } 156 157 nonzero_integers! { 158 #[stable(feature = "nonzero", since = "1.28.0")] #[rustc_const_stable(feature = "nonzero", since = "1.28.0")] NonZeroU8(u8); 159 #[stable(feature = "nonzero", since = "1.28.0")] #[rustc_const_stable(feature = "nonzero", since = "1.28.0")] NonZeroU16(u16); 160 #[stable(feature = "nonzero", since = "1.28.0")] #[rustc_const_stable(feature = "nonzero", since = "1.28.0")] NonZeroU32(u32); 161 #[stable(feature = "nonzero", since = "1.28.0")] #[rustc_const_stable(feature = "nonzero", since = "1.28.0")] NonZeroU64(u64); 162 #[stable(feature = "nonzero", since = "1.28.0")] #[rustc_const_stable(feature = "nonzero", since = "1.28.0")] NonZeroU128(u128); 163 #[stable(feature = "nonzero", since = "1.28.0")] #[rustc_const_stable(feature = "nonzero", since = "1.28.0")] NonZeroUsize(usize); 164 #[stable(feature = "signed_nonzero", since = "1.34.0")] #[rustc_const_stable(feature = "signed_nonzero", since = "1.34.0")] NonZeroI8(i8); 165 #[stable(feature = "signed_nonzero", since = "1.34.0")] #[rustc_const_stable(feature = "signed_nonzero", since = "1.34.0")] NonZeroI16(i16); 166 #[stable(feature = "signed_nonzero", since = "1.34.0")] #[rustc_const_stable(feature = "signed_nonzero", since = "1.34.0")] NonZeroI32(i32); 167 #[stable(feature = "signed_nonzero", since = "1.34.0")] #[rustc_const_stable(feature = "signed_nonzero", since = "1.34.0")] NonZeroI64(i64); 168 #[stable(feature = "signed_nonzero", since = "1.34.0")] #[rustc_const_stable(feature = "signed_nonzero", since = "1.34.0")] NonZeroI128(i128); 169 #[stable(feature = "signed_nonzero", since = "1.34.0")] #[rustc_const_stable(feature = "signed_nonzero", since = "1.34.0")] NonZeroIsize(isize); 170 } 171 172 macro_rules! from_str_radix_nzint_impl { 173 ($($t:ty)*) => {$( 174 #[stable(feature = "nonzero_parse", since = "1.35.0")] 175 impl FromStr for $t { 176 type Err = ParseIntError; 177 fn from_str(src: &str) -> Result<Self, Self::Err> { 178 Self::new(from_str_radix(src, 10)?) 179 .ok_or(ParseIntError { 180 kind: IntErrorKind::Zero 181 }) 182 } 183 } 184 )*} 185 } 186 187 from_str_radix_nzint_impl! { NonZeroU8 NonZeroU16 NonZeroU32 NonZeroU64 NonZeroU128 NonZeroUsize 188 NonZeroI8 NonZeroI16 NonZeroI32 NonZeroI64 NonZeroI128 NonZeroIsize } 189 190 macro_rules! nonzero_leading_trailing_zeros { 191 ( $( $Ty: ident($Uint: ty) , $LeadingTestExpr:expr ;)+ ) => { 192 $( 193 impl $Ty { 194 /// Returns the number of leading zeros in the binary representation of `self`. 195 /// 196 /// On many architectures, this function can perform better than `leading_zeros()` on the underlying integer type, as special handling of zero can be avoided. 197 /// 198 /// # Examples 199 /// 200 /// Basic usage: 201 /// 202 /// ``` 203 #[doc = concat!("let n = std::num::", stringify!($Ty), "::new(", stringify!($LeadingTestExpr), ").unwrap();")] 204 /// 205 /// assert_eq!(n.leading_zeros(), 0); 206 /// ``` 207 #[stable(feature = "nonzero_leading_trailing_zeros", since = "1.53.0")] 208 #[rustc_const_stable(feature = "nonzero_leading_trailing_zeros", since = "1.53.0")] 209 #[must_use = "this returns the result of the operation, \ 210 without modifying the original"] 211 #[inline] 212 pub const fn leading_zeros(self) -> u32 { 213 // SAFETY: since `self` can not be zero it is safe to call ctlz_nonzero 214 unsafe { intrinsics::ctlz_nonzero(self.0 as $Uint) as u32 } 215 } 216 217 /// Returns the number of trailing zeros in the binary representation 218 /// of `self`. 219 /// 220 /// On many architectures, this function can perform better than `trailing_zeros()` on the underlying integer type, as special handling of zero can be avoided. 221 /// 222 /// # Examples 223 /// 224 /// Basic usage: 225 /// 226 /// ``` 227 #[doc = concat!("let n = std::num::", stringify!($Ty), "::new(0b0101000).unwrap();")] 228 /// 229 /// assert_eq!(n.trailing_zeros(), 3); 230 /// ``` 231 #[stable(feature = "nonzero_leading_trailing_zeros", since = "1.53.0")] 232 #[rustc_const_stable(feature = "nonzero_leading_trailing_zeros", since = "1.53.0")] 233 #[must_use = "this returns the result of the operation, \ 234 without modifying the original"] 235 #[inline] 236 pub const fn trailing_zeros(self) -> u32 { 237 // SAFETY: since `self` can not be zero it is safe to call cttz_nonzero 238 unsafe { intrinsics::cttz_nonzero(self.0 as $Uint) as u32 } 239 } 240 241 } 242 )+ 243 } 244 } 245 246 nonzero_leading_trailing_zeros! { 247 NonZeroU8(u8), u8::MAX; 248 NonZeroU16(u16), u16::MAX; 249 NonZeroU32(u32), u32::MAX; 250 NonZeroU64(u64), u64::MAX; 251 NonZeroU128(u128), u128::MAX; 252 NonZeroUsize(usize), usize::MAX; 253 NonZeroI8(u8), -1i8; 254 NonZeroI16(u16), -1i16; 255 NonZeroI32(u32), -1i32; 256 NonZeroI64(u64), -1i64; 257 NonZeroI128(u128), -1i128; 258 NonZeroIsize(usize), -1isize; 259 } 260 261 macro_rules! nonzero_integers_div { 262 ( $( $Ty: ident($Int: ty); )+ ) => { 263 $( 264 #[stable(feature = "nonzero_div", since = "1.51.0")] 265 #[rustc_const_unstable(feature = "const_ops", issue = "90080")] 266 impl const Div<$Ty> for $Int { 267 type Output = $Int; 268 /// This operation rounds towards zero, 269 /// truncating any fractional part of the exact result, and cannot panic. 270 #[inline] 271 fn div(self, other: $Ty) -> $Int { 272 // SAFETY: div by zero is checked because `other` is a nonzero, 273 // and MIN/-1 is checked because `self` is an unsigned int. 274 unsafe { crate::intrinsics::unchecked_div(self, other.get()) } 275 } 276 } 277 278 #[stable(feature = "nonzero_div", since = "1.51.0")] 279 #[rustc_const_unstable(feature = "const_ops", issue = "90080")] 280 impl const Rem<$Ty> for $Int { 281 type Output = $Int; 282 /// This operation satisfies `n % d == n - (n / d) * d`, and cannot panic. 283 #[inline] 284 fn rem(self, other: $Ty) -> $Int { 285 // SAFETY: rem by zero is checked because `other` is a nonzero, 286 // and MIN/-1 is checked because `self` is an unsigned int. 287 unsafe { crate::intrinsics::unchecked_rem(self, other.get()) } 288 } 289 } 290 )+ 291 } 292 } 293 294 nonzero_integers_div! { 295 NonZeroU8(u8); 296 NonZeroU16(u16); 297 NonZeroU32(u32); 298 NonZeroU64(u64); 299 NonZeroU128(u128); 300 NonZeroUsize(usize); 301 } 302 303 // A bunch of methods for unsigned nonzero types only. 304 macro_rules! nonzero_unsigned_operations { 305 ( $( $Ty: ident($Int: ty); )+ ) => { 306 $( 307 impl $Ty { 308 /// Add an unsigned integer to a non-zero value. 309 /// Check for overflow and return [`None`] on overflow 310 /// As a consequence, the result cannot wrap to zero. 311 /// 312 /// 313 /// # Examples 314 /// 315 /// ``` 316 /// #![feature(nonzero_ops)] 317 #[doc = concat!("# use std::num::", stringify!($Ty), ";")] 318 /// 319 /// # fn main() { test().unwrap(); } 320 /// # fn test() -> Option<()> { 321 #[doc = concat!("let one = ", stringify!($Ty), "::new(1)?;")] 322 #[doc = concat!("let two = ", stringify!($Ty), "::new(2)?;")] 323 #[doc = concat!("let max = ", stringify!($Ty), "::new(", 324 stringify!($Int), "::MAX)?;")] 325 /// 326 /// assert_eq!(Some(two), one.checked_add(1)); 327 /// assert_eq!(None, max.checked_add(1)); 328 /// # Some(()) 329 /// # } 330 /// ``` 331 #[unstable(feature = "nonzero_ops", issue = "84186")] 332 #[must_use = "this returns the result of the operation, \ 333 without modifying the original"] 334 #[inline] 335 pub const fn checked_add(self, other: $Int) -> Option<$Ty> { 336 if let Some(result) = self.get().checked_add(other) { 337 // SAFETY: $Int::checked_add returns None on overflow 338 // so the result cannot be zero. 339 Some(unsafe { $Ty::new_unchecked(result) }) 340 } else { 341 None 342 } 343 } 344 345 /// Add an unsigned integer to a non-zero value. 346 #[doc = concat!("Return [`", stringify!($Int), "::MAX`] on overflow.")] 347 /// 348 /// # Examples 349 /// 350 /// ``` 351 /// #![feature(nonzero_ops)] 352 #[doc = concat!("# use std::num::", stringify!($Ty), ";")] 353 /// 354 /// # fn main() { test().unwrap(); } 355 /// # fn test() -> Option<()> { 356 #[doc = concat!("let one = ", stringify!($Ty), "::new(1)?;")] 357 #[doc = concat!("let two = ", stringify!($Ty), "::new(2)?;")] 358 #[doc = concat!("let max = ", stringify!($Ty), "::new(", 359 stringify!($Int), "::MAX)?;")] 360 /// 361 /// assert_eq!(two, one.saturating_add(1)); 362 /// assert_eq!(max, max.saturating_add(1)); 363 /// # Some(()) 364 /// # } 365 /// ``` 366 #[unstable(feature = "nonzero_ops", issue = "84186")] 367 #[must_use = "this returns the result of the operation, \ 368 without modifying the original"] 369 #[inline] 370 pub const fn saturating_add(self, other: $Int) -> $Ty { 371 // SAFETY: $Int::saturating_add returns $Int::MAX on overflow 372 // so the result cannot be zero. 373 unsafe { $Ty::new_unchecked(self.get().saturating_add(other)) } 374 } 375 376 /// Add an unsigned integer to a non-zero value, 377 /// assuming overflow cannot occur. 378 /// Overflow is unchecked, and it is undefined behaviour to overflow 379 /// *even if the result would wrap to a non-zero value*. 380 /// The behaviour is undefined as soon as 381 #[doc = concat!("`self + rhs > ", stringify!($Int), "::MAX`.")] 382 /// 383 /// # Examples 384 /// 385 /// ``` 386 /// #![feature(nonzero_ops)] 387 #[doc = concat!("# use std::num::", stringify!($Ty), ";")] 388 /// 389 /// # fn main() { test().unwrap(); } 390 /// # fn test() -> Option<()> { 391 #[doc = concat!("let one = ", stringify!($Ty), "::new(1)?;")] 392 #[doc = concat!("let two = ", stringify!($Ty), "::new(2)?;")] 393 /// 394 /// assert_eq!(two, unsafe { one.unchecked_add(1) }); 395 /// # Some(()) 396 /// # } 397 /// ``` 398 #[unstable(feature = "nonzero_ops", issue = "84186")] 399 #[must_use = "this returns the result of the operation, \ 400 without modifying the original"] 401 #[inline] 402 pub const unsafe fn unchecked_add(self, other: $Int) -> $Ty { 403 // SAFETY: The caller ensures there is no overflow. 404 unsafe { $Ty::new_unchecked(self.get().unchecked_add(other)) } 405 } 406 407 /// Returns the smallest power of two greater than or equal to n. 408 /// Check for overflow and return [`None`] 409 /// if the next power of two is greater than the type’s maximum value. 410 /// As a consequence, the result cannot wrap to zero. 411 /// 412 /// # Examples 413 /// 414 /// ``` 415 /// #![feature(nonzero_ops)] 416 #[doc = concat!("# use std::num::", stringify!($Ty), ";")] 417 /// 418 /// # fn main() { test().unwrap(); } 419 /// # fn test() -> Option<()> { 420 #[doc = concat!("let two = ", stringify!($Ty), "::new(2)?;")] 421 #[doc = concat!("let three = ", stringify!($Ty), "::new(3)?;")] 422 #[doc = concat!("let four = ", stringify!($Ty), "::new(4)?;")] 423 #[doc = concat!("let max = ", stringify!($Ty), "::new(", 424 stringify!($Int), "::MAX)?;")] 425 /// 426 /// assert_eq!(Some(two), two.checked_next_power_of_two() ); 427 /// assert_eq!(Some(four), three.checked_next_power_of_two() ); 428 /// assert_eq!(None, max.checked_next_power_of_two() ); 429 /// # Some(()) 430 /// # } 431 /// ``` 432 #[unstable(feature = "nonzero_ops", issue = "84186")] 433 #[must_use = "this returns the result of the operation, \ 434 without modifying the original"] 435 #[inline] 436 pub const fn checked_next_power_of_two(self) -> Option<$Ty> { 437 if let Some(nz) = self.get().checked_next_power_of_two() { 438 // SAFETY: The next power of two is positive 439 // and overflow is checked. 440 Some(unsafe { $Ty::new_unchecked(nz) }) 441 } else { 442 None 443 } 444 } 445 } 446 )+ 447 } 448 } 449 450 nonzero_unsigned_operations! { 451 NonZeroU8(u8); 452 NonZeroU16(u16); 453 NonZeroU32(u32); 454 NonZeroU64(u64); 455 NonZeroU128(u128); 456 NonZeroUsize(usize); 457 } 458 459 // A bunch of methods for signed nonzero types only. 460 macro_rules! nonzero_signed_operations { 461 ( $( $Ty: ident($Int: ty) -> $Uty: ident($Uint: ty); )+ ) => { 462 $( 463 impl $Ty { 464 /// Computes the absolute value of self. 465 #[doc = concat!("See [`", stringify!($Int), "::abs`]")] 466 /// for documentation on overflow behaviour. 467 /// 468 /// # Example 469 /// 470 /// ``` 471 /// #![feature(nonzero_ops)] 472 #[doc = concat!("# use std::num::", stringify!($Ty), ";")] 473 /// 474 /// # fn main() { test().unwrap(); } 475 /// # fn test() -> Option<()> { 476 #[doc = concat!("let pos = ", stringify!($Ty), "::new(1)?;")] 477 #[doc = concat!("let neg = ", stringify!($Ty), "::new(-1)?;")] 478 /// 479 /// assert_eq!(pos, pos.abs()); 480 /// assert_eq!(pos, neg.abs()); 481 /// # Some(()) 482 /// # } 483 /// ``` 484 #[unstable(feature = "nonzero_ops", issue = "84186")] 485 #[must_use = "this returns the result of the operation, \ 486 without modifying the original"] 487 #[inline] 488 pub const fn abs(self) -> $Ty { 489 // SAFETY: This cannot overflow to zero. 490 unsafe { $Ty::new_unchecked(self.get().abs()) } 491 } 492 493 /// Checked absolute value. 494 /// Check for overflow and returns [`None`] if 495 #[doc = concat!("`self == ", stringify!($Int), "::MIN`.")] 496 /// The result cannot be zero. 497 /// 498 /// # Example 499 /// 500 /// ``` 501 /// #![feature(nonzero_ops)] 502 #[doc = concat!("# use std::num::", stringify!($Ty), ";")] 503 /// 504 /// # fn main() { test().unwrap(); } 505 /// # fn test() -> Option<()> { 506 #[doc = concat!("let pos = ", stringify!($Ty), "::new(1)?;")] 507 #[doc = concat!("let neg = ", stringify!($Ty), "::new(-1)?;")] 508 #[doc = concat!("let min = ", stringify!($Ty), "::new(", 509 stringify!($Int), "::MIN)?;")] 510 /// 511 /// assert_eq!(Some(pos), neg.checked_abs()); 512 /// assert_eq!(None, min.checked_abs()); 513 /// # Some(()) 514 /// # } 515 /// ``` 516 #[unstable(feature = "nonzero_ops", issue = "84186")] 517 #[must_use = "this returns the result of the operation, \ 518 without modifying the original"] 519 #[inline] 520 pub const fn checked_abs(self) -> Option<$Ty> { 521 if let Some(nz) = self.get().checked_abs() { 522 // SAFETY: absolute value of nonzero cannot yield zero values. 523 Some(unsafe { $Ty::new_unchecked(nz) }) 524 } else { 525 None 526 } 527 } 528 529 /// Computes the absolute value of self, 530 /// with overflow information, see 531 #[doc = concat!("[`", stringify!($Int), "::overflowing_abs`].")] 532 /// 533 /// # Example 534 /// 535 /// ``` 536 /// #![feature(nonzero_ops)] 537 #[doc = concat!("# use std::num::", stringify!($Ty), ";")] 538 /// 539 /// # fn main() { test().unwrap(); } 540 /// # fn test() -> Option<()> { 541 #[doc = concat!("let pos = ", stringify!($Ty), "::new(1)?;")] 542 #[doc = concat!("let neg = ", stringify!($Ty), "::new(-1)?;")] 543 #[doc = concat!("let min = ", stringify!($Ty), "::new(", 544 stringify!($Int), "::MIN)?;")] 545 /// 546 /// assert_eq!((pos, false), pos.overflowing_abs()); 547 /// assert_eq!((pos, false), neg.overflowing_abs()); 548 /// assert_eq!((min, true), min.overflowing_abs()); 549 /// # Some(()) 550 /// # } 551 /// ``` 552 #[unstable(feature = "nonzero_ops", issue = "84186")] 553 #[must_use = "this returns the result of the operation, \ 554 without modifying the original"] 555 #[inline] 556 pub const fn overflowing_abs(self) -> ($Ty, bool) { 557 let (nz, flag) = self.get().overflowing_abs(); 558 ( 559 // SAFETY: absolute value of nonzero cannot yield zero values. 560 unsafe { $Ty::new_unchecked(nz) }, 561 flag, 562 ) 563 } 564 565 /// Saturating absolute value, see 566 #[doc = concat!("[`", stringify!($Int), "::saturating_abs`].")] 567 /// 568 /// # Example 569 /// 570 /// ``` 571 /// #![feature(nonzero_ops)] 572 #[doc = concat!("# use std::num::", stringify!($Ty), ";")] 573 /// 574 /// # fn main() { test().unwrap(); } 575 /// # fn test() -> Option<()> { 576 #[doc = concat!("let pos = ", stringify!($Ty), "::new(1)?;")] 577 #[doc = concat!("let neg = ", stringify!($Ty), "::new(-1)?;")] 578 #[doc = concat!("let min = ", stringify!($Ty), "::new(", 579 stringify!($Int), "::MIN)?;")] 580 #[doc = concat!("let min_plus = ", stringify!($Ty), "::new(", 581 stringify!($Int), "::MIN + 1)?;")] 582 #[doc = concat!("let max = ", stringify!($Ty), "::new(", 583 stringify!($Int), "::MAX)?;")] 584 /// 585 /// assert_eq!(pos, pos.saturating_abs()); 586 /// assert_eq!(pos, neg.saturating_abs()); 587 /// assert_eq!(max, min.saturating_abs()); 588 /// assert_eq!(max, min_plus.saturating_abs()); 589 /// # Some(()) 590 /// # } 591 /// ``` 592 #[unstable(feature = "nonzero_ops", issue = "84186")] 593 #[must_use = "this returns the result of the operation, \ 594 without modifying the original"] 595 #[inline] 596 pub const fn saturating_abs(self) -> $Ty { 597 // SAFETY: absolute value of nonzero cannot yield zero values. 598 unsafe { $Ty::new_unchecked(self.get().saturating_abs()) } 599 } 600 601 /// Wrapping absolute value, see 602 #[doc = concat!("[`", stringify!($Int), "::wrapping_abs`].")] 603 /// 604 /// # Example 605 /// 606 /// ``` 607 /// #![feature(nonzero_ops)] 608 #[doc = concat!("# use std::num::", stringify!($Ty), ";")] 609 /// 610 /// # fn main() { test().unwrap(); } 611 /// # fn test() -> Option<()> { 612 #[doc = concat!("let pos = ", stringify!($Ty), "::new(1)?;")] 613 #[doc = concat!("let neg = ", stringify!($Ty), "::new(-1)?;")] 614 #[doc = concat!("let min = ", stringify!($Ty), "::new(", 615 stringify!($Int), "::MIN)?;")] 616 #[doc = concat!("let max = ", stringify!($Ty), "::new(", 617 stringify!($Int), "::MAX)?;")] 618 /// 619 /// assert_eq!(pos, pos.wrapping_abs()); 620 /// assert_eq!(pos, neg.wrapping_abs()); 621 /// assert_eq!(min, min.wrapping_abs()); 622 /// # // FIXME: add once Neg is implemented? 623 /// # // assert_eq!(max, (-max).wrapping_abs()); 624 /// # Some(()) 625 /// # } 626 /// ``` 627 #[unstable(feature = "nonzero_ops", issue = "84186")] 628 #[must_use = "this returns the result of the operation, \ 629 without modifying the original"] 630 #[inline] 631 pub const fn wrapping_abs(self) -> $Ty { 632 // SAFETY: absolute value of nonzero cannot yield zero values. 633 unsafe { $Ty::new_unchecked(self.get().wrapping_abs()) } 634 } 635 636 /// Computes the absolute value of self 637 /// without any wrapping or panicking. 638 /// 639 /// # Example 640 /// 641 /// ``` 642 /// #![feature(nonzero_ops)] 643 #[doc = concat!("# use std::num::", stringify!($Ty), ";")] 644 #[doc = concat!("# use std::num::", stringify!($Uty), ";")] 645 /// 646 /// # fn main() { test().unwrap(); } 647 /// # fn test() -> Option<()> { 648 #[doc = concat!("let u_pos = ", stringify!($Uty), "::new(1)?;")] 649 #[doc = concat!("let i_pos = ", stringify!($Ty), "::new(1)?;")] 650 #[doc = concat!("let i_neg = ", stringify!($Ty), "::new(-1)?;")] 651 #[doc = concat!("let i_min = ", stringify!($Ty), "::new(", 652 stringify!($Int), "::MIN)?;")] 653 #[doc = concat!("let u_max = ", stringify!($Uty), "::new(", 654 stringify!($Uint), "::MAX / 2 + 1)?;")] 655 /// 656 /// assert_eq!(u_pos, i_pos.unsigned_abs()); 657 /// assert_eq!(u_pos, i_neg.unsigned_abs()); 658 /// assert_eq!(u_max, i_min.unsigned_abs()); 659 /// # Some(()) 660 /// # } 661 /// ``` 662 #[unstable(feature = "nonzero_ops", issue = "84186")] 663 #[must_use = "this returns the result of the operation, \ 664 without modifying the original"] 665 #[inline] 666 pub const fn unsigned_abs(self) -> $Uty { 667 // SAFETY: absolute value of nonzero cannot yield zero values. 668 unsafe { $Uty::new_unchecked(self.get().unsigned_abs()) } 669 } 670 } 671 )+ 672 } 673 } 674 675 nonzero_signed_operations! { 676 NonZeroI8(i8) -> NonZeroU8(u8); 677 NonZeroI16(i16) -> NonZeroU16(u16); 678 NonZeroI32(i32) -> NonZeroU32(u32); 679 NonZeroI64(i64) -> NonZeroU64(u64); 680 NonZeroI128(i128) -> NonZeroU128(u128); 681 NonZeroIsize(isize) -> NonZeroUsize(usize); 682 } 683 684 // A bunch of methods for both signed and unsigned nonzero types. 685 macro_rules! nonzero_unsigned_signed_operations { 686 ( $( $signedness:ident $Ty: ident($Int: ty); )+ ) => { 687 $( 688 impl $Ty { 689 /// Multiply two non-zero integers together. 690 /// Check for overflow and return [`None`] on overflow. 691 /// As a consequence, the result cannot wrap to zero. 692 /// 693 /// # Examples 694 /// 695 /// ``` 696 /// #![feature(nonzero_ops)] 697 #[doc = concat!("# use std::num::", stringify!($Ty), ";")] 698 /// 699 /// # fn main() { test().unwrap(); } 700 /// # fn test() -> Option<()> { 701 #[doc = concat!("let two = ", stringify!($Ty), "::new(2)?;")] 702 #[doc = concat!("let four = ", stringify!($Ty), "::new(4)?;")] 703 #[doc = concat!("let max = ", stringify!($Ty), "::new(", 704 stringify!($Int), "::MAX)?;")] 705 /// 706 /// assert_eq!(Some(four), two.checked_mul(two)); 707 /// assert_eq!(None, max.checked_mul(two)); 708 /// # Some(()) 709 /// # } 710 /// ``` 711 #[unstable(feature = "nonzero_ops", issue = "84186")] 712 #[must_use = "this returns the result of the operation, \ 713 without modifying the original"] 714 #[inline] 715 pub const fn checked_mul(self, other: $Ty) -> Option<$Ty> { 716 if let Some(result) = self.get().checked_mul(other.get()) { 717 // SAFETY: checked_mul returns None on overflow 718 // and `other` is also non-null 719 // so the result cannot be zero. 720 Some(unsafe { $Ty::new_unchecked(result) }) 721 } else { 722 None 723 } 724 } 725 726 /// Multiply two non-zero integers together. 727 #[doc = concat!("Return [`", stringify!($Int), "::MAX`] on overflow.")] 728 /// 729 /// # Examples 730 /// 731 /// ``` 732 /// #![feature(nonzero_ops)] 733 #[doc = concat!("# use std::num::", stringify!($Ty), ";")] 734 /// 735 /// # fn main() { test().unwrap(); } 736 /// # fn test() -> Option<()> { 737 #[doc = concat!("let two = ", stringify!($Ty), "::new(2)?;")] 738 #[doc = concat!("let four = ", stringify!($Ty), "::new(4)?;")] 739 #[doc = concat!("let max = ", stringify!($Ty), "::new(", 740 stringify!($Int), "::MAX)?;")] 741 /// 742 /// assert_eq!(four, two.saturating_mul(two)); 743 /// assert_eq!(max, four.saturating_mul(max)); 744 /// # Some(()) 745 /// # } 746 /// ``` 747 #[unstable(feature = "nonzero_ops", issue = "84186")] 748 #[must_use = "this returns the result of the operation, \ 749 without modifying the original"] 750 #[inline] 751 pub const fn saturating_mul(self, other: $Ty) -> $Ty { 752 // SAFETY: saturating_mul returns u*::MAX on overflow 753 // and `other` is also non-null 754 // so the result cannot be zero. 755 unsafe { $Ty::new_unchecked(self.get().saturating_mul(other.get())) } 756 } 757 758 /// Multiply two non-zero integers together, 759 /// assuming overflow cannot occur. 760 /// Overflow is unchecked, and it is undefined behaviour to overflow 761 /// *even if the result would wrap to a non-zero value*. 762 /// The behaviour is undefined as soon as 763 #[doc = sign_dependent_expr!{ 764 $signedness ? 765 if signed { 766 concat!("`self * rhs > ", stringify!($Int), "::MAX`, ", 767 "or `self * rhs < ", stringify!($Int), "::MIN`.") 768 } 769 if unsigned { 770 concat!("`self * rhs > ", stringify!($Int), "::MAX`.") 771 } 772 }] 773 /// 774 /// # Examples 775 /// 776 /// ``` 777 /// #![feature(nonzero_ops)] 778 #[doc = concat!("# use std::num::", stringify!($Ty), ";")] 779 /// 780 /// # fn main() { test().unwrap(); } 781 /// # fn test() -> Option<()> { 782 #[doc = concat!("let two = ", stringify!($Ty), "::new(2)?;")] 783 #[doc = concat!("let four = ", stringify!($Ty), "::new(4)?;")] 784 /// 785 /// assert_eq!(four, unsafe { two.unchecked_mul(two) }); 786 /// # Some(()) 787 /// # } 788 /// ``` 789 #[unstable(feature = "nonzero_ops", issue = "84186")] 790 #[must_use = "this returns the result of the operation, \ 791 without modifying the original"] 792 #[inline] 793 pub const unsafe fn unchecked_mul(self, other: $Ty) -> $Ty { 794 // SAFETY: The caller ensures there is no overflow. 795 unsafe { $Ty::new_unchecked(self.get().unchecked_mul(other.get())) } 796 } 797 798 /// Raise non-zero value to an integer power. 799 /// Check for overflow and return [`None`] on overflow. 800 /// As a consequence, the result cannot wrap to zero. 801 /// 802 /// # Examples 803 /// 804 /// ``` 805 /// #![feature(nonzero_ops)] 806 #[doc = concat!("# use std::num::", stringify!($Ty), ";")] 807 /// 808 /// # fn main() { test().unwrap(); } 809 /// # fn test() -> Option<()> { 810 #[doc = concat!("let three = ", stringify!($Ty), "::new(3)?;")] 811 #[doc = concat!("let twenty_seven = ", stringify!($Ty), "::new(27)?;")] 812 #[doc = concat!("let half_max = ", stringify!($Ty), "::new(", 813 stringify!($Int), "::MAX / 2)?;")] 814 /// 815 /// assert_eq!(Some(twenty_seven), three.checked_pow(3)); 816 /// assert_eq!(None, half_max.checked_pow(3)); 817 /// # Some(()) 818 /// # } 819 /// ``` 820 #[unstable(feature = "nonzero_ops", issue = "84186")] 821 #[must_use = "this returns the result of the operation, \ 822 without modifying the original"] 823 #[inline] 824 pub const fn checked_pow(self, other: u32) -> Option<$Ty> { 825 if let Some(result) = self.get().checked_pow(other) { 826 // SAFETY: checked_pow returns None on overflow 827 // so the result cannot be zero. 828 Some(unsafe { $Ty::new_unchecked(result) }) 829 } else { 830 None 831 } 832 } 833 834 /// Raise non-zero value to an integer power. 835 #[doc = sign_dependent_expr!{ 836 $signedness ? 837 if signed { 838 concat!("Return [`", stringify!($Int), "::MIN`] ", 839 "or [`", stringify!($Int), "::MAX`] on overflow.") 840 } 841 if unsigned { 842 concat!("Return [`", stringify!($Int), "::MAX`] on overflow.") 843 } 844 }] 845 /// 846 /// # Examples 847 /// 848 /// ``` 849 /// #![feature(nonzero_ops)] 850 #[doc = concat!("# use std::num::", stringify!($Ty), ";")] 851 /// 852 /// # fn main() { test().unwrap(); } 853 /// # fn test() -> Option<()> { 854 #[doc = concat!("let three = ", stringify!($Ty), "::new(3)?;")] 855 #[doc = concat!("let twenty_seven = ", stringify!($Ty), "::new(27)?;")] 856 #[doc = concat!("let max = ", stringify!($Ty), "::new(", 857 stringify!($Int), "::MAX)?;")] 858 /// 859 /// assert_eq!(twenty_seven, three.saturating_pow(3)); 860 /// assert_eq!(max, max.saturating_pow(3)); 861 /// # Some(()) 862 /// # } 863 /// ``` 864 #[unstable(feature = "nonzero_ops", issue = "84186")] 865 #[must_use = "this returns the result of the operation, \ 866 without modifying the original"] 867 #[inline] 868 pub const fn saturating_pow(self, other: u32) -> $Ty { 869 // SAFETY: saturating_pow returns u*::MAX on overflow 870 // so the result cannot be zero. 871 unsafe { $Ty::new_unchecked(self.get().saturating_pow(other)) } 872 } 873 } 874 )+ 875 } 876 } 877 878 // Use this when the generated code should differ between signed and unsigned types. 879 macro_rules! sign_dependent_expr { 880 (signed ? if signed { $signed_case:expr } if unsigned { $unsigned_case:expr } ) => { 881 $signed_case 882 }; 883 (unsigned ? if signed { $signed_case:expr } if unsigned { $unsigned_case:expr } ) => { 884 $unsigned_case 885 }; 886 } 887 888 nonzero_unsigned_signed_operations! { 889 unsigned NonZeroU8(u8); 890 unsigned NonZeroU16(u16); 891 unsigned NonZeroU32(u32); 892 unsigned NonZeroU64(u64); 893 unsigned NonZeroU128(u128); 894 unsigned NonZeroUsize(usize); 895 signed NonZeroI8(i8); 896 signed NonZeroI16(i16); 897 signed NonZeroI32(i32); 898 signed NonZeroI64(i64); 899 signed NonZeroI128(i128); 900 signed NonZeroIsize(isize); 901 } 902 903 macro_rules! nonzero_unsigned_is_power_of_two { 904 ( $( $Ty: ident )+ ) => { 905 $( 906 impl $Ty { 907 908 /// Returns `true` if and only if `self == (1 << k)` for some `k`. 909 /// 910 /// On many architectures, this function can perform better than `is_power_of_two()` 911 /// on the underlying integer type, as special handling of zero can be avoided. 912 /// 913 /// # Examples 914 /// 915 /// Basic usage: 916 /// 917 /// ``` 918 /// #![feature(nonzero_is_power_of_two)] 919 /// 920 #[doc = concat!("let eight = std::num::", stringify!($Ty), "::new(8).unwrap();")] 921 /// assert!(eight.is_power_of_two()); 922 #[doc = concat!("let ten = std::num::", stringify!($Ty), "::new(10).unwrap();")] 923 /// assert!(!ten.is_power_of_two()); 924 /// ``` 925 #[must_use] 926 #[unstable(feature = "nonzero_is_power_of_two", issue = "81106")] 927 #[inline] 928 pub const fn is_power_of_two(self) -> bool { 929 // LLVM 11 normalizes `unchecked_sub(x, 1) & x == 0` to the implementation seen here. 930 // On the basic x86-64 target, this saves 3 instructions for the zero check. 931 // On x86_64 with BMI1, being nonzero lets it codegen to `BLSR`, which saves an instruction 932 // compared to the `POPCNT` implementation on the underlying integer type. 933 934 intrinsics::ctpop(self.get()) < 2 935 } 936 937 } 938 )+ 939 } 940 } 941 942 nonzero_unsigned_is_power_of_two! { NonZeroU8 NonZeroU16 NonZeroU32 NonZeroU64 NonZeroU128 NonZeroUsize } 943