diff --git a/src/macros_frac.rs b/src/macros_frac.rs index d0a0299..40d6cf7 100644 --- a/src/macros_frac.rs +++ b/src/macros_frac.rs @@ -961,6 +961,283 @@ assert_eq!(Fix::from_num(-7.5).wrapping_rem_euclid_int(20), Fix::from_num(-3.5)) } } + #[cfg(feature = "unwrapped")] + if_signed! { + $Signedness; + comment! { + "Unwrapped signum. Returns a number representing +the sign of `self`, panicking on overflow. + +Overflow can only occur + * if the value is positive and the fixed-point number has zero + or one integer bits such that it cannot hold the value 1. + * if the value is negative and the fixed-point number has zero + integer bits, such that it cannot hold the value −1. + +This method is only available when the [`unwrapped` experimental +feature][exp] is enabled. + +# Panics + +Panics if the result does not fit. + +# Examples + +```rust +use fixed::{types::extra::U4, ", $s_fixed, "}; +type Fix = ", $s_fixed, "; +assert_eq!(Fix::from_num(5).unwrapped_signum(), 1); +assert_eq!(Fix::from_num(0).unwrapped_signum(), 0); +assert_eq!(Fix::from_num(-5).unwrapped_signum(), -1); +``` + +The following panics because of overflow. + +```should_panic +use fixed::{types::extra::U", $s_nbits_m1, ", ", $s_fixed, "}; +type OneIntBit = ", $s_fixed, "; +let _overflow = OneIntBit::from_num(0.5).unwrapped_signum(); +``` + +[exp]: ../index.html#experimental-optional-features +"; + #[inline] + pub fn unwrapped_signum(self) -> $Fixed { + self.checked_signum().expect("overflow") + } + } + } + + #[cfg(feature = "unwrapped")] + comment! { + "Unwrapped multiplication. Returns the product, panicking on overflow. + +This method is only available when the [`unwrapped` experimental +feature][exp] is enabled. + +# Panics + +Panics if the result does not fit. + +# Examples + +```rust +use fixed::{types::extra::U4, ", $s_fixed, "}; +type Fix = ", $s_fixed, "; +assert_eq!(Fix::from_num(3).unwrapped_mul(Fix::from_num(2)), Fix::from_num(6)); +``` + +The following panics because of overflow. + +```should_panic +use fixed::{types::extra::U4, ", $s_fixed, "}; +type Fix = ", $s_fixed, "; +let _overflow = Fix::MAX.unwrapped_mul(Fix::from_num(4)); +``` + +[exp]: ../index.html#experimental-optional-features +"; + #[inline] + pub fn unwrapped_mul(self, rhs: $Fixed) -> $Fixed { + self.checked_mul(rhs).expect("overflow") + } + } + + #[cfg(feature = "unwrapped")] + comment! { + "Unwrapped division. Returns the quotient, panicking on overflow. + +This method is only available when the [`unwrapped` experimental +feature][exp] is enabled. + +# Panics + +Panics if the divisor is zero or if the division results in overflow. + +# Examples + +```rust +use fixed::{types::extra::U4, ", $s_fixed, "}; +type Fix = ", $s_fixed, "; +let one_point_5 = Fix::from_bits(0b11 << (4 - 1)); +assert_eq!(Fix::from_num(3).unwrapped_div(Fix::from_num(2)), one_point_5); +``` + +The following panics because of overflow. + +```should_panic +use fixed::{types::extra::U4, ", $s_fixed, "}; +type Fix = ", $s_fixed, "; +let quarter = Fix::from_num(1) / 4; +let _overflow = Fix::MAX.unwrapped_div(quarter); +``` + +[exp]: ../index.html#experimental-optional-features +"; + #[inline] + pub fn unwrapped_div(self, rhs: $Fixed) -> $Fixed { + match self.overflowing_div(rhs) { + (_, true) => panic!("overflow"), + (ans, false) => ans, + } + } + } + + #[cfg(feature = "unwrapped")] + comment! { + "Unwrapped Euclidean division. Returns the quotient, panicking on overflow. + +This method is only available when the [`unwrapped` experimental +feature][exp] is enabled. + +# Panics + +Panics if the divisor is zero or if the division results in overflow. + +# Examples + +```rust +use fixed::{types::extra::U4, ", $s_fixed, "}; +type Fix = ", $s_fixed, "; +assert_eq!(Fix::from_num(7.5).unwrapped_div_euclid(Fix::from_num(2)), Fix::from_num(3)); +``` + +The following panics because of overflow. + +```should_panic +use fixed::{types::extra::U4, ", $s_fixed, "}; +type Fix = ", $s_fixed, "; +let _overflow = Fix::MAX.unwrapped_div_euclid(Fix::from_num(0.25)); +``` + +[exp]: ../index.html#experimental-optional-features +"; + #[inline] + pub fn unwrapped_div_euclid(self, rhs: $Fixed) -> $Fixed { + match self.overflowing_div_euclid(rhs) { + (_, true) => panic!("overflow"), + (ans, false) => ans, + } + } + } + + #[cfg(feature = "unwrapped")] + comment! { + "Unwrapped Euclidean division by an integer. Returns the quotient", + if_signed_unsigned! { + $Signedness, + ", panicking on overflow. + +Overflow can only occur when dividing the minimum value by −1.", + ". + +Can never overflow for unsigned values.", + }, + " + +This method is only available when the [`unwrapped` experimental +feature][exp] is enabled. + +# Panics + +Panics if the divisor is zero", + if_signed_else_empty_str! { + $Signedness, + " or if the division results in overflow", + }, + ". + +# Examples + +```rust +use fixed::{types::extra::U4, ", $s_fixed, "}; +type Fix = ", $s_fixed, "; +assert_eq!(Fix::from_num(7.5).unwrapped_div_euclid_int(2), Fix::from_num(3)); +", + if_signed_else_empty_str! { + $Signedness, + "assert_eq!(Fix::from_num(-7.5).unwrapped_div_euclid_int(2), Fix::from_num(-4)); +``` + +The following panics because of overflow. + +```should_panic +use fixed::{types::extra::U4, ", $s_fixed, "}; +type Fix = ", $s_fixed, "; +let _overflow = Fix::MIN.unwrapped_div_euclid_int(-1); +", + }, + "``` + +[exp]: ../index.html#experimental-optional-features +"; + #[inline] + pub fn unwrapped_div_euclid_int(self, rhs: $Inner) -> $Fixed { + match self.overflowing_div_euclid_int(rhs) { + (_, true) => panic!("overflow"), + (ans, false) => ans, + } + } + } + + #[cfg(feature = "unwrapped")] + comment! { + "Unwrapped remainder for Euclidean division by an integer. Returns the remainder", + if_signed_unsigned! { + $Signedness, + ", panicking on overflow. + +Note that while remainder for Euclidean division cannot be negative, +the wrapped value can be negative.", + ". + +Can never overflow for unsigned values.", + }, + " + +# Panics + +Panics if the divisor is zero", + if_signed_else_empty_str! { + $Signedness, + " or if the division results in overflow", + }, + ". + +# Examples + +```rust +use fixed::{types::extra::U", $s_nbits_m4, ", ", $s_fixed, "}; +type Fix = ", $s_fixed, "; +assert_eq!(Fix::from_num(7.5).unwrapped_rem_euclid_int(2), Fix::from_num(1.5)); +", + if_signed_else_empty_str! { + $Signedness, + "assert_eq!(Fix::from_num(-7.5).unwrapped_rem_euclid_int(2), Fix::from_num(0.5)); +``` + +The following panics because of overflow. + +```should_panic +use fixed::{types::extra::U", $s_nbits_m4, ", ", $s_fixed, "}; +type Fix = ", $s_fixed, "; +// −8 ≤ Fix < 8, so the answer 12.5 overflows +let _overflow = Fix::from_num(-7.5).unwrapped_rem_euclid_int(20); +", + }, + "``` + +[exp]: ../index.html#experimental-optional-features +"; + #[inline] + pub fn unwrapped_rem_euclid_int(self, rhs: $Inner) -> $Fixed { + match self.overflowing_rem_euclid_int(rhs) { + (_, true) => panic!("overflow"), + (ans, false) => ans, + } + } + } + if_signed! { $Signedness; comment! { diff --git a/src/macros_no_frac.rs b/src/macros_no_frac.rs index 2045671..bd21fa0 100644 --- a/src/macros_no_frac.rs +++ b/src/macros_no_frac.rs @@ -1228,6 +1228,391 @@ assert_eq!(Fix::MAX.wrapping_next_power_of_two(), 0); } } + #[cfg(feature = "unwrapped")] + comment! { + "Unwrapped negation. Returns the negated value, panicking on overflow. + +", + if_signed_unsigned! { + $Signedness, + "Overflow can only occur when negating the minimum value.", + "Only zero can be negated without overflow.", + }, + " + +This method is only available when the [`unwrapped` experimental +feature][exp] is enabled. + +# Panics + +Panics if the result does not fit. + +# Examples + +```rust +use fixed::{types::extra::U4, ", $s_fixed, "}; +type Fix = ", $s_fixed, "; +", + if_signed_unsigned! { + $Signedness, + concat!( + "assert_eq!(Fix::from_num(5).unwrapped_neg(), Fix::from_num(-5)); +``` + +The following panics because of overflow. + +```should_panic +use fixed::{types::extra::U4, ", $s_fixed, "}; +type Fix = ", $s_fixed, "; +let _overflow = Fix::MIN.unwrapped_neg();", + ), + concat!( + "assert_eq!(Fix::from_num(0).unwrapped_neg(), Fix::from_num(0)); +``` + +The following panics because of overflow. + +```should_panic +use fixed::{types::extra::U4, ", $s_fixed, "}; +type Fix = ", $s_fixed, "; +let _overflow = Fix::from_num(5).unwrapped_neg();", + ), + }, + " +``` + +[exp]: ../index.html#experimental-optional-features +"; + #[inline] + pub fn unwrapped_neg(self) -> $Fixed { + self.checked_neg().expect("overflow") + } + } + + #[cfg(feature = "unwrapped")] + comment! { + "Unwrapped addition. Returns the sum, panicking on overflow. + +This method is only available when the [`unwrapped` experimental +feature][exp] is enabled. + +# Panics + +Panics if the result does not fit. + +# Examples + +```rust +use fixed::{types::extra::U4, ", $s_fixed, "}; +type Fix = ", $s_fixed, "; +assert_eq!(Fix::from_num(3).unwrapped_add(Fix::from_num(2)), Fix::from_num(5)); +``` + +The following panics because of overflow. + +```should_panic +use fixed::{types::extra::U4, ", $s_fixed, "}; +type Fix = ", $s_fixed, "; +let _overflow = Fix::MAX.unwrapped_add(Fix::from_bits(1)); +``` + +[exp]: ../index.html#experimental-optional-features +"; + #[inline] + pub fn unwrapped_add(self, rhs: $Fixed) -> $Fixed { + self.checked_add(rhs).expect("overflow") + } + } + + #[cfg(feature = "unwrapped")] + comment! { + "Unwrapped subtraction. Returns the difference, panicking on overflow. + +This method is only available when the [`unwrapped` experimental +feature][exp] is enabled. + +# Panics + +Panics if the result does not fit. + +# Examples + +```rust +use fixed::{types::extra::U4, ", $s_fixed, "}; +type Fix = ", $s_fixed, "; +", + if_signed_unsigned! { + $Signedness, + "assert_eq!(Fix::from_num(3).unwrapped_sub(Fix::from_num(5)), Fix::from_num(-2)); +", + "assert_eq!(Fix::from_num(5).unwrapped_sub(Fix::from_num(3)), Fix::from_num(2)); +", + }, + "``` + +The following panics because of overflow. + +```should_panic +use fixed::{types::extra::U4, ", $s_fixed, "}; +type Fix = ", $s_fixed, "; +let _overflow = Fix::MIN.unwrapped_sub(Fix::from_bits(1)); +``` + +[exp]: ../index.html#experimental-optional-features +"; + #[inline] + pub fn unwrapped_sub(self, rhs: $Fixed) -> $Fixed { + self.checked_sub(rhs).expect("overflow") + } + } + + #[cfg(feature = "unwrapped")] + comment! { + "Unwrapped multiplication by an integer. Returns the product, panicking on overflow. + +This method is only available when the [`unwrapped` experimental +feature][exp] is enabled. + +# Panics + +Panics if the result does not fit. + +# Examples + +```rust +use fixed::{types::extra::U4, ", $s_fixed, "}; +type Fix = ", $s_fixed, "; +assert_eq!(Fix::from_num(3).unwrapped_mul_int(2), Fix::from_num(6)); +``` + +The following panics because of overflow. + +```should_panic +use fixed::{types::extra::U4, ", $s_fixed, "}; +type Fix = ", $s_fixed, "; +let _overflow = Fix::MAX.unwrapped_mul_int(4); +``` + +[exp]: ../index.html#experimental-optional-features +"; + #[inline] + pub fn unwrapped_mul_int(self, rhs: $Inner) -> $Fixed { + self.checked_mul_int(rhs).expect("overflow") + } + } + + #[cfg(feature = "unwrapped")] + comment! { + "Unwrapped division by an integer. Returns the quotient", + if_signed_unsigned! { + $Signedness, + ", panicking on overflow. + +Overflow can only occur when dividing the minimum value by −1.", + ". + +Can never overflow for unsigned values.", + }, + " + +This method is only available when the [`unwrapped` experimental +feature][exp] is enabled. + +# Panics + +Panics if the divisor is zero", + if_signed_else_empty_str! { + $Signedness, + " or if the division results in overflow", + }, + ". + +# Examples + +```rust +use fixed::{types::extra::U4, ", $s_fixed, "}; +type Fix = ", $s_fixed, "; +// 1.5 is binary 1.1 +let one_point_5 = Fix::from_bits(0b11 << (4 - 1)); +assert_eq!(Fix::from_num(3).unwrapped_div_int(2), one_point_5); +", + if_signed_else_empty_str! { + $Signedness, + "``` + +The following panics because of overflow. + +```should_panic +use fixed::{types::extra::U4, ", $s_fixed, "}; +type Fix = ", $s_fixed, "; +let _overflow = Fix::MIN.unwrapped_div_int(-1); +", + }, + "``` + +[exp]: ../index.html#experimental-optional-features +"; + #[inline] + pub fn unwrapped_div_int(self, rhs: $Inner) -> $Fixed { + match self.overflowing_div_int(rhs) { + (_, true) => panic!("overflow"), + (ans, false) => ans, + } + } + } + + #[cfg(feature = "unwrapped")] + comment! { + "Unwrapped shift left. Panics if `rhs` ≥ ", $s_nbits, ". + +This method is only available when the [`unwrapped` experimental +feature][exp] is enabled. + +# Panics + +Panics if `rhs` ≥ ", $s_nbits, ". + +# Examples + +```rust +use fixed::{types::extra::U4, ", $s_fixed, "}; +type Fix = ", $s_fixed, "; +assert_eq!((Fix::from_num(1) / 2).unwrapped_shl(3), Fix::from_num(4)); +``` + +The following panics because of overflow. + +```should_panic +use fixed::{types::extra::U4, ", $s_fixed, "}; +type Fix = ", $s_fixed, "; +let _overflow = Fix::from_num(1).unwrapped_shl(", $s_nbits, "); +``` + +[exp]: ../index.html#experimental-optional-features +"; + #[inline] + pub fn unwrapped_shl(self, rhs: u32) -> $Fixed { + self.checked_shl(rhs).expect("overflow") + } + } + + #[cfg(feature = "unwrapped")] + comment! { + "Unwrapped shift right. Panics if `rhs` ≥ ", $s_nbits, ". + +This method is only available when the [`unwrapped` experimental +feature][exp] is enabled. + +# Panics + +Panics if `rhs` ≥ ", $s_nbits, ". + +# Examples + +```rust +use fixed::{types::extra::U4, ", $s_fixed, "}; +type Fix = ", $s_fixed, "; +assert_eq!((Fix::from_num(4)).unwrapped_shr(3), Fix::from_num(1) / 2); +``` + +The following panics because of overflow. + +```should_panic +use fixed::{types::extra::U4, ", $s_fixed, "}; +type Fix = ", $s_fixed, "; +let _overflow = Fix::from_num(1).unwrapped_shr(", $s_nbits, "); +``` + +[exp]: ../index.html#experimental-optional-features +"; + #[inline] + pub fn unwrapped_shr(self, rhs: u32) -> $Fixed { + self.checked_shr(rhs).expect("overflow") + } + } + + #[cfg(feature = "unwrapped")] + if_signed! { + $Signedness; + comment! { + "Unwrapped absolute value. Returns the absolute value, panicking on overflow. + +Overflow can only occur when trying to find the absolute value of the minimum value. + +This method is only available when the [`unwrapped` experimental +feature][exp] is enabled. + +# Panics + +Panics if the result does not fit. + +# Examples + +```rust +use fixed::{types::extra::U4, ", $s_fixed, "}; +type Fix = ", $s_fixed, "; +assert_eq!(Fix::from_num(-5).unwrapped_abs(), Fix::from_num(5)); +``` + +The following panics because of overflow. + +```should_panic +use fixed::{types::extra::U4, ", $s_fixed, "}; +type Fix = ", $s_fixed, "; +let _overflow = Fix::MIN.unwrapped_abs(); +``` + +[exp]: ../index.html#experimental-optional-features +"; + #[inline] + pub fn unwrapped_abs(self) -> $Fixed { + self.checked_abs().expect("overflow") + } + } + } + + if_unsigned! { + $Signedness; + comment! { + "Returns the smallest power of two that is ≥ `self`, +panicking if the next power of two is too large to represent. + +This method is only available when the [`unwrapped` experimental +feature][exp] is enabled. + +# Panics + +Panics if the result does not fit. + +# Examples + +```rust +use fixed::{types::extra::U4, ", $s_fixed, "}; +type Fix = ", $s_fixed, "; +// 3/8 is 0.0110 +let three_eights = Fix::from_bits(0b0110); +// 1/2 is 0.1000 +let half = Fix::from_bits(0b1000); +assert_eq!(three_eights.unwrapped_next_power_of_two(), half); +``` + +The following panics because of overflow. + +```should_panic +use fixed::{types::extra::U4, ", $s_fixed, "}; +type Fix = ", $s_fixed, "; +let _overflow = Fix::MAX.unwrapped_next_power_of_two(); +``` + +[exp]: ../index.html#experimental-optional-features +"; + #[inline] + pub fn unwrapped_next_power_of_two(self) -> $Fixed { + self.checked_next_power_of_two().expect("overflow") + } + } + } + comment! { "Overflowing negation. diff --git a/src/traits.rs b/src/traits.rs index 9c3eeb6..57d26e7 100644 --- a/src/traits.rs +++ b/src/traits.rs @@ -1035,6 +1035,168 @@ where /// bits, then shifts and returns the number. fn wrapping_shr(self, rhs: u32) -> Self; + #[cfg(feature = "unwrapped")] + /// Unwrapped negation. Returns the negated value, panicking on overflow. + /// + /// This method is only available when the [`unwrapped` + /// experimental feature][exp] is enabled. + /// + /// # Panics + /// + /// Panics if the result does not fit. + /// + /// [exp]: ../index.html#experimental-optional-features + fn unwrapped_neg(self) -> Self; + + #[cfg(feature = "unwrapped")] + /// Unwrapped addition. Returns the sum, panicking on overflow. + /// + /// This method is only available when the [`unwrapped` + /// experimental feature][exp] is enabled. + /// + /// # Panics + /// + /// Panics if the result does not fit. + /// + /// [exp]: ../index.html#experimental-optional-features + fn unwrapped_add(self, rhs: Self) -> Self; + + #[cfg(feature = "unwrapped")] + /// Unwrapped subtraction. Returns the difference, panicking on overflow. + /// + /// This method is only available when the [`unwrapped` + /// experimental feature][exp] is enabled. + /// + /// # Panics + /// + /// Panics if the result does not fit. + /// + /// [exp]: ../index.html#experimental-optional-features + fn unwrapped_sub(self, rhs: Self) -> Self; + + #[cfg(feature = "unwrapped")] + /// Unwrapped multiplication. Returns the product, panicking on overflow. + /// + /// This method is only available when the [`unwrapped` + /// experimental feature][exp] is enabled. + /// + /// # Panics + /// + /// Panics if the result does not fit. + /// + /// [exp]: ../index.html#experimental-optional-features + fn unwrapped_mul(self, rhs: Self) -> Self; + + #[cfg(feature = "unwrapped")] + /// Unwrapped division. Returns the quotient, panicking on overflow. + /// + /// This method is only available when the [`unwrapped` + /// experimental feature][exp] is enabled. + /// + /// # Panics + /// + /// Panics if the divisor is zero or if the result does not fit. + /// + /// [exp]: ../index.html#experimental-optional-features + fn unwrapped_div(self, rhs: Self) -> Self; + + #[cfg(feature = "unwrapped")] + /// Unwrapped Euclidean division. Returns the quotient, panicking on overflow. + /// + /// This method is only available when the [`unwrapped` + /// experimental feature][exp] is enabled. + /// + /// # Panics + /// + /// Panics if the divisor is zero or if the result does not fit. + /// + /// [exp]: ../index.html#experimental-optional-features + fn unwrapped_div_euclid(self, rhs: Self) -> Self; + + #[cfg(feature = "unwrapped")] + /// Unwrapped multiplication by an integer. Returns the product, panicking on overflow. + /// + /// This method is only available when the [`unwrapped` + /// experimental feature][exp] is enabled. + /// + /// # Panics + /// + /// Panics if the result does not fit. + /// + /// [exp]: ../index.html#experimental-optional-features + fn unwrapped_mul_int(self, rhs: Self::Bits) -> Self; + + #[cfg(feature = "unwrapped")] + /// Unwrapped division by an integer. Returns the quotient, panicking on overflow. + /// + /// Overflow can only occur when dividing the minimum value by −1. + /// + /// This method is only available when the [`unwrapped` + /// experimental feature][exp] is enabled. + /// + /// # Panics + /// + /// Panics if the divisor is zero or if the result does not fit. + /// + /// [exp]: ../index.html#experimental-optional-features + fn unwrapped_div_int(self, rhs: Self::Bits) -> Self; + + #[cfg(feature = "unwrapped")] + /// Unwrapped Euclidean division by an integer. Returns the + /// quotient, panicking on overflow. + /// + /// Overflow can only occur when dividing the minimum value by −1. + /// + /// This method is only available when the [`unwrapped` + /// experimental feature][exp] is enabled. + /// + /// # Panics + /// + /// Panics if the divisor is zero or if the result does not fit. + /// + /// [exp]: ../index.html#experimental-optional-features + fn unwrapped_div_euclid_int(self, rhs: Self::Bits) -> Self; + + #[cfg(feature = "unwrapped")] + /// Unwrapped remainder for Euclidean division by an integer. + /// Returns the remainder, panicking on overflow. + /// + /// This method is only available when the [`unwrapped` + /// experimental feature][exp] is enabled. + /// + /// # Panics + /// + /// Panics if the divisor is zero or if the result does not fit. + /// + /// [exp]: ../index.html#experimental-optional-features + fn unwrapped_rem_euclid_int(self, rhs: Self::Bits) -> Self; + + #[cfg(feature = "unwrapped")] + /// Unwrapped shift left. Panics if `rhs` ≥ the number of bits. + /// + /// This method is only available when the [`unwrapped` + /// experimental feature][exp] is enabled. + /// + /// # Panics + /// + /// Panics if `rhs` ≥ the number of bits. + /// + /// [exp]: ../index.html#experimental-optional-features + fn unwrapped_shl(self, rhs: u32) -> Self; + + #[cfg(feature = "unwrapped")] + /// Unwrapped shift right. Panics if `rhs` ≥ the number of bits. + /// + /// This method is only available when the [`unwrapped` + /// experimental feature][exp] is enabled. + /// + /// # Panics + /// + /// Panics if `rhs` ≥ the number of bits. + /// + /// [exp]: ../index.html#experimental-optional-features + fn unwrapped_shr(self, rhs: u32) -> Self; + /// Overflowing negation. /// /// Returns a [tuple] of the negated value and a [`bool`], @@ -1271,6 +1433,41 @@ pub trait FixedSigned: Fixed + Neg { /// integer bits, such that it cannot hold the value −1. fn wrapping_signum(self) -> Self; + #[cfg(feature = "unwrapped")] + /// Unwrapped absolute value. Returns the absolute value, panicking on overflow. + /// + /// Overflow can only occur when trying to find the absolute value of the minimum value. + /// + /// This method is only available when the [`unwrapped` + /// experimental feature][exp] is enabled. + /// + /// # Panics + /// + /// Panics if the result does not fit. + /// + /// [exp]: ../index.html#experimental-optional-features + fn unwrapped_abs(self) -> Self; + + #[cfg(feature = "unwrapped")] + /// Unwrapped signum. Returns a number representing the sign of + /// `self`, panicking on overflow. + /// + /// Overflow can only occur + /// * if the value is positive and the fixed-point number has zero + /// or one integer bits such that it cannot hold the value 1. + /// * if the value is negative and the fixed-point number has zero + /// integer bits, such that it cannot hold the value −1. + /// + /// This method is only available when the [`unwrapped` + /// experimental feature][exp] is enabled. + /// + /// # Panics + /// + /// Panics if the result does not fit. + /// + /// [exp]: ../index.html#experimental-optional-features + fn unwrapped_signum(self) -> Self; + /// Overflowing absolute value. /// /// Returns a [tuple] of the fixed-point number and a [`bool`], @@ -1332,6 +1529,20 @@ pub trait FixedUnsigned: Fixed { /// Returns the smallest power of two that is ≥ `self`, wrapping /// to 0 if the next power of two is too large to represent. fn wrapping_next_power_of_two(self) -> Self; + + #[cfg(feature = "unwrapped")] + /// Returns the smallest power of two that is ≥ `self`, panicking + /// if the next power of two is too large to represent. + /// + /// This method is only available when the [`unwrapped` + /// experimental feature][exp] is enabled. + /// + /// # Panics + /// + /// Panics if the result does not fit. + /// + /// [exp]: ../index.html#experimental-optional-features + fn unwrapped_next_power_of_two(self) -> Self; } /// This trait provides lossless conversions that might be fallible. @@ -2169,6 +2380,30 @@ macro_rules! impl_fixed { trait_delegate! { fn wrapping_rem_euclid_int(self, rhs: Self::Bits) -> Self } trait_delegate! { fn wrapping_shl(self, rhs: u32) -> Self } trait_delegate! { fn wrapping_shr(self, rhs: u32) -> Self } + #[cfg(feature = "unwrapped")] + trait_delegate! { fn unwrapped_neg(self) -> Self } + #[cfg(feature = "unwrapped")] + trait_delegate! { fn unwrapped_add(self, rhs: Self) -> Self } + #[cfg(feature = "unwrapped")] + trait_delegate! { fn unwrapped_sub(self, rhs: Self) -> Self } + #[cfg(feature = "unwrapped")] + trait_delegate! { fn unwrapped_mul(self, rhs: Self) -> Self } + #[cfg(feature = "unwrapped")] + trait_delegate! { fn unwrapped_div(self, rhs: Self) -> Self } + #[cfg(feature = "unwrapped")] + trait_delegate! { fn unwrapped_div_euclid(self, rhs: Self) -> Self } + #[cfg(feature = "unwrapped")] + trait_delegate! { fn unwrapped_mul_int(self, rhs: Self::Bits) -> Self } + #[cfg(feature = "unwrapped")] + trait_delegate! { fn unwrapped_div_int(self, rhs: Self::Bits) -> Self } + #[cfg(feature = "unwrapped")] + trait_delegate! { fn unwrapped_div_euclid_int(self, rhs: Self::Bits) -> Self } + #[cfg(feature = "unwrapped")] + trait_delegate! { fn unwrapped_rem_euclid_int(self, rhs: Self::Bits) -> Self } + #[cfg(feature = "unwrapped")] + trait_delegate! { fn unwrapped_shl(self, rhs: u32) -> Self } + #[cfg(feature = "unwrapped")] + trait_delegate! { fn unwrapped_shr(self, rhs: u32) -> Self } trait_delegate! { fn overflowing_neg(self) -> (Self, bool) } trait_delegate! { fn overflowing_add(self, rhs: Self) -> (Self, bool) } trait_delegate! { fn overflowing_sub(self, rhs: Self) -> (Self, bool) } @@ -2346,6 +2581,10 @@ macro_rules! impl_fixed { trait_delegate! { fn saturating_signum(self) -> Self } trait_delegate! { fn wrapping_abs(self) -> Self } trait_delegate! { fn wrapping_signum(self) -> Self } + #[cfg(feature = "unwrapped")] + trait_delegate! { fn unwrapped_abs(self) -> Self } + #[cfg(feature = "unwrapped")] + trait_delegate! { fn unwrapped_signum(self) -> Self } trait_delegate! { fn overflowing_abs(self) -> (Self, bool) } trait_delegate! { fn overflowing_signum(self) -> (Self, bool) } trait_delegate! { fn is_positive(self) -> bool } @@ -2360,6 +2599,8 @@ macro_rules! impl_fixed { trait_delegate! { fn next_power_of_two(self) -> Self } trait_delegate! { fn checked_next_power_of_two(self) -> Option } trait_delegate! { fn wrapping_next_power_of_two(self) -> Self } + #[cfg(feature = "unwrapped")] + trait_delegate! { fn unwrapped_next_power_of_two(self) -> Self } } } };