add to_fixed

README.md

@@ -39,6 +39,12 @@ numeric primitives are implemented. That is, you can use [`From`] or
 
 ## What’s new
 
+### Version 0.2.2 news (unreleased)
+
+  * The new method [`to_fixed`] was added.
+
+[`to_fixed`]: https://docs.rs/fixed/0.2.2/fixed/struct.FixedI32.html#method.to_fixed
+
 ### Version 0.2.1 news (2019-01-29)
 
   * Bug fix: the [`from_fixed`] and [`from_int`] methods (and their

RELEASES.md

@@ -5,6 +5,11 @@ modification, are permitted in any medium without royalty provided the
 copyright notice and this notice are preserved. This file is offered
 as-is, without any warranty. -->
 
+Version 0.2.2 (unreleased)
+==========================
+
+  * The new method `to_fixed` was added.
+
 Version 0.2.1 (2019-01-29)
 ==========================
 

src/lib.rs

@@ -903,6 +903,65 @@ assert_eq!(Fix::overflowing_from_fixed(large), (wrapped, true));
                 }
             );
 
+            doc_comment!(
+                concat!(
+                    "
+Converts this fixed-point number to another fixed-point number.
+
+This method behaves like [`from_fixed`], similar to how [`Into`]
+behaves like [`From`].
+
+The source value does not need to have the same fixed-point type as
+the destination value.
+
+This method truncates the extra fractional bits in the source value.
+For example, if the source type has 24 fractional bits and the
+destination type has 10 fractional bits, then 14 fractional bits will
+be truncated.
+
+# Panics
+
+If the value is too large to fit, the method panics in debug mode. In
+release mode, the method may either panic or wrap the value, with the
+current implementation wrapping the value. It is not considered a
+breaking change if in the future the method panics even in release
+mode; if wrapping is the required behavior use [`wrapping_from_fixed`]
+instead.
+
+# Examples
+
+```rust
+use fixed::frac;
+type Fix = fixed::",
+                    stringify!($Fixed),
+                    "<frac::U4>;
+type Dst = fixed::FixedI32<frac::U16>;
+// 1.75 is 1.1100, that is Fix::from_bits(0b111<< (4 - 2))
+// or Dst::from_bits(0b111 << (16 - 2))
+let src = Fix::from_bits(0b111 << (4 - 2));
+let expected = Dst::from_bits(0b111 << (16 - 2));
+let dst: Dst = src.to_fixed();
+assert_eq!(dst, expected);",
+                    if_signed_else_empty_str!(
+                        $Signedness,
+                        "
+assert_eq!((-src).to_fixed::<Dst>(), -expected);",
+                    ),
+                    "
+```
+
+[`From`]: https://doc.rust-lang.org/nightly/std/convert/trait.From.html
+[`Into`]: https://doc.rust-lang.org/nightly/std/convert/trait.Into.html
+[`from_fixed`]: #method.from_fixed
+[`wrapping_from_fixed`]: #method.wrapping_from_fixed
+",
+                ),
+                #[inline]
+                pub fn to_fixed<F>(self) -> F where F: Fixed {
+                    F::from_fixed(self)
+                }
+            );
+
             doc_comment!(
                 concat!(
                     "

src/sealed_fixed.rs

@@ -15,7 +15,7 @@
 
 use core::fmt::{Debug, Display};
 use frac::{IsLessOrEqual, True, Unsigned, U128, U16, U32, U64, U8};
-use sealed::SealedInt;
+use sealed::{Fixed, SealedInt};
 use {
     FixedI128, FixedI16, FixedI32, FixedI64, FixedI8, FixedU128, FixedU16, FixedU32, FixedU64,
     FixedU8,
@@ -37,6 +37,10 @@ pub trait SealedFixed: Copy + Debug + Display {
         Self::Bits::nbits() - Self::frac_bits()
     }
 
+    fn from_fixed<F>(fixed: F) -> Self
+    where
+        F: Fixed;
+
     #[inline]
     fn one() -> Option<Self> {
         let min_int_bits = if Self::Bits::is_signed() { 2 } else { 1 };
@@ -88,6 +92,14 @@ macro_rules! sealed_fixed {
                 Frac::to_u32()
             }
 
+            #[inline]
+            fn from_fixed<F>(fixed: F) -> Self
+            where
+                F: Fixed,
+            {
+                $Fixed::from_fixed(fixed)
+            }
+
             #[inline]
             fn frac_mask() -> Self::Bits {
                 !Self::int_mask()