feat: OverflowingSub trait

corelib/src/integer.cairo

@@ -2856,3 +2856,105 @@ impl I128OverflowingAdd of core::num::traits::OverflowingAdd<i128> {
         }
     }
 }
+
+// OverflowingSub implementations
+impl U8OverflowingSub of core::num::traits::OverflowingSub<u8> {
+    fn overflowing_sub(self: u8, v: u8) -> (u8, bool) {
+        match u8_overflowing_sub(self, v) {
+            Result::Ok(x) => (x, false),
+            Result::Err(x) => (x, true)
+        }
+    }
+}
+
+impl U16OverflowingSub of core::num::traits::OverflowingSub<u16> {
+    fn overflowing_sub(self: u16, v: u16) -> (u16, bool) {
+        match u16_overflowing_sub(self, v) {
+            Result::Ok(x) => (x, false),
+            Result::Err(x) => (x, true)
+        }
+    }
+}
+
+impl U32OverflowingSub of core::num::traits::OverflowingSub<u32> {
+    fn overflowing_sub(self: u32, v: u32) -> (u32, bool) {
+        match u32_overflowing_sub(self, v) {
+            Result::Ok(x) => (x, false),
+            Result::Err(x) => (x, true)
+        }
+    }
+}
+
+impl U64OverflowingSub of core::num::traits::OverflowingSub<u64> {
+    fn overflowing_sub(self: u64, v: u64) -> (u64, bool) {
+        match u64_overflowing_sub(self, v) {
+            Result::Ok(x) => (x, false),
+            Result::Err(x) => (x, true)
+        }
+    }
+}
+
+impl U128OverflowingSub of core::num::traits::OverflowingSub<u128> {
+    fn overflowing_sub(self: u128, v: u128) -> (u128, bool) {
+        match u128_overflowing_sub(self, v) {
+            Result::Ok(x) => (x, false),
+            Result::Err(x) => (x, true)
+        }
+    }
+}
+
+impl U256OverflowingSub of core::num::traits::OverflowingSub<u256> {
+    fn overflowing_sub(self: u256, v: u256) -> (u256, bool) {
+        u256_overflow_sub(self, v)
+    }
+}
+
+impl I8OverflowingSub of core::num::traits::OverflowingSub<i8> {
+    fn overflowing_sub(self: i8, v: i8) -> (i8, bool) {
+        match i8_overflowing_sub_impl(self, v) {
+            SignedIntegerResult::InRange(x) => (x, false),
+            SignedIntegerResult::Underflow(x) => (x, true),
+            SignedIntegerResult::Overflow(x) => (x, true),
+        }
+    }
+}
+
+impl I16OverflowingSub of core::num::traits::OverflowingSub<i16> {
+    fn overflowing_sub(self: i16, v: i16) -> (i16, bool) {
+        match i16_overflowing_sub_impl(self, v) {
+            SignedIntegerResult::InRange(x) => (x, false),
+            SignedIntegerResult::Underflow(x) => (x, true),
+            SignedIntegerResult::Overflow(x) => (x, true),
+        }
+    }
+}
+
+impl I32OverflowingSub of core::num::traits::OverflowingSub<i32> {
+    fn overflowing_sub(self: i32, v: i32) -> (i32, bool) {
+        match i32_overflowing_sub_impl(self, v) {
+            SignedIntegerResult::InRange(x) => (x, false),
+            SignedIntegerResult::Underflow(x) => (x, true),
+            SignedIntegerResult::Overflow(x) => (x, true),
+        }
+    }
+}
+
+impl I64OverflowingSub of core::num::traits::OverflowingSub<i64> {
+    fn overflowing_sub(self: i64, v: i64) -> (i64, bool) {
+        match i64_overflowing_sub_impl(self, v) {
+            SignedIntegerResult::InRange(x) => (x, false),
+            SignedIntegerResult::Underflow(x) => (x, true),
+            SignedIntegerResult::Overflow(x) => (x, true),
+        }
+    }
+}
+
+impl I128OverflowingSub of core::num::traits::OverflowingSub<i128> {
+    fn overflowing_sub(self: i128, v: i128) -> (i128, bool) {
+        match i128_overflowing_sub_impl(self, v) {
+            SignedIntegerResult::InRange(x) => (x, false),
+            SignedIntegerResult::Underflow(x) => (x, true),
+            SignedIntegerResult::Overflow(x) => (x, true),
+        }
+    }
+}

corelib/src/num/traits.cairo

@@ -8,4 +8,4 @@ pub mod bit_size;
 pub use bit_size::BitSize;
 
 pub mod ops;
-pub use ops::{OverflowingAdd};
+pub use ops::{OverflowingAdd, OverflowingSub};

corelib/src/num/traits/ops.cairo

@@ -1,2 +1,2 @@
 pub mod overflowing;
-pub use overflowing::{OverflowingAdd};
+pub use overflowing::{OverflowingAdd, OverflowingSub};

corelib/src/num/traits/ops/overflowing.cairo

@@ -5,3 +5,11 @@ pub trait OverflowingAdd<T> {
     /// If an overflow would have occurred then the wrapped value is returned.
     fn overflowing_add(self: T, v: T) -> (T, bool);
 }
+
+/// Performs subtraction with a flag for overflow.
+pub trait OverflowingSub<T> {
+    /// Returns a tuple of the difference along with a boolean indicating whether an arithmetic
+    /// overflow would occur.
+    /// If an overflow would have occurred then the wrapped value is returned.
+    fn overflowing_sub(self: T, v: T) -> (T, bool);
+}

corelib/src/test/num_test.cairo

@@ -1,5 +1,5 @@
 use core::num::traits::BitSize;
-use core::num::traits::OverflowingAdd;
+use core::num::traits::{OverflowingAdd, OverflowingSub};
 use core::integer::BoundedInt;
 
 
@@ -66,3 +66,46 @@ fn test_overflowing_add_negative_signed_integers() {
         BoundedInt::<i128>::min().overflowing_add(-1) == (0x7fffffffffffffffffffffffffffffff, true)
     );
 }
+
+fn test_overflowing_sub_unsigned_integers() {
+    assert_eq!(3_u8.overflowing_sub(2), (1, false));
+    assert_eq!(0_u8.overflowing_sub(1), (BoundedInt::<u8>::max(), true));
+    assert_eq!(3_u16.overflowing_sub(2), (1, false));
+    assert_eq!(0_u16.overflowing_sub(1), (BoundedInt::<u16>::max(), true));
+    assert_eq!(3_u32.overflowing_sub(2), (1, false));
+    assert_eq!(0_u32.overflowing_sub(1), (BoundedInt::<u32>::max(), true));
+    assert_eq!(3_u64.overflowing_sub(2), (1, false));
+    assert_eq!(0_u64.overflowing_sub(1), (BoundedInt::<u64>::max(), true));
+    assert_eq!(3_u128.overflowing_sub(2), (1, false));
+    assert_eq!(0_u128.overflowing_sub(1), (BoundedInt::<u128>::max(), true));
+    assert_eq!(3_u256.overflowing_sub(2), (1, false));
+    assert_eq!(0_u256.overflowing_sub(1), (BoundedInt::<u256>::max(), true));
+}
+
+#[test]
+fn test_overflowing_sub_positive_signed_integers() {
+    assert!(3_i8.overflowing_sub(2) == (1, false));
+    assert!(BoundedInt::<i8>::min().overflowing_sub(1) == (BoundedInt::<i8>::max(), true));
+    assert!(3_i16.overflowing_sub(2) == (1, false));
+    assert!(BoundedInt::<i16>::min().overflowing_sub(1) == (BoundedInt::<i16>::max(), true));
+    assert!(3_i32.overflowing_sub(2) == (1, false));
+    assert!(BoundedInt::<i32>::min().overflowing_sub(1) == (BoundedInt::<i32>::max(), true));
+    assert!(3_i64.overflowing_sub(2) == (1, false));
+    assert!(BoundedInt::<i64>::min().overflowing_sub(1) == (BoundedInt::<i64>::max(), true));
+    assert!(3_i128.overflowing_sub(2) == (1, false));
+    assert!(BoundedInt::<i128>::min().overflowing_sub(1) == (BoundedInt::<i128>::max(), true));
+}
+
+#[test]
+fn test_overflowing_sub_negative_signed_integers() {
+    assert!((-3_i8).overflowing_sub(-2) == (-1, false));
+    assert!(BoundedInt::<i8>::max().overflowing_sub(-1) == (BoundedInt::<i8>::min(), true));
+    assert!((-3_i16).overflowing_sub(-2) == (-1, false));
+    assert!(BoundedInt::<i16>::max().overflowing_sub(-1) == (BoundedInt::<i16>::min(), true));
+    assert!((-3_i32).overflowing_sub(-2) == (-1, false));
+    assert!(BoundedInt::<i32>::max().overflowing_sub(-1) == (BoundedInt::<i32>::min(), true));
+    assert!((-3_i64).overflowing_sub(-2) == (-1, false));
+    assert!(BoundedInt::<i64>::max().overflowing_sub(-1) == (BoundedInt::<i64>::min(), true));
+    assert!((-3_i128).overflowing_sub(-2) == (-1, false));
+    assert!(BoundedInt::<i128>::max().overflowing_sub(-1) == (BoundedInt::<i128>::min(), true));
+}