add wrapping_next_power_of_two

README.md

@@ -86,6 +86,9 @@ The conversions supported cover the following cases.
     [`Fixed`][tf-0-5-7] trait, and to the [`Wrapping`][wr-0-5-7]
     wrapper:
       * [`leading_ones`][f-lo-0-5-7], [`trailing_ones`][f-to-0-5-7]
+  * The following method was added to unsigned fixed-point types and
+    to the [`FixedUnsigned`][tfu-0-5-7] trait:
+      * [`wrapping_next_power_of_two`][f-wnpot-0-5-7]
   * The [`PHI`][phi-0-5-7] and [`FRAC_1_PHI`][f1phi-0-5-7] constants
     were added to the [`consts`][cons-0-5-7] module and as
     [associated constants][f-phi-0-5-7] for fixed-point types.
@@ -94,11 +97,13 @@ The conversions supported cover the following cases.
 [f-lo-0-5-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.leading_ones
 [f-phi-0-5-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#associatedconstant.PHI
 [f-to-0-5-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.trailing_ones
+[f-wnpot-0-5-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedU32.html#method.wrapping_next_power_of_two
 [f1phi-0-5-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/consts/constant.FRAC_1_PHI.html
 [ltf-0-5-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/traits/trait.LosslessTryFrom.html
 [lti-0-5-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/traits/trait.LosslessTryInto.html
 [phi-0-5-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/consts/constant.PHI.html
 [tf-0-5-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/traits/trait.Fixed.html
+[tfu-0-5-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/traits/trait.FixedUnsigned.html
 [wr-0-5-7]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.Wrapping.html
 
 ### Version 0.5.6 news (2020-05-01)

RELEASES.md

@@ -12,6 +12,9 @@ Version 0.5.7 (unreleased)
   * The following methods were added to all fixed-point types, to the
     `Fixed` trait, and to the `Wrapping` wrapper:
       * `leading_ones`, `trailing_ones`
+  * The following method was added to unsigned fixed-point types and
+    to the `FixedUnsigned` trait:
+      * `wrapping_next_power_of_two`
   * The `PHI` and `FRAC_1_PHI` constants were added to the `consts`
     module and as associated constants for fixed-point types.
 

src/macros_no_frac.rs

@@ -1206,6 +1206,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, "<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.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<Frac> {
+                        self.checked_next_power_of_two().unwrap_or(Self::from_bits(0))
+                    }
+                }
+            }
+
             comment! {
                 "Overflowing negation.
 

src/traits.rs

@@ -1213,6 +1213,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<Self>;
+
+    /// 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.
@@ -2233,6 +2237,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<Self> }
+                trait_delegate! { fn wrapping_next_power_of_two(self) -> Self }
             }
         }
     };

src/wrapping.rs

@@ -468,8 +468,8 @@ impl<F: Fixed> Wrapping<F> {
     /// # 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<F: Fixed> Wrapping<F> {
     /// # 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]
@@ -808,7 +808,7 @@ impl<F: FixedUnsigned> Wrapping<F> {
     /// ```
     #[inline]
     pub fn next_power_of_two(self) -> Wrapping<F> {
-        Wrapping(self.0.checked_next_power_of_two().unwrap_or_default())
+        Wrapping(self.0.wrapping_next_power_of_two())
     }
 }