Improve ranges in error messages (#2733)

changelog/2024-06-11T16_55_10+02_00_improve_range_error

@@ -0,0 +1 @@
+CHANGED: The error messages that mention the valid ranges for out-of-range inputs have been improved to be more intuitive: one of `<empty range>`, `[n]` or `[n..m]`. All _n..m_ ranges are now ordered with the lower bound on the left.

clash-prelude/clash-prelude.cabal

@@ -315,6 +315,7 @@ Library
                       Clash.Clocks.Internal
                       Clash.CPP
                       Clash.Signal.Bundle.Internal
+                      Clash.Sized.Internal
                       Language.Haskell.TH.Compat
                       Paths_clash_prelude
 

clash-prelude/src/Clash/Class/BitPack/BitIndex.hs

@@ -39,7 +39,7 @@ import Clash.Sized.Internal.BitVector
 -- >>> (7 :: Unsigned 6) ! 5
 -- 0
 -- >>> (7 :: Unsigned 6) ! 6
--- *** Exception: (!): 6 is out of range [5..0]
+-- *** Exception: (!): 6 is out of range [0..5]
 -- ...
 (!) :: (BitPack a, Enum i) => a -> i -> Bit
 (!) v i = index# (pack v) (fromEnum i)
@@ -114,7 +114,7 @@ split v = split# (pack v)
 -- >>> pack (27 :: Signed 6)
 -- 0b01_1011
 -- >>> replaceBit 6 0 (-5 :: Signed 6)
--- *** Exception: replaceBit: 6 is out of range [5..0]
+-- *** Exception: replaceBit: 6 is out of range [0..5]
 -- ...
 replaceBit :: (BitPack a, Enum i) => i -> Bit -> a -> a
 replaceBit i b v = unpack (replaceBit# (pack v) (fromEnum i) b)

clash-prelude/src/Clash/Class/Resize.hs

@@ -1,6 +1,7 @@
 {-|
 Copyright  :  (C) 2013-2016, University of Twente
                   2020,      Myrtle Software Ltd
+                  2024,      QBayLogic B.V.
 License    :  BSD2 (see the file LICENSE)
 Maintainer :  QBayLogic B.V. <devops@qbaylogic.com>
 -}
@@ -26,6 +27,8 @@ import Data.Proxy (Proxy(Proxy))
 import GHC.Stack (HasCallStack)
 import GHC.TypeLits (Nat, KnownNat, type (+))
 
+import Clash.Sized.Internal (formatRange)
+
 -- | Coerce a value to be represented by a different number of bits
 class Resize (f :: Nat -> Type) where
   -- | A sign-preserving resize operation
@@ -61,9 +64,8 @@ checkIntegral Proxy v =
   if toInteger v > toInteger (maxBound @b)
   || toInteger v < toInteger (minBound @b) then
     error $ "Given integral " <> show (toInteger v) <> " is out of bounds for" <>
-            " target type. Bounds of target type are: [" <>
-            show (toInteger (minBound @b)) <> ".." <>
-            show (toInteger (maxBound @b)) <> "]."
+            " target type. Bounds of target type are: " <>
+            formatRange (toInteger (minBound @b)) (toInteger (maxBound @b)) <> "."
   else
     ()
 

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

@@ -0,0 +1,24 @@
+{-|
+Copyright  :  (C) 2024     , QBayLogic B.V.
+License    :  BSD2 (see the file LICENSE)
+Maintainer :  QBayLogic B.V. <devops@qbaylogic.com>
+-}
+
+module Clash.Sized.Internal where
+
+-- | Format a range of numbers for use in error messages
+--
+-- If the upper bound is below the lower bound, @"\<empty range\>"@ is returned.
+-- If the bounds are equal, @"[n]"@ is returned (for bounds equal to /n/).
+-- Otherwise, @formatRange n m@ returns @"[n..m]"@.
+formatRange ::
+  (Ord a, Show a) =>
+  -- | Lower bound
+  a ->
+  -- | Upper bound
+  a ->
+  String
+formatRange n m
+  | m < n     = "<empty range>"
+  | m == n    = '[' : shows n "]"
+  | otherwise = '[' : show n ++ ".." ++ shows m "]"

clash-prelude/src/Clash/Sized/Internal/BitVector.hs

@@ -196,6 +196,7 @@ import Clash.Class.Num            (ExtendingNum (..), SaturatingNum (..),
 import Clash.Class.Resize         (Resize (..))
 import Clash.Promoted.Nat
   (SNat (..), SNatLE (..), compareSNat, snatToInteger, snatToNum, natToNum)
+import Clash.Sized.Internal (formatRange)
 import Clash.XException
   (ShowX (..), NFDataX (..), errorX, isX, showsPrecXWith, rwhnfX, XException(..))
 
@@ -1053,9 +1054,8 @@ index# bv@(BV m v) i
 #endif
     err = error $ concat [ "(!): "
                          , show i
-                         , " is out of range ["
-                         , show (sz - 1)
-                         , "..0]"
+                         , " is out of range "
+                         , formatRange 0 (sz - 1)
                          ]
 
 -- See: https://github.com/clash-lang/clash-compiler/pull/2511
@@ -1146,9 +1146,8 @@ replaceBit# bv@(BV m v) i (Bit mb b)
 #endif
     err  = error $ concat [ "replaceBit: "
                           , show i
-                          , " is out of range ["
-                          , show (sz - 1)
-                          , "..0]"
+                          , " is out of range "
+                          , formatRange 0 (sz - 1)
                           ]
 
 -- See: https://github.com/clash-lang/clash-compiler/pull/2511

clash-prelude/src/Clash/Sized/Internal/Index.hs

@@ -1,7 +1,7 @@
 {-|
 Copyright  :  (C) 2013-2016, University of Twente,
                   2016-2019, Myrtle Software Ltd,
-                  2021-2023, QBayLogic B.V.
+                  2021-2024, QBayLogic B.V.
 License    :  BSD2 (see the file LICENSE)
 Maintainer :  QBayLogic B.V. <devops@qbaylogic.com>
 -}
@@ -108,6 +108,7 @@ import Clash.Class.Num            (ExtendingNum (..), SaturatingNum (..),
 import Clash.Class.Parity         (Parity (..))
 import Clash.Class.Resize         (Resize (..))
 import Clash.Class.BitPack.BitIndex (replaceBit)
+import Clash.Sized.Internal       (formatRange)
 import {-# SOURCE #-} Clash.Sized.Internal.BitVector (BitVector (BV), high, low, undefError)
 import qualified Clash.Sized.Internal.BitVector as BV
 import Clash.Promoted.Nat         (SNat(..), snatToNum, natToInteger, leToPlusKN)
@@ -347,7 +348,7 @@ fromInteger_INLINE i = bound `seq` if i > (-1) && i < bound then I i else err
   where
     bound = natToInteger @n
     err   = errorX ("Clash.Sized.Index: result " ++ show i ++
-                   " is out of bounds: [0.." ++ show (bound - 1) ++ "]")
+                   " is out of bounds: " ++ formatRange 0 (bound - 1))
 
 instance ExtendingNum (Index m) (Index n) where
   type AResult (Index m) (Index n) = Index (m + n - 1)
@@ -591,5 +592,5 @@ instance (KnownNat n) => Ix (Index n) where
   range (a, b) = [a..b]
   index ab@(a, b) x
     | inRange ab x = fromIntegral $ x - a
-    | otherwise = error $ printf "Index %d out of bounds (%d, %d)" x a b
+    | otherwise = error $ printf "Index (%d) out of range ((%d, %d))" x a b
   inRange (a, b) x = a <= x && x <= b

clash-prelude/src/Clash/Sized/Internal/Signed.hs

@@ -1,7 +1,7 @@
 {-|
 Copyright  :  (C) 2013-2016, University of Twente,
                   2016     , Myrtle Software Ltd,
-                  2021-2023, QBayLogic B.V.
+                  2021-2024, QBayLogic B.V.
 License    :  BSD2 (see the file LICENSE)
 Maintainer :  QBayLogic B.V. <devops@qbaylogic.com>
 -}
@@ -881,7 +881,7 @@ instance (KnownNat n) => Ix (Signed n) where
   range (a, b) = [a..b]
   index ab@(a, b) x
     | inRange ab x = fromIntegral $ x - a
-    | otherwise = error $ printf "Index %d out of bounds (%d, %d) ab" x a b
+    | otherwise = error $ printf "Index (%d) out of range ((%d, %d))" x a b
   inRange (a, b) x = a <= x && x <= b
 
 -- | Shift left that ties to zero on negative shifts

clash-prelude/src/Clash/Sized/Internal/Unsigned.hs

@@ -1,7 +1,7 @@
 {-|
 Copyright  :  (C) 2013-2016, University of Twente,
                   2016     , Myrtle Software Ltd,
-                  2021-2023, QBayLogic B.V.
+                  2021-2024, QBayLogic B.V.
 License    :  BSD2 (see the file LICENSE)
 Maintainer :  QBayLogic B.V. <devops@qbaylogic.com>
 -}
@@ -794,7 +794,7 @@ instance (KnownNat n) => Ix (Unsigned n) where
   range (a, b) = [a..b]
   index ab@(a, b) x
     | inRange ab x = fromIntegral $ x - a
-    | otherwise = error $ printf "Index %d out of bounds (%d, %d) ab" x a b
+    | otherwise = error $ printf "Index (%d) out of range ((%d, %d))" x a b
   inRange (a, b) x = a <= x && x <= b
 
 unsignedToWord :: Unsigned WORD_SIZE_IN_BITS -> Word