blockworks-foundation
/
fixed
mirror of https://github.com/blockworks-foundation/fixed.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

use imports throughout doc examples

This commit is contained in:
Trevor Spiteri 2019-08-16 22:57:31 +02:00
parent 637a87524c
commit c6cacadfa0
6 changed files with 320 additions and 559 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
src/consts.rs
View File

@ -22,7 +22,8 @@ number, and are rounded down at that precision.
# Examples
```rust
let tau: fixed::types::I8F8 = fixed::consts::TAU.to_num();
use fixed::{consts, types::I8F8};
let tau = I8F8::from_num(consts::TAU);
println!("τ = 2π with eight binary places is {:b}", tau);
assert_eq!(format!("{:b}", tau), "110.01001000");
```

131
src/lib.rs
View File

@ -299,21 +299,13 @@ are implemented by the Rust compiler.
# Examples
```rust
use fixed::{frac::U3, ",
$s_fixed,
"};
let eleven = ",
$s_fixed,
"::<U3>::from_num(11);
assert_eq!(eleven, ",
$s_fixed,
"::<U3>::from_bits(11 << 3));
use fixed::{frac::U3, ", $s_fixed, "};
let eleven = ", $s_fixed, "::<U3>::from_num(11);
assert_eq!(eleven, ", $s_fixed, "::<U3>::from_bits(11 << 3));
assert_eq!(eleven, 11);
assert_eq!(eleven.to_string(), \"11.0\");
let two_point_75 = eleven / 4;
assert_eq!(two_point_75, ",
$s_fixed,
"::<U3>::from_bits(11 << 1));
assert_eq!(two_point_75, ", $s_fixed, "::<U3>::from_bits(11 << 1));
assert_eq!(two_point_75, 2.75);
assert_eq!(two_point_75.to_string(), \"2.8\");
```
@ -365,12 +357,9 @@ assert_eq!(two_point_75.to_string(), \"2.8\");
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
assert_eq!(Fix::min_value(), Fix::from_bits(",
$s_inner,
"::min_value()));
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
assert_eq!(Fix::min_value(), Fix::from_bits(", $s_inner, "::min_value()));
```
";
$Fixed($Inner) => fn min_value()
@ -381,12 +370,9 @@ assert_eq!(Fix::min_value(), Fix::from_bits(",
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
assert_eq!(Fix::max_value(), Fix::from_bits(",
$s_inner,
"::max_value()));
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
assert_eq!(Fix::max_value(), Fix::from_bits(", $s_inner, "::max_value()));
```
";
$Fixed($Inner) => fn max_value()
@ -398,12 +384,9 @@ assert_eq!(Fix::max_value(), Fix::from_bits(",
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U6>;
assert_eq!(Fix::int_nbits(), ",
$s_nbits,
" - 6);
use fixed::{frac::U6, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U6>;
assert_eq!(Fix::int_nbits(), ", $s_nbits, " - 6);
```
";
#[inline]
@ -418,9 +401,8 @@ assert_eq!(Fix::int_nbits(), ",
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U6>;
use fixed::{frac::U6, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U6>;
assert_eq!(Fix::frac_nbits(), 6);
```
";
@ -440,9 +422,8 @@ representation.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
let f = Fix::from_bits(0b11_0010);
assert_eq!(f.count_ones(), 3);
```
@ -456,9 +437,8 @@ representation.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
let f = Fix::from_bits(!0b11_0010);
assert_eq!(f.count_zeros(), 3);
```
@ -472,13 +452,10 @@ representation.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
let f = Fix::from_bits(0b10_0000);
assert_eq!(f.leading_zeros(), ",
$s_nbits,
" - 6);
assert_eq!(f.leading_zeros(), ", $s_nbits, " - 6);
```
";
$Fixed => fn leading_zeros(self) -> u32
@ -490,9 +467,8 @@ representation.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
let f = Fix::from_bits(0b10_0000);
assert_eq!(f.trailing_zeros(), 5);
```
@ -506,14 +482,9 @@ truncated bits to the right end.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
let bits: ",
$s_inner,
" = (0b111 << (",
$s_nbits,
" - 3)) | 0b1010;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
let bits: ", $s_inner, " = (0b111 << (", $s_nbits, " - 3)) | 0b1010;
let rot = 0b1010111;
assert_eq!(bits.rotate_left(3), rot);
assert_eq!(Fix::from_bits(bits).rotate_left(3), Fix::from_bits(rot));
@ -528,15 +499,10 @@ truncated bits to the left end.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
let bits: ",
$s_inner,
" = 0b1010111;
let rot = (0b111 << (",
$s_nbits,
" - 3)) | 0b1010;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
let bits: ", $s_inner, " = 0b1010111;
let rot = (0b111 << (", $s_nbits, " - 3)) | 0b1010;
assert_eq!(bits.rotate_right(3), rot);
assert_eq!(Fix::from_bits(bits).rotate_right(3), Fix::from_bits(rot));
```
@ -552,9 +518,8 @@ assert_eq!(Fix::from_bits(bits).rotate_right(3), Fix::from_bits(rot));
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
let five = Fix::from_num(5);
let minus_five = Fix::from_num(-5);
assert_eq!(five.abs(), five);
@ -583,9 +548,8 @@ represented is almost certainly a bug.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
assert_eq!(Fix::from_num(5).signum(), 1);
assert_eq!(Fix::from_num(0).signum(), 0);
assert_eq!(Fix::from_num(-5).signum(), -1);
@ -613,9 +577,8 @@ assert_eq!(Fix::from_num(-5).signum(), -1);
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::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
@ -642,9 +605,8 @@ future it panics.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::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
@ -663,9 +625,8 @@ assert_eq!(half.next_power_of_two(), half);
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::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
@ -691,9 +652,8 @@ assert!(Fix::max_value().checked_next_power_of_two().is_none());
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
assert!(Fix::from_num(5).is_positive());
assert!(!Fix::from_num(0).is_positive());
assert!(!Fix::from_num(-5).is_positive());
@ -710,9 +670,8 @@ assert!(!Fix::from_num(-5).is_positive());
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
assert!(!Fix::from_num(5).is_negative());
assert!(!Fix::from_num(0).is_negative());
assert!(Fix::from_num(-5).is_negative());

254
src/macros_checked_arith.rs
View File

@ -29,9 +29,8 @@ macro_rules! fixed_checked_arith {
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
",
if_signed_unsigned!(
$Signedness,
@ -57,9 +56,8 @@ assert_eq!(Fix::from_num(5).checked_neg(), None);",
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
let one = Fix::from_num(1);
assert_eq!((Fix::max_value() - one).checked_add(one), Some(Fix::max_value()));
assert_eq!(Fix::max_value().checked_add(one), None);
@ -79,9 +77,8 @@ assert_eq!(Fix::max_value().checked_add(one), None);
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
let one = Fix::from_num(1);
assert_eq!((Fix::min_value() + one).checked_sub(one), Some(Fix::min_value()));
assert_eq!(Fix::min_value().checked_sub(one), None);
@ -101,9 +98,8 @@ assert_eq!(Fix::min_value().checked_sub(one), None);
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
assert_eq!(Fix::max_value().checked_mul(Fix::from_num(1)), Some(Fix::max_value()));
assert_eq!(Fix::max_value().checked_mul(Fix::from_num(2)), None);
```
@ -127,9 +123,8 @@ the divisor is zero or on overflow.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
assert_eq!(Fix::max_value().checked_div(Fix::from_num(1)), Some(Fix::max_value()));
assert_eq!(Fix::max_value().checked_div(Fix::from_num(1) / 2), None);
```
@ -156,9 +151,8 @@ product, or [`None`] on overflow.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
assert_eq!(Fix::max_value().checked_mul_int(1), Some(Fix::max_value()));
assert_eq!(Fix::max_value().checked_mul_int(2), None);
```
@ -184,9 +178,8 @@ assert_eq!(Fix::max_value().checked_mul_int(2), None);
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
assert_eq!(Fix::max_value().checked_div_int(1), Some(Fix::max_value()));
assert_eq!(Fix::from_num(1).checked_div_int(0), None);
",
@ -218,9 +211,8 @@ Returns the remainder, or [`None`] if the divisor is zero",
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
// binary 1.0101 / 8 = binary 0.0010 remainder 0.0101
assert_eq!(Fix::from_bits(0b10101).checked_rem_int(8), Some(Fix::from_bits(0b101)));
assert_eq!(Fix::from_num(1).checked_rem_int(0), None);
@ -241,20 +233,16 @@ assert_eq!(Fix::from_num(1).checked_rem_int(0), None);
);
comment!(
"Checked shift left. Returns the shifted number, or [`None`] if `rhs` ≥ ",
$s_nbits,
".
"Checked shift left. Returns the shifted number,
or [`None`] if `rhs` ≥ ", $s_nbits, ".
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
assert_eq!((Fix::from_num(1) / 2).checked_shl(3), Some(Fix::from_num(4)));
assert_eq!((Fix::from_num(1) / 2).checked_shl(",
$s_nbits,
"), None);
assert_eq!((Fix::from_num(1) / 2).checked_shl(", $s_nbits, "), None);
```
[`None`]: https://doc.rust-lang.org/nightly/std/option/enum.Option.html#variant.None
@ -266,20 +254,16 @@ assert_eq!((Fix::from_num(1) / 2).checked_shl(",
);
comment!(
"Checked shift right. Returns the shifted number, or [`None`] if `rhs` ≥ ",
$s_nbits,
".
"Checked shift right. Returns the shifted number,
or [`None`] if `rhs` ≥ ", $s_nbits, ".
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
assert_eq!(Fix::from_num(4).checked_shr(3), Some(Fix::from_num(1) / 2));
assert_eq!(Fix::from_num(4).checked_shr(",
$s_nbits,
"), None);
assert_eq!(Fix::from_num(4).checked_shr(", $s_nbits, "), None);
```
[`None`]: https://doc.rust-lang.org/nightly/std/option/enum.Option.html#variant.None
@ -300,9 +284,8 @@ Overflow can only occur when trying to find the absolute value of the minimum va
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
assert_eq!(Fix::from_num(-5).checked_abs(), Some(Fix::from_num(5)));
assert_eq!(Fix::min_value().checked_abs(), None);
```
@ -330,9 +313,8 @@ assert_eq!(Fix::min_value().checked_abs(), None);
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
",
if_signed_unsigned!(
$Signedness,
@ -360,9 +342,8 @@ assert_eq!(Fix::from_num(5).saturating_neg(), Fix::from_num(0));",
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
assert_eq!(Fix::from_num(3).saturating_add(Fix::from_num(2)), Fix::from_num(5));
assert_eq!(Fix::max_value().saturating_add(Fix::from_num(1)), Fix::max_value());
```
@ -376,9 +357,8 @@ assert_eq!(Fix::max_value().saturating_add(Fix::from_num(1)), Fix::max_value());
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
",
if_signed_unsigned!(
$Signedness,
@ -399,9 +379,8 @@ assert_eq!(Fix::from_num(0).saturating_sub(Fix::from_num(1)), Fix::from_num(0));
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
assert_eq!(Fix::from_num(3).saturating_mul(Fix::from_num(2)), Fix::from_num(6));
assert_eq!(Fix::max_value().saturating_mul(Fix::from_num(2)), Fix::max_value());
```
@ -427,9 +406,8 @@ Panics if the divisor is zero.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
let one_half = Fix::from_num(1) / 2;
assert_eq!(Fix::from_num(1).saturating_div(Fix::from_num(2)), one_half);
assert_eq!(Fix::max_value().saturating_div(one_half), Fix::max_value());
@ -452,9 +430,8 @@ assert_eq!(Fix::max_value().saturating_div(one_half), Fix::max_value());
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
assert_eq!(Fix::from_num(3).saturating_mul_int(2), Fix::from_num(6));
assert_eq!(Fix::max_value().saturating_mul_int(2), Fix::max_value());
```
@ -475,9 +452,8 @@ Overflow can only occur when trying to find the absolute value of the minimum va
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
assert_eq!(Fix::from_num(-5).saturating_abs(), Fix::from_num(5));
assert_eq!(Fix::min_value().saturating_abs(), Fix::max_value());
```
@ -503,9 +479,8 @@ assert_eq!(Fix::min_value().saturating_abs(), Fix::max_value());
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
",
if_signed_unsigned!(
$Signedness,
@ -528,9 +503,8 @@ assert_eq!(Fix::from_num(5).wrapping_neg(), Fix::from_bits(neg_five_bits));",
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
let one = Fix::from_num(1);
let one_minus_bit = one - Fix::from_bits(1);
assert_eq!(Fix::from_num(3).wrapping_add(Fix::from_num(2)), Fix::from_num(5));
@ -548,9 +522,8 @@ assert_eq!(Fix::max_value().wrapping_add(one), ",
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
let one = Fix::from_num(1);
let one_minus_bit = one - Fix::from_bits(1);
",
@ -573,9 +546,8 @@ assert_eq!(Fix::from_num(0)",
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
assert_eq!(Fix::from_num(3).wrapping_mul(Fix::from_num(2)), Fix::from_num(6));
let wrapped = Fix::from_bits(!0 << 2);
assert_eq!(Fix::max_value().wrapping_mul(Fix::from_num(4)), wrapped);
@ -598,9 +570,8 @@ Panics if the divisor is zero.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
let one_point_5 = Fix::from_bits(0b11 << (4 - 1));
assert_eq!(Fix::from_num(3).wrapping_div(Fix::from_num(2)), one_point_5);
let quarter = Fix::from_num(1) / 4;
@ -621,9 +592,8 @@ assert_eq!(Fix::max_value().wrapping_div(quarter), wrapped);
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
assert_eq!(Fix::from_num(3).wrapping_mul_int(2), Fix::from_num(6));
let wrapped = Fix::from_bits(!0 << 2);
assert_eq!(Fix::max_value().wrapping_mul_int(4), wrapped);
@ -655,9 +625,8 @@ Panics if the divisor is zero.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::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).wrapping_div_int(2), one_point_5);
@ -695,9 +664,8 @@ Panics if the divisor is zero.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
// binary 1.0101 / 8 = binary 0.0010 remainder 0.0101
assert_eq!(Fix::from_bits(0b10101).wrapping_rem_int(8), Fix::from_bits(0b101));
",
@ -715,40 +683,32 @@ assert_eq!(Fix::from_bits(0b10101).wrapping_rem_int(8), Fix::from_bits(0b101));
);
delegate!(
"Wrapping shift left. Wraps `rhs` if `rhs` ≥ ",
$s_nbits,
", then shifts and returns the number.
"Wrapping shift left. Wraps `rhs` if `rhs` ≥ ", $s_nbits, ",
then shifts and returns the number.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
assert_eq!((Fix::from_num(1) / 2).wrapping_shl(3), Fix::from_num(4));
assert_eq!((Fix::from_num(1) / 2).wrapping_shl(3 + ",
$s_nbits,
"), Fix::from_num(4));
assert_eq!((Fix::from_num(1) / 2).wrapping_shl(3 + ", $s_nbits, "), Fix::from_num(4));
```
";
$Fixed => fn wrapping_shl(self, rhs: u32)
);
delegate!(
"Wrapping shift right. Wraps `rhs` if `rhs` ≥ ",
$s_nbits,
", then shifts and returns the number.
"Wrapping shift right. Wraps `rhs` if `rhs` ≥ ", $s_nbits, ",
then shifts and returns the number.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
assert_eq!((Fix::from_num(4)).wrapping_shr(3), Fix::from_num(1) / 2);
assert_eq!((Fix::from_num(4)).wrapping_shr(3 + ",
$s_nbits,
"), Fix::from_num(1) / 2);
assert_eq!((Fix::from_num(4)).wrapping_shr(3 + ", $s_nbits, "), Fix::from_num(1) / 2);
```
";
$Fixed => fn wrapping_shr(self, rhs: u32)
@ -764,9 +724,8 @@ Overflow can only occur when trying to find the absolute value of the minimum va
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
assert_eq!(Fix::from_num(-5).wrapping_abs(), Fix::from_num(5));
assert_eq!(Fix::min_value().wrapping_abs(), Fix::min_value());
```
@ -792,9 +751,8 @@ an overflow has occurred. On overflow, the wrapped value is returned.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
",
if_signed_unsigned!(
$Signedness,
@ -827,9 +785,8 @@ overflow has occurred. On overflow, the wrapped value is returned.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
let one = Fix::from_num(1);
let one_minus_bit = one - Fix::from_bits(1);
assert_eq!(Fix::from_num(3).overflowing_add(Fix::from_num(2)), (Fix::from_num(5), false));
@ -857,9 +814,8 @@ overflow has occurred. On overflow, the wrapped value is returned.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
let one = Fix::from_num(1);
let one_minus_bit = one - Fix::from_bits(1);
",
@ -892,9 +848,8 @@ overflow has occurred. On overflow, the wrapped value is returned.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
assert_eq!(Fix::from_num(3).overflowing_mul(Fix::from_num(2)), (Fix::from_num(6), false));
let wrapped = Fix::from_bits(!0 << 2);
assert_eq!(Fix::max_value().overflowing_mul(Fix::from_num(4)), (wrapped, true));
@ -923,9 +878,8 @@ Panics if the divisor is zero.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
let one_point_5 = Fix::from_bits(0b11 << (4 - 1));
assert_eq!(Fix::from_num(3).overflowing_div(Fix::from_num(2)), (one_point_5, false));
let quarter = Fix::from_num(1) / 4;
@ -949,9 +903,8 @@ overflow has occurred. On overflow, the wrapped value is returned.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
assert_eq!(Fix::from_num(3).overflowing_mul_int(2), (Fix::from_num(6), false));
let wrapped = Fix::from_bits(!0 << 2);
assert_eq!(Fix::max_value().overflowing_mul_int(4), (wrapped, true));
@ -987,9 +940,8 @@ Panics if the divisor is zero.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::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).overflowing_div_int(2), (one_point_5, false));
@ -1031,9 +983,8 @@ Panics if the divisor is zero.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
// binary 1.0101 / 8 = binary 0.0010 remainder 0.0101
assert_eq!(Fix::from_bits(0b10101).overflowing_rem_int(8), (Fix::from_bits(0b101), false));
",
@ -1058,20 +1009,16 @@ assert_eq!(Fix::from_bits(0b10101).overflowing_rem_int(8), (Fix::from_bits(0b101
"Overflowing shift left.
Returns a [tuple] of the shifted value and a [`bool`] indicating whether
an overflow has occurred. Overflow occurs when `rhs` ≥ ",
$s_nbits,
". On overflow `rhs` is wrapped before the shift operation.
an overflow has occurred. Overflow occurs when `rhs` ≥ ", $s_nbits, ".
On overflow `rhs` is wrapped before the shift operation.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
assert_eq!((Fix::from_num(1) / 2).overflowing_shl(3), (Fix::from_num(4), false));
assert_eq!((Fix::from_num(1) / 2).overflowing_shl(3 + ",
$s_nbits,
"), (Fix::from_num(4), true));
assert_eq!((Fix::from_num(1) / 2).overflowing_shl(3 + ", $s_nbits, "), (Fix::from_num(4), true));
```
[`bool`]: https://doc.rust-lang.org/nightly/std/primitive.bool.html
@ -1088,20 +1035,16 @@ assert_eq!((Fix::from_num(1) / 2).overflowing_shl(3 + ",
"Overflowing shift right.
Returns a [tuple] of the shifted value and a [`bool`] indicating whether
an overflow has occurred. Overflow occurs when `rhs` ≥ ",
$s_nbits,
". On overflow `rhs` is wrapped before the shift operation.
an overflow has occurred. Overflow occurs when `rhs` ≥ ", $s_nbits, ".
On overflow `rhs` is wrapped before the shift operation.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
assert_eq!((Fix::from_num(4)).overflowing_shr(3), (Fix::from_num(1) / 2, false));
assert_eq!((Fix::from_num(4)).overflowing_shr(3 + ",
$s_nbits,
"), (Fix::from_num(1) / 2, true));
assert_eq!((Fix::from_num(4)).overflowing_shr(3 + ", $s_nbits, "), (Fix::from_num(1) / 2, true));
```
[`bool`]: https://doc.rust-lang.org/nightly/std/primitive.bool.html
@ -1128,9 +1071,8 @@ Overflow can only occur when trying to find the absolute value of the minimum va
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
assert_eq!(Fix::from_num(-5).overflowing_abs(), (Fix::from_num(5), false));
assert_eq!(Fix::min_value().overflowing_abs(), (Fix::min_value(), true));
```

276
src/macros_from_to.rs
View File

@ -22,12 +22,8 @@ representation identical to the given integer.
# Examples
```rust
use fixed::{frac::U4, ",
$s_fixed,
"};
type Fix = ",
$s_fixed,
"<U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
// 0010.0000 == 2
assert_eq!(Fix::from_bits(0b10_0000), 2);
```
@ -48,12 +44,8 @@ identical to the given fixed-point number.
# Examples
```rust
use fixed::{frac::U4, ",
$s_fixed,
"};
type Fix = ",
$s_fixed,
"<U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
// 2 is 0010.0000
assert_eq!(Fix::from_num(2).to_bits(), 0b10_0000);
```
@ -92,12 +84,8 @@ it panics; if wrapping is required use [`wrapping_from_num`] instead.
# Examples
```rust
use fixed::{frac::U4, types::I16F16, ",
$s_fixed,
"};
type Fix = ",
$s_fixed,
"<U4>;
use fixed::{frac::U4, types::I16F16, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
// 1.75 is 1.11 in binary
let src = I16F16::from_bits(0b111 << (16 - 2));
@ -176,12 +164,8 @@ it panics; if wrapping is required use [`wrapping_to_num`] instead.
# Examples
```rust
use fixed::{frac::U4, types::I30F2, ",
$s_fixed,
"};
type Fix = ",
$s_fixed,
"<U4>;
use fixed::{frac::U4, types::I30F2, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
// 1.75 is 1.11 in binary
let src = Fix::from_bits(0b111 << (4 - 2));
@ -261,26 +245,18 @@ The other number can be:
use fixed::{
frac::{U2, U4},
types::I16F16,
",
$s_fixed,
",
", $s_fixed, ",
};
type Fix = ",
$s_fixed,
"<U4>;
type Fix = ", $s_fixed, "<U4>;
// 1.75 is 1.11 in binary
let src = I16F16::from_bits(0b111 << (16 - 2));
assert_eq!(Fix::checked_from_num(src), Some(Fix::from_bits(0b111 << (4 - 2))));
let too_large = ",
$s_fixed,
"::<U2>::max_value();
let too_large = ", $s_fixed, "::<U2>::max_value();
assert!(Fix::checked_from_num(too_large).is_none());
assert_eq!(Fix::checked_from_num(3), Some(Fix::from_bits(3 << 4)));
let too_large = ",
$s_inner,
"::max_value();
let too_large = ", $s_inner, "::max_value();
assert!(Fix::checked_from_num(too_large).is_none());
let too_small = ",
if_signed_unsigned!(
@ -355,21 +331,15 @@ The other number can be:
use fixed::{
frac::{U0, U4, U6},
types::I16F16,
",
$s_fixed,
",
", $s_fixed, ",
};
type Fix = ",
$s_fixed,
"<U4>;
type Fix = ", $s_fixed, "<U4>;
// 1.75 is 1.11 in binary
let src = Fix::from_bits(0b111 << (4 - 2));
let expected = I16F16::from_bits(0b111 << (16 - 2));
assert_eq!(src.checked_to_num::<I16F16>(), Some(expected));
type TooFewIntBits = ",
$s_fixed,
"<U6>;
type TooFewIntBits = ", $s_fixed, "<U6>;
assert!(Fix::max_value().checked_to_num::<TooFewIntBits>().is_none());
// 2.5 is 10.1 in binary
@ -382,17 +352,14 @@ assert_eq!(",
"two_point_5.checked_to_num::<i64>(), Some(2",
),
"));
type AllInt = ",
$s_fixed,
"<U0>;
type AllInt = ", $s_fixed, "<U0>;
assert!(AllInt::",
if_signed_unsigned!(
$Signedness,
"from_bits(-1).checked_to_num::<u",
"max_value().checked_to_num::<i",
),
$s_nbits,
">().is_none());
$s_nbits, ">().is_none());
// 1.625 is 1.101 in binary
let one_point_625 = Fix::from_bits(0b1101 << (4 - 3));
@ -453,20 +420,14 @@ This method panics if the value is a floating-point [NaN].
use fixed::{
frac::{U2, U4},
types::I16F16,
",
$s_fixed,
",
", $s_fixed, ",
};
type Fix = ",
$s_fixed,
"<U4>;
type Fix = ", $s_fixed, "<U4>;
// 1.75 is 1.11 in binary
let src = I16F16::from_bits(0b111 << (16 - 2));
assert_eq!(Fix::saturating_from_num(src), Fix::from_bits(0b111 << (4 - 2)));
let too_large = ",
$s_fixed,
"::<U2>::max_value();
let too_large = ", $s_fixed, "::<U2>::max_value();
assert_eq!(Fix::saturating_from_num(too_large), Fix::max_value());
assert_eq!(Fix::saturating_from_num(3), Fix::from_bits(3 << 4));
@ -543,44 +504,29 @@ The other number can be:
use fixed::{
frac::{U0, U4, U6},
types::I16F16,
",
$s_fixed,
",
", $s_fixed, ",
};
type Fix = ",
$s_fixed,
"<U4>;
type Fix = ", $s_fixed, "<U4>;
// 1.75 is 1.11 in binary
let src = Fix::from_bits(0b111 << (4 - 2));
let expected = I16F16::from_bits(0b111 << (16 - 2));
assert_eq!(src.saturating_to_num::<I16F16>(), expected);
type TooFewIntBits = ",
$s_fixed,
"<U6>;
type TooFewIntBits = ", $s_fixed, "<U6>;
let saturated = Fix::max_value().saturating_to_num::<TooFewIntBits>();
assert_eq!(saturated, TooFewIntBits::max_value());
// 2.5 is 10.1 in binary
let two_point_5 = Fix::from_bits(0b101 << (4 - 1));
assert_eq!(two_point_5.saturating_to_num::<i32>(), 2);
type AllInt = ",
$s_fixed,
"<U0>;
type AllInt = ", $s_fixed, "<U0>;
assert_eq!(",
if_signed_unsigned!(
$Signedness,
concat!("AllInt::from_bits(-1).saturating_to_num::<u", $s_nbits, ">(), 0"),
concat!(
"AllInt::from_bits(-1).saturating_to_num::<u",
$s_nbits,
">(), 0",
),
concat!(
"AllInt::max_value().saturating_to_num::<i",
$s_nbits,
">(), i",
$s_nbits,
"::max_value()",
"AllInt::max_value().saturating_to_num::<i", $s_nbits, ">(), ",
"i", $s_nbits, "::max_value()",
),
),
");
@ -642,55 +588,29 @@ For floating-point numbers, panics if the value is not [finite].
use fixed::{
frac::{U0, U4},
types::I16F16,
",
$s_fixed,
",
", $s_fixed, ",
};
type Fix = ",
$s_fixed,
"<U4>;
type Fix = ", $s_fixed, "<U4>;
// 1.75 is 1.11 in binary
let src = I16F16::from_bits(0b111 << (16 - 2));
assert_eq!(Fix::wrapping_from_num(src), Fix::from_bits(0b111 << (4 - 2)));
// integer 0b1101 << (",
$s_nbits,
" - 7) will wrap to fixed-point 1010...
let too_large = ",
$s_fixed,
"::<U0>::from_bits(0b1101 << (",
$s_nbits,
" - 7));
let wrapped = Fix::from_bits(0b1010 << (",
$s_nbits,
" - 4));
// integer 0b1101 << (", $s_nbits, " - 7) will wrap to fixed-point 1010...
let too_large = ", $s_fixed, "::<U0>::from_bits(0b1101 << (", $s_nbits, " - 7));
let wrapped = Fix::from_bits(0b1010 << (", $s_nbits, " - 4));
assert_eq!(Fix::wrapping_from_num(too_large), wrapped);
// integer 0b1101 << (",
$s_nbits,
" - 7) will wrap to fixed-point 1010...
let large: ",
$s_inner,
" = 0b1101 << (",
$s_nbits,
" - 7);
let wrapped = Fix::from_bits(0b1010 << (",
$s_nbits,
" - 4));
// integer 0b1101 << (", $s_nbits, " - 7) will wrap to fixed-point 1010...
let large: ", $s_inner, " = 0b1101 << (", $s_nbits, " - 7);
let wrapped = Fix::from_bits(0b1010 << (", $s_nbits, " - 4));
assert_eq!(Fix::wrapping_from_num(large), wrapped);
// 1.75 is 1.11 in binary
let expected = Fix::from_bits(0b111 << (4 - 2));
assert_eq!(Fix::wrapping_from_num(1.75f32), expected);
// 1.75 << (",
$s_nbits,
" - 4) wraps to binary 11000...
let large = 1.75 * 2f32.powi(",
$s_nbits,
" - 4);
let wrapped = Fix::from_bits(0b1100 << (",
$s_nbits,
" - 4));
// 1.75 << (", $s_nbits, " - 4) wraps to binary 11000...
let large = 1.75 * 2f32.powi(", $s_nbits, " - 4);
let wrapped = Fix::from_bits(0b1100 << (", $s_nbits, " - 4));
assert_eq!(Fix::wrapping_from_num(large), wrapped);
```
@ -744,45 +664,30 @@ The other number can be:
use fixed::{
frac::{U0, U4, U6},
types::I16F16,
",
$s_fixed,
",
", $s_fixed, ",
};
type Fix = ",
$s_fixed,
"<U4>;
type Fix = ", $s_fixed, "<U4>;
// 1.75 is 1.11 in binary
let src = Fix::from_bits(0b111 << (4 - 2));
let expected = I16F16::from_bits(0b111 << (16 - 2));
assert_eq!(src.wrapping_to_num::<I16F16>(), expected);
type TooFewIntBits = ",
$s_fixed,
"<U6>;
type TooFewIntBits = ", $s_fixed, "<U6>;
let wrapped = TooFewIntBits::from_bits(Fix::max_value().to_bits() << 2);
assert_eq!(Fix::max_value().wrapping_to_num::<TooFewIntBits>(), wrapped);
// 2.5 is 10.1 in binary
let two_point_5 = Fix::from_bits(0b101 << (4 - 1));
assert_eq!(two_point_5.wrapping_to_num::<i32>(), 2);
type AllInt = ",
$s_fixed,
"<U0>;
type AllInt = ", $s_fixed, "<U0>;
assert_eq!(",
if_signed_unsigned!(
$Signedness,
concat!(
"AllInt::from_bits(-1).wrapping_to_num::<u",
$s_nbits,
">(), u",
$s_nbits,
"::max_value()",
),
concat!(
"AllInt::max_value().wrapping_to_num::<i",
$s_nbits,
">(), -1",
"AllInt::from_bits(-1).wrapping_to_num::<u", $s_nbits, ">(), ",
"u", $s_nbits, "::max_value()",
),
concat!("AllInt::max_value().wrapping_to_num::<i", $s_nbits, ">(), -1"),
),
");
@ -846,57 +751,31 @@ For floating-point numbers, panics if the value is not [finite].
use fixed::{
frac::{U0, U4},
types::I16F16,
",
$s_fixed,
",
", $s_fixed, ",
};
type Fix = ",
$s_fixed,
"<U4>;
type Fix = ", $s_fixed, "<U4>;
// 1.75 is 1.11 in binary
let src = I16F16::from_bits(0b111 << (16 - 2));
let expected = Fix::from_bits(0b111 << (4 - 2));
assert_eq!(Fix::overflowing_from_num(src), (expected, false));
// integer 0b1101 << (",
$s_nbits,
" - 7) will wrap to fixed-point 1010...
let too_large = ",
$s_fixed,
"::<U0>::from_bits(0b1101 << (",
$s_nbits,
" - 7));
let wrapped = Fix::from_bits(0b1010 << (",
$s_nbits,
" - 4));
// integer 0b1101 << (", $s_nbits, " - 7) will wrap to fixed-point 1010...
let too_large = ", $s_fixed, "::<U0>::from_bits(0b1101 << (", $s_nbits, " - 7));
let wrapped = Fix::from_bits(0b1010 << (", $s_nbits, " - 4));
assert_eq!(Fix::overflowing_from_num(too_large), (wrapped, true));
assert_eq!(Fix::overflowing_from_num(3), (Fix::from_bits(3 << 4), false));
// integer 0b1101 << (",
$s_nbits,
" - 7) will wrap to fixed-point 1010...
let large: ",
$s_inner,
" = 0b1101 << (",
$s_nbits,
" - 7);
let wrapped = Fix::from_bits(0b1010 << (",
$s_nbits,
" - 4));
// integer 0b1101 << (", $s_nbits, " - 7) will wrap to fixed-point 1010...
let large: ", $s_inner, " = 0b1101 << (", $s_nbits, " - 7);
let wrapped = Fix::from_bits(0b1010 << (", $s_nbits, " - 4));
assert_eq!(Fix::overflowing_from_num(large), (wrapped, true));
// 1.75 is 1.11 in binary
let expected = Fix::from_bits(0b111 << (4 - 2));
assert_eq!(Fix::overflowing_from_num(1.75f32), (expected, false));
// 1.75 << (",
$s_nbits,
" - 4) wraps to binary 11000...
let large = 1.75 * 2f32.powi(",
$s_nbits,
" - 4);
let wrapped = Fix::from_bits(0b1100 << (",
$s_nbits,
" - 4));
// 1.75 << (", $s_nbits, " - 4) wraps to binary 11000...
let large = 1.75 * 2f32.powi(", $s_nbits, " - 4);
let wrapped = Fix::from_bits(0b1100 << (", $s_nbits, " - 4));
assert_eq!(Fix::overflowing_from_num(large), (wrapped, true));
```
@ -954,30 +833,22 @@ The other number can be:
use fixed::{
frac::{U0, U4, U6},
types::I16F16,
",
$s_fixed,
",
", $s_fixed, ",
};
type Fix = ",
$s_fixed,
"<U4>;
type Fix = ", $s_fixed, "<U4>;
// 1.75 is 1.11 in binary
let src = Fix::from_bits(0b111 << (4 - 2));
let expected = I16F16::from_bits(0b111 << (16 - 2));
assert_eq!(src.overflowing_to_num::<I16F16>(), (expected, false));
type TooFewIntBits = ",
$s_fixed,
"<U6>;
type TooFewIntBits = ", $s_fixed, "<U6>;
let wrapped = TooFewIntBits::from_bits(Fix::max_value().to_bits() << 2);
assert_eq!(Fix::max_value().overflowing_to_num::<TooFewIntBits>(), (wrapped, true));
// 2.5 is 10.1 in binary
let two_point_5 = Fix::from_bits(0b101 << (4 - 1));
assert_eq!(two_point_5.overflowing_to_num::<i32>(), (2, false));
let does_not_fit = ",
$s_fixed,
"::<U0>::",
let does_not_fit = ", $s_fixed, "::<U0>::",
if_signed_unsigned!($Signedness, "from_bits(-1)", "max_value()"),
";
let wrapped = ",
@ -989,8 +860,7 @@ let wrapped = ",
";
assert_eq!(does_not_fit.overflowing_to_num::<",
if_signed_unsigned!($Signedness, "u", "i"),
$s_nbits,
">(), (wrapped, true));
$s_nbits, ">(), (wrapped, true));
// 1.625 is 1.101 in binary
let one_point_625 = Fix::from_bits(0b1101 << (4 - 3));
@ -1030,12 +900,8 @@ assert_eq!(one_point_625.overflowing_to_num::<f32>(), (1.625f32, false));
# Examples
```rust
use fixed::{frac::U4, ",
$s_fixed,
"};
type Fix = ",
$s_fixed,
"<U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
// 1.75 is 1.11 in binary
let f = Fix::from_str_binary(\"1.11\");
let check = Fix::from_bits(0b111 << (4 - 2));
@ -1061,12 +927,8 @@ assert_eq!(neg, Ok(-check));
# Examples
```rust
use fixed::{frac::U4, ",
$s_fixed,
"};
type Fix = ",
$s_fixed,
"<U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
// 1.75 is 1.11 in binary, 1.6 in octal
let f = Fix::from_str_octal(\"1.6\");
let check = Fix::from_bits(0b111 << (4 - 2));
@ -1092,12 +954,8 @@ assert_eq!(neg, Ok(-check));
# Examples
```rust
use fixed::{frac::U4, ",
$s_fixed,
"};
type Fix = ",
$s_fixed,
"<U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
// 1.75 is 1.11 in binary, 1.C in hexadecimal
let f = Fix::from_str_hex(\"1.C\");
let check = Fix::from_bits(0b111 << (4 - 2));

166
src/macros_round.rs
View File

@ -24,20 +24,15 @@ macro_rules! fixed_round {
"Note that since the numbers are stored in two’s
complement, negative numbers with non-zero fractional parts will be
rounded towards −∞, except in the case where there are no integer
bits, that is `",
$s_fixed,
"<U",
$s_nbits,
">`, where the return value is always zero.
bits, that is `", $s_fixed, "<U", $s_nbits, ">`, where the return value is always zero.
",
),
"# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
// 0010.0000
let two = Fix::from_num(2);
// 0010.0100
@ -68,11 +63,8 @@ assert_eq!((-two_and_quarter).int(), -three);
$Signedness,
"Note that since the numbers are stored in two’s
complement, the returned fraction will be non-negative for negative
numbers, except in the case where there are no integer bits, that is `",
$s_fixed,
"<U",
$s_nbits,
">` where the return value is always equal to
numbers, except in the case where there are no integer bits, that is
`", $s_fixed, "<U", $s_nbits, ">` where the return value is always equal to
`self`.
",
@ -80,9 +72,8 @@ numbers, except in the case where there are no integer bits, that is `",
"# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
// 0000.0100
let quarter = Fix::from_num(1) / 4;
// 0010.0100
@ -118,9 +109,8 @@ it panics; if wrapping is required use [`wrapping_ceil`] instead.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
let two_half = Fix::from_num(5) / 2;
assert_eq!(two_half.ceil(), Fix::from_num(3));
",
@ -162,9 +152,8 @@ Overflow can only occur when there are zero integer bits.
"# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
let two_half = Fix::from_num(5) / 2;
assert_eq!(two_half.floor(), Fix::from_num(2));
",
@ -200,9 +189,8 @@ it panics; if wrapping is required use [`wrapping_round`] instead.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
r"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, r"<U4>;
let two_half = Fix::from_num(5) / 2;
assert_eq!(two_half.round(), Fix::from_num(3));
",
@ -231,9 +219,8 @@ returning [`None`] on overflow.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
let two_half = Fix::from_num(5) / 2;
assert_eq!(two_half.checked_ceil(), Some(Fix::from_num(3)));
",
@ -268,20 +255,26 @@ Overflow can only occur when there are zero integer bits.",
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{",
if_signed_unsigned!(
$Signedness,
concat!(
"
frac::{U4, U", $s_nbits, "},
", $s_fixed, ",
",
),
concat!("frac::U4, ", $s_fixed),
),
"};
type Fix = ", $s_fixed, "<U4>;
let two_half = Fix::from_num(5) / 2;
assert_eq!(two_half.checked_floor(), Some(Fix::from_num(2)));
",
if_signed_else_empty_str!(
$Signedness,
"assert_eq!((-two_half).checked_floor(), Some(Fix::from_num(-3)));
type AllFrac = fixed::",
$s_fixed,
"<fixed::frac::U",
$s_nbits,
">;
type AllFrac = ", $s_fixed, "<U", $s_nbits, ">;
assert!(AllFrac::min_value().checked_floor().is_none());
",
),
@ -310,9 +303,8 @@ rounded away from zero, returning [`None`] on overflow.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
let two_half = Fix::from_num(5) / 2;
assert_eq!(two_half.checked_round(), Some(Fix::from_num(3)));
",
@ -340,9 +332,8 @@ saturating on overflow.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
let two_half = Fix::from_num(5) / 2;
assert_eq!(two_half.saturating_ceil(), Fix::from_num(3));
",
@ -375,20 +366,26 @@ Overflow can only occur when there are zero integer bits.",
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{",
if_signed_unsigned!(
$Signedness,
concat!(
"
frac::{U4, U", $s_nbits, "},
", $s_fixed, ",
",
),
concat!("frac::U4, ", $s_fixed),
),
"};
type Fix = ", $s_fixed, "<U4>;
let two_half = Fix::from_num(5) / 2;
assert_eq!(two_half.saturating_floor(), Fix::from_num(2));
",
if_signed_else_empty_str!(
$Signedness,
"assert_eq!((-two_half).saturating_floor(), Fix::from_num(-3));
type AllFrac = fixed::",
$s_fixed,
"<fixed::frac::U",
$s_nbits,
">;
type AllFrac = ", $s_fixed, "<U", $s_nbits, ">;
assert_eq!(AllFrac::min_value().saturating_floor(), AllFrac::min_value());
",
),
@ -408,9 +405,8 @@ ties rounded away from zero, and saturating on overflow.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
let two_half = Fix::from_num(5) / 2;
assert_eq!(two_half.saturating_round(), Fix::from_num(3));
",
@ -441,9 +437,8 @@ wrapping on overflow.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
let two_half = Fix::from_num(5) / 2;
assert_eq!(two_half.wrapping_ceil(), Fix::from_num(3));
",
@ -475,20 +470,26 @@ Overflow can only occur when there are zero integer bits.",
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{",
if_signed_unsigned!(
$Signedness,
concat!(
"
frac::{U4, U", $s_nbits, "},
", $s_fixed, ",
",
),
concat!("frac::U4, ", $s_fixed),
),
"};
type Fix = ", $s_fixed, "<U4>;
let two_half = Fix::from_num(5) / 2;
assert_eq!(two_half.wrapping_floor(), Fix::from_num(2));
",
if_signed_else_empty_str!(
$Signedness,
"assert_eq!((-two_half).wrapping_floor(), Fix::from_num(-3));
type AllFrac = fixed::",
$s_fixed,
"<fixed::frac::U",
$s_nbits,
">;
type AllFrac = ", $s_fixed, "<U", $s_nbits, ">;
assert_eq!(AllFrac::min_value().wrapping_floor(), AllFrac::from_num(0));
",
),
@ -507,9 +508,8 @@ nearest, with ties rounded away from zero, and wrapping on overflow.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
let two_half = Fix::from_num(5) / 2;
assert_eq!(two_half.wrapping_round(), Fix::from_num(3));
",
@ -537,9 +537,8 @@ returned.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
let two_half = Fix::from_num(5) / 2;
assert_eq!(two_half.overflowing_ceil(), (Fix::from_num(3), false));
",
@ -591,20 +590,26 @@ occur when there are zero integer bits.",
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{",
if_signed_unsigned!(
$Signedness,
concat!(
"
frac::{U4, U", $s_nbits, "},
", $s_fixed, ",
",
),
concat!("frac::U4, ", $s_fixed),
),
"};
type Fix = ", $s_fixed, "<U4>;
let two_half = Fix::from_num(5) / 2;
assert_eq!(two_half.overflowing_floor(), (Fix::from_num(2), false));
",
if_signed_else_empty_str!(
$Signedness,
"assert_eq!((-two_half).overflowing_floor(), (Fix::from_num(-3), false));
type AllFrac = fixed::",
$s_fixed,
"<fixed::frac::U",
$s_nbits,
">;
type AllFrac = ", $s_fixed, "<U", $s_nbits, ">;
assert_eq!(AllFrac::min_value().overflowing_floor(), (AllFrac::from_num(0), true));
",
),
@ -637,9 +642,8 @@ returned.
# Examples
```rust
type Fix = fixed::",
$s_fixed,
"<fixed::frac::U4>;
use fixed::{frac::U4, ", $s_fixed, "};
type Fix = ", $s_fixed, "<U4>;
let two_half = Fix::from_num(5) / 2;
assert_eq!(two_half.overflowing_round(), (Fix::from_num(3), false));
",

49
src/wrapping.rs
View File

@ -37,11 +37,10 @@ use core::{
/// # Examples
///
/// ```rust
/// use fixed::Wrapping;
/// type Fix = fixed::types::I16F16;
/// let max = Wrapping(Fix::max_value());
/// let delta = Wrapping(Fix::from_bits(1));
/// assert_eq!(Fix::min_value(), (max + delta).0);
/// use fixed::{types::I16F16, Wrapping};
/// let max = Wrapping(I16F16::max_value());
/// let delta = Wrapping(I16F16::from_bits(1));
/// assert_eq!(I16F16::min_value(), (max + delta).0);
/// ```
#[repr(transparent)]
#[derive(Clone, Copy, Default, Hash, Debug, Eq, PartialEq, Ord, PartialOrd)]
@ -122,11 +121,10 @@ impl<F: Fixed> Wrapping<F> {
/// # Examples
///
/// ```rust
/// use fixed::Wrapping;
/// type Fix = fixed::types::I16F16;
/// let two_half = Wrapping(Fix::from_num(5) / 2);
/// assert_eq!(two_half.ceil(), Wrapping(Fix::from_num(3)));
/// assert_eq!(Wrapping(Fix::max_value()).ceil(), Wrapping(Fix::min_value()));
/// use fixed::{types::I16F16, Wrapping};
/// let two_half = Wrapping(I16F16::from_num(5) / 2);
/// assert_eq!(two_half.ceil(), Wrapping(I16F16::from_num(3)));
/// assert_eq!(Wrapping(I16F16::max_value()).ceil(), Wrapping(I16F16::min_value()));
/// ```
pub fn ceil(self) -> Wrapping<F> {
Wrapping(self.0.wrapping_ceil())
@ -141,12 +139,13 @@ impl<F: Fixed> Wrapping<F> {
/// # Examples
///
/// ```rust
/// use fixed::Wrapping;
/// type Fix = fixed::types::I16F16;
/// let two_half = Wrapping(Fix::from_num(5) / 2);
/// assert_eq!(two_half.floor(), Wrapping(Fix::from_num(2)));
/// type AllFrac = fixed::types::I0F32;
/// assert_eq!(Wrapping(AllFrac::min_value()).floor(), Wrapping(AllFrac::from_num(0)));
/// use fixed::{
/// types::{I0F32, I16F16},
/// Wrapping,
/// };
/// let two_half = Wrapping(I16F16::from_num(5) / 2);
/// assert_eq!(two_half.floor(), Wrapping(I16F16::from_num(2)));
/// assert_eq!(Wrapping(I0F32::min_value()).floor(), Wrapping(I0F32::from_num(0)));
/// ```
pub fn floor(self) -> Wrapping<F> {
Wrapping(self.0.wrapping_floor())
@ -158,12 +157,11 @@ impl<F: Fixed> Wrapping<F> {
/// # Examples
///
/// ```rust
/// use fixed::Wrapping;
/// type Fix = fixed::types::I16F16;
/// let two_half = Wrapping(Fix::from_num(5) / 2);
/// assert_eq!(two_half.round(), Wrapping(Fix::from_num(3)));
/// assert_eq!((-two_half).round(), Wrapping(Fix::from_num(-3)));
/// assert_eq!(Wrapping(Fix::max_value()).round(), Wrapping(Fix::min_value()));
/// use fixed::{types::I16F16, Wrapping};
/// let two_half = Wrapping(I16F16::from_num(5) / 2);
/// assert_eq!(two_half.round(), Wrapping(I16F16::from_num(3)));
/// assert_eq!((-two_half).round(), Wrapping(I16F16::from_num(-3)));
/// assert_eq!(Wrapping(I16F16::max_value()).round(), Wrapping(I16F16::min_value()));
/// ```
pub fn round(self) -> Wrapping<F> {
Wrapping(self.0.wrapping_round())
@ -178,10 +176,9 @@ impl<F: Fixed> Wrapping<F> {
/// # Examples
///
/// ```rust
/// use fixed::Wrapping;
/// type Fix = fixed::types::I16F16;
/// assert_eq!(Wrapping(Fix::from_num(-5)).abs(), Wrapping(Fix::from_num(5)));
/// assert_eq!(Wrapping(Fix::min_value()).abs(), Wrapping(Fix::min_value()));
/// use fixed::{types::I16F16, Wrapping};
/// assert_eq!(Wrapping(I16F16::from_num(-5)).abs(), Wrapping(I16F16::from_num(5)));
/// assert_eq!(Wrapping(I16F16::min_value()).abs(), Wrapping(I16F16::min_value()));
/// ```
pub fn abs(self) -> Wrapping<F>
where