diff --git a/README.md b/README.md index dc6a011..87b4136 100644 --- a/README.md +++ b/README.md @@ -86,6 +86,9 @@ The conversions supported cover the following cases. * The following methods were added to all fixed-point types, to the [`Fixed`][tf-1-0] trait, and to the [`Wrapping`][wr-1-0] wrapper: * [`leading_ones`][f-lo-1-0], [`trailing_ones`][f-to-1-0] + * The following method was added to unsigned fixed-point types and + to the [`FixedUnsigned`][tfu-1-0] trait: + * [`wrapping_next_power_of_two`][f-wnpot-1-0] * The [`PHI`][phi-1-0] and [`FRAC_1_PHI`][f1phi-1-0] constants were added to the [`consts`][cons-1-0] module and as [associated constants][f-phi-1-0] for fixed-point types. @@ -95,11 +98,13 @@ The conversions supported cover the following cases. [f-lo-1-0]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.leading_ones [f-phi-1-0]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#associatedconstant.PHI [f-to-1-0]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.trailing_ones +[f-wnpot-1-0]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedU32.html#method.wrapping_next_power_of_two [f1phi-1-0]: https://tspiteri.gitlab.io/fixed/dev/fixed/consts/constant.FRAC_1_PHI.html [ltf-1-0]: https://tspiteri.gitlab.io/fixed/dev/fixed/traits/trait.LosslessTryFrom.html [lti-1-0]: https://tspiteri.gitlab.io/fixed/dev/fixed/traits/trait.LosslessTryInto.html [phi-1-0]: https://tspiteri.gitlab.io/fixed/dev/fixed/consts/constant.PHI.html [tf-1-0]: https://tspiteri.gitlab.io/fixed/dev/fixed/traits/trait.Fixed.html +[tfu-1-0]: https://tspiteri.gitlab.io/fixed/dev/fixed/traits/trait.FixedUnsigned.html [wr-1-0]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.Wrapping.html ### Version 0.5.6 news (2020-05-01) diff --git a/RELEASES.md b/RELEASES.md index 8c6a3ee..23aa689 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -14,6 +14,9 @@ Version 1.0.0 (unreleased) * The following methods were added to all fixed-point types, to the [`Fixed`][tf-1-0] trait, and to the [`Wrapping`][wr-1-0] wrapper: * [`leading_ones`][f-lo-1-0], [`trailing_ones`][f-to-1-0] + * The following method was added to unsigned fixed-point types and + to the [`FixedUnsigned`][tfu-1-0] trait: + * [`wrapping_next_power_of_two`][f-wnpot-1-0] * The [`PHI`][phi-1-0] and [`FRAC_1_PHI`][f1phi-1-0] constants were added to the [`consts`][cons-1-0] module and as [associated constants][f-phi-1-0] for fixed-point types. @@ -23,11 +26,13 @@ Version 1.0.0 (unreleased) [f-lo-1-0]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.leading_ones [f-phi-1-0]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#associatedconstant.PHI [f-to-1-0]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.trailing_ones +[f-wnpot-1-0]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedU32.html#method.wrapping_next_power_of_two [f1phi-1-0]: https://tspiteri.gitlab.io/fixed/dev/fixed/consts/constant.FRAC_1_PHI.html [ltf-1-0]: https://tspiteri.gitlab.io/fixed/dev/fixed/traits/trait.LosslessTryFrom.html [lti-1-0]: https://tspiteri.gitlab.io/fixed/dev/fixed/traits/trait.LosslessTryInto.html [phi-1-0]: https://tspiteri.gitlab.io/fixed/dev/fixed/consts/constant.PHI.html [tf-1-0]: https://tspiteri.gitlab.io/fixed/dev/fixed/traits/trait.Fixed.html +[tfu-1-0]: https://tspiteri.gitlab.io/fixed/dev/fixed/traits/trait.FixedUnsigned.html [wr-1-0]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.Wrapping.html Version 0.5.6 (2020-05-01) diff --git a/src/macros_no_frac.rs b/src/macros_no_frac.rs index 07301c0..7a18ab5 100644 --- a/src/macros_no_frac.rs +++ b/src/macros_no_frac.rs @@ -1202,6 +1202,32 @@ assert_eq!(Fix::MIN.wrapping_abs(), Fix::MIN); } } + if_unsigned! { + $Signedness; + comment! { + "Returns the smallest power of two that is ≥ `self`, +wrapping to 0 if the next power of two is too large to represent. + +# 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.wrapping_next_power_of_two(), half); +assert_eq!(Fix::MAX.wrapping_next_power_of_two(), 0); +``` +"; + #[inline] + pub fn wrapping_next_power_of_two(self) -> $Fixed { + self.checked_next_power_of_two().unwrap_or(Self::from_bits(0)) + } + } + } + comment! { "Overflowing negation. diff --git a/src/traits.rs b/src/traits.rs index 253e20a..8c303fc 100644 --- a/src/traits.rs +++ b/src/traits.rs @@ -1157,6 +1157,10 @@ pub trait FixedUnsigned: Fixed { /// /// [`None`]: https://doc.rust-lang.org/nightly/core/option/enum.Option.html#variant.None fn checked_next_power_of_two(self) -> Option; + + /// 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; } /// This trait provides lossless conversions that might be fallible. @@ -2176,6 +2180,7 @@ macro_rules! impl_fixed { trait_delegate! { fn is_power_of_two(self) -> bool } 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 } } } }; diff --git a/src/wrapping.rs b/src/wrapping.rs index 8d65a07..f03db83 100644 --- a/src/wrapping.rs +++ b/src/wrapping.rs @@ -468,8 +468,8 @@ impl Wrapping { /// # Examples /// /// ```rust - /// use fixed::{types::I16F16, Wrapping}; - /// let w = Wrapping(I16F16::from_bits(0xFF00_00FF)); + /// use fixed::{types::U16F16, Wrapping}; + /// let w = Wrapping(U16F16::from_bits(0xFF00_00FF)); /// assert_eq!(w.leading_ones(), w.0.leading_ones()); /// ``` #[inline] @@ -496,8 +496,8 @@ impl Wrapping { /// # Examples /// /// ```rust - /// use fixed::{types::I16F16, Wrapping}; - /// let w = Wrapping(I16F16::from_bits(0xFF00_00FF)); + /// use fixed::{types::U16F16, Wrapping}; + /// let w = Wrapping(U16F16::from_bits(0xFF00_00FF)); /// assert_eq!(w.trailing_ones(), w.0.trailing_ones()); /// ``` #[inline] @@ -780,7 +780,7 @@ impl Wrapping { /// ``` #[inline] pub fn next_power_of_two(self) -> Wrapping { - Wrapping(self.0.checked_next_power_of_two().unwrap_or_default()) + Wrapping(self.0.wrapping_next_power_of_two()) } }