add unwrapped arithmetic methods
This commit is contained in:
parent
ff9211e9ab
commit
8756a4bd5c
|
@ -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, "<U4>;
|
||||
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, "<U", $s_nbits_m1, ">;
|
||||
let _overflow = OneIntBit::from_num(0.5).unwrapped_signum();
|
||||
```
|
||||
|
||||
[exp]: ../index.html#experimental-optional-features
|
||||
";
|
||||
#[inline]
|
||||
pub fn unwrapped_signum(self) -> $Fixed<Frac> {
|
||||
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, "<U4>;
|
||||
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, "<U4>;
|
||||
let _overflow = Fix::MAX.unwrapped_mul(Fix::from_num(4));
|
||||
```
|
||||
|
||||
[exp]: ../index.html#experimental-optional-features
|
||||
";
|
||||
#[inline]
|
||||
pub fn unwrapped_mul(self, rhs: $Fixed<Frac>) -> $Fixed<Frac> {
|
||||
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, "<U4>;
|
||||
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, "<U4>;
|
||||
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<Frac>) -> $Fixed<Frac> {
|
||||
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, "<U4>;
|
||||
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, "<U4>;
|
||||
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<Frac>) -> $Fixed<Frac> {
|
||||
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, "<U4>;
|
||||
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, "<U4>;
|
||||
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<Frac> {
|
||||
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, "<U", $s_nbits_m4, ">;
|
||||
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, "<U", $s_nbits_m4, ">;
|
||||
// −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<Frac> {
|
||||
match self.overflowing_rem_euclid_int(rhs) {
|
||||
(_, true) => panic!("overflow"),
|
||||
(ans, false) => ans,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if_signed! {
|
||||
$Signedness;
|
||||
comment! {
|
||||
|
|
|
@ -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, "<U4>;
|
||||
",
|
||||
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, "<U4>;
|
||||
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, "<U4>;
|
||||
let _overflow = Fix::from_num(5).unwrapped_neg();",
|
||||
),
|
||||
},
|
||||
"
|
||||
```
|
||||
|
||||
[exp]: ../index.html#experimental-optional-features
|
||||
";
|
||||
#[inline]
|
||||
pub fn unwrapped_neg(self) -> $Fixed<Frac> {
|
||||
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, "<U4>;
|
||||
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, "<U4>;
|
||||
let _overflow = Fix::MAX.unwrapped_add(Fix::from_bits(1));
|
||||
```
|
||||
|
||||
[exp]: ../index.html#experimental-optional-features
|
||||
";
|
||||
#[inline]
|
||||
pub fn unwrapped_add(self, rhs: $Fixed<Frac>) -> $Fixed<Frac> {
|
||||
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, "<U4>;
|
||||
",
|
||||
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, "<U4>;
|
||||
let _overflow = Fix::MIN.unwrapped_sub(Fix::from_bits(1));
|
||||
```
|
||||
|
||||
[exp]: ../index.html#experimental-optional-features
|
||||
";
|
||||
#[inline]
|
||||
pub fn unwrapped_sub(self, rhs: $Fixed<Frac>) -> $Fixed<Frac> {
|
||||
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, "<U4>;
|
||||
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, "<U4>;
|
||||
let _overflow = Fix::MAX.unwrapped_mul_int(4);
|
||||
```
|
||||
|
||||
[exp]: ../index.html#experimental-optional-features
|
||||
";
|
||||
#[inline]
|
||||
pub fn unwrapped_mul_int(self, rhs: $Inner) -> $Fixed<Frac> {
|
||||
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, "<U4>;
|
||||
// 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, "<U4>;
|
||||
let _overflow = Fix::MIN.unwrapped_div_int(-1);
|
||||
",
|
||||
},
|
||||
"```
|
||||
|
||||
[exp]: ../index.html#experimental-optional-features
|
||||
";
|
||||
#[inline]
|
||||
pub fn unwrapped_div_int(self, rhs: $Inner) -> $Fixed<Frac> {
|
||||
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, "<U4>;
|
||||
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, "<U4>;
|
||||
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<Frac> {
|
||||
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, "<U4>;
|
||||
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, "<U4>;
|
||||
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<Frac> {
|
||||
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, "<U4>;
|
||||
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, "<U4>;
|
||||
let _overflow = Fix::MIN.unwrapped_abs();
|
||||
```
|
||||
|
||||
[exp]: ../index.html#experimental-optional-features
|
||||
";
|
||||
#[inline]
|
||||
pub fn unwrapped_abs(self) -> $Fixed<Frac> {
|
||||
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, "<U4>;
|
||||
// 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, "<U4>;
|
||||
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<Frac> {
|
||||
self.checked_next_power_of_two().expect("overflow")
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
comment! {
|
||||
"Overflowing negation.
|
||||
|
||||
|
|
241
src/traits.rs
241
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<Output = Self> {
|
|||
/// 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<Self> }
|
||||
trait_delegate! { fn wrapping_next_power_of_two(self) -> Self }
|
||||
#[cfg(feature = "unwrapped")]
|
||||
trait_delegate! { fn unwrapped_next_power_of_two(self) -> Self }
|
||||
}
|
||||
}
|
||||
};
|
||||
|
|
Loading…
Reference in New Issue