Add SaturatingNum and Bounded for Signal dom a (#3137)

Closes #2931

Co-authored-by: Martijn Bastiaan <martijn@qbaylogic.com>

Author: Copilot

changelog/2026-02-08T16_57_33+00_00_add_saturatingnum_signal_instance

@@ -0,0 +1 @@
+ADDED: `SaturatingNum` and `Bounded` instances for `Signal dom a`. The `sat` family (`satAdd`, `satSucc`, ...) can now be used on `Signal`s and `{min,max}Bound` can be used to construct them [#2931](github.com/clash-lang/clash-compiler/issues/2931)

clash-prelude/src/Clash/Signal/Internal.hs

@@ -211,6 +211,7 @@ import System.IO.Unsafe           (unsafeInterleaveIO, unsafePerformIO)
 import Test.QuickCheck            (Arbitrary (..), CoArbitrary(..), Property,
                                    property)
 
+import Clash.Class.Num            (SaturatingNum(..))
 import Clash.CPP                  (fStrictMapSignal)
 import Clash.NamedTypes
 import Clash.Promoted.Nat         (SNat (..), snatToNum, snatToNatural)
@@ -910,6 +911,17 @@ instance Num a => Num (Signal dom a) where
   signum      = fmap signum
   fromInteger = signal# . fromInteger
 
+instance Bounded a => Bounded (Signal dom a) where
+  minBound = pure minBound
+  maxBound = pure maxBound
+
+instance SaturatingNum a => SaturatingNum (Signal dom a) where
+  satAdd mode = liftA2 (satAdd mode)
+  satSub mode = liftA2 (satSub mode)
+  satMul mode = liftA2 (satMul mode)
+  satSucc mode = fmap (satSucc mode)
+  satPred mode = fmap (satPred mode)
+
 -- | __NB__: Not synthesizable
 --
 -- __NB__: In \"@'foldr' f z s@\":

clash-prelude/tests/Clash/Tests/Signal.hs

@@ -61,6 +61,12 @@ tests =
             in
               evaluate a >> pure ()
         ]
+    , testGroup "SaturatingNum"
+      [ testCase "satSucc SatWrap" case_satSuccSatWrap
+      , testCase "satSucc SatBound" case_satSuccSatBound
+      , testCase "satPred SatWrap" case_satPredSatWrap
+      , testCase "satPred SatBound" case_satPredSatBound
+      ]
     , testGroup "unsafeSynchronizer"
       [ testCase "case_dynamicStaticEq" case_dynamicStaticEq
       , testCase "case_dynamicHasEffect" case_dynamicHasEffect
@@ -180,3 +186,31 @@ case_F6_F1 = do
     , 2, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4
     , 4, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 6, 6, 6, 6, 6, 6, 6
     ]
+
+-- | Test that satSucc SatWrap works on signals
+case_satSuccSatWrap :: Assertion
+case_satSuccSatWrap = do
+  let s = fromList [255, 254] :: Signal System (Unsigned 8)
+      result = satSucc SatWrap s
+  sampleN @System 2 result @?= [0, 255]
+
+-- | Test that satSucc SatBound works on signals
+case_satSuccSatBound :: Assertion
+case_satSuccSatBound = do
+  let s = fromList [255, 254] :: Signal System (Unsigned 8)
+      result = satSucc SatBound s
+  sampleN @System 2 result @?= [255, 255]
+
+-- | Test that satPred SatWrap works on signals
+case_satPredSatWrap :: Assertion
+case_satPredSatWrap = do
+  let s = fromList [0, 1] :: Signal System (Unsigned 8)
+      result = satPred SatWrap s
+  sampleN @System 2 result @?= [255, 0]
+
+-- | Test that satPred SatBound works on signals
+case_satPredSatBound :: Assertion
+case_satPredSatBound = do
+  let s = fromList [0, 1] :: Signal System (Unsigned 8)
+      result = satPred SatBound s
+  sampleN @System 2 result @?= [0, 0]