feat/checked-convert

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "hylo-fix"
-version = "0.5.1"
+version = "0.5.2"
 edition = "2021"
 description = "Fixed-point number types with Solana Anchor support"
 authors = ["0xPlish <plish@hylo.so>", "Curtis McEnroe <programble@gmail.com>"]

flake.nix

@@ -3,7 +3,7 @@
 
   inputs = {
     nixpkgs.url      = "github:NixOS/nixpkgs/25.11";
-    rust-overlay.url = "github:oxalica/rust-overlay/bc00300f010275e46feb3c3974df6587ff7b7808";
+    rust-overlay.url = "github:oxalica/rust-overlay/2859683cd9ef7858d324c5399b0d8d6652bf4044";
     flake-parts.url  = "github:hercules-ci/flake-parts";
   };
 
@@ -25,7 +25,7 @@
           buildInputs = [
             openssl
             pkg-config
-            (rust-bin.stable."1.86.0".default.override {
+            (rust-bin.stable."1.88.0".default.override {
               extensions = [ "rust-analyzer" "rust-src" ];
             })
           ];

src/lib.rs

@@ -925,4 +925,39 @@ mod tests {
         assert_eq!(Micro::<u64>::one().bits, 1_000_000);
         assert_eq!(Nano::<u64>::one().bits, 1_000_000_000);
     }
+
+    #[test]
+    fn checked_convert_upconvert() {
+        assert_eq!(
+            Milli::new(5u64).checked_convert(),
+            Some(Micro::new(5_000u64)),
+        );
+    }
+
+    #[test]
+    fn checked_convert_downconvert() {
+        assert_eq!(
+            Micro::new(5_000u64).checked_convert(),
+            Some(Milli::new(5u64)),
+        );
+    }
+
+    #[test]
+    fn checked_convert_identity() {
+        assert_eq!(Milli::new(42u64).checked_convert(), Some(Milli::new(42u64)),);
+    }
+
+    #[test]
+    fn checked_convert_overflow() {
+        assert_eq!(Milli::new(u64::MAX).checked_convert::<typenum::N9>(), None,);
+    }
+
+    #[test]
+    fn checked_convert_matches_convert() {
+        let value = Milli::new(15u64);
+        assert_eq!(
+            value.checked_convert::<typenum::N6>(),
+            Some(value.convert::<typenum::N6>()),
+        );
+    }
 }

src/util.rs

@@ -1,3 +1,4 @@
+use crate::muldiv::MulDiv;
 use crate::typenum::consts::Z0;
 use crate::typenum::{Integer, IsLess, B1, U10};
 use crate::{Fix, FromUnsigned, Pow};
@@ -18,3 +19,26 @@ where
         Fix::new(base.pow(Exp::to_i32().unsigned_abs()))
     }
 }
+
+impl<Bits, Exp> Fix<Bits, U10, Exp>
+where
+    Self: FixExt,
+    Bits: MulDiv<Output = Bits>,
+{
+    /// Converts to another _Exp_, returning `None` on overflow.
+    ///
+    /// ```
+    /// use fix::prelude::*;
+    /// let source = UFix64::<N3>::new(5u64);
+    /// let target = source.checked_convert::<N6>();
+    /// assert_eq!(target, Some(UFix64::<N6>::new(5_000u64)));
+    /// ```
+    pub fn checked_convert<ToExp>(self) -> Option<Fix<Bits, U10, ToExp>>
+    where
+        Fix<Bits, U10, ToExp>: FixExt,
+    {
+        let target_one = Fix::<Bits, U10, ToExp>::one();
+        let source_one = Self::one();
+        target_one.mul_div_floor(self, source_one)
+    }
+}