add wrapping_next_power_of_two

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)

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)

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, "<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

@@ -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<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.
@@ -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<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]
@@ -780,7 +780,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())
     }
 }