packages feed

clash-prelude 1.10.3 → 1.10.4

raw patch · 15 files changed

+233/−50 lines, 15 filesPVP ok

version bump matches the API change (PVP)

API changes (from Hackage documentation)

Files

CHANGELOG.md view
@@ -1,5 +1,67 @@ # Changelog for the Clash project +## 1.10.4 - *17 Nov, 2026*++### Changed:++- Clash now derives more names in the generated HDL from the source code:++  * Arguments of data constructors are named after the record field they are passed to, e.g. `c$baudCount` instead of `c$app_arg` for the second field of `Tx { txState, baudCount }`.+  * Arguments of functions are named after the function and its parameter, e.g. `c$txStep_s` for the state of `mealy txStep`.+  * Case alternatives are named after the constructor they match, e.g. `c$x_case_Idle` instead of `c$x_case_alt` for the alternative `Idle -> ...` of `x = case s of ...`.+  * Pattern bindings such as `(nextState, output) = ...` are named after their variables, e.g. `nextState_output` instead of `ds`.+  * Variables made up by GHC, such as `eta`, are named after the parameter of the user-defined function they're passed to. This also names ports of top entities without a `Synthesize` annotation.+  * User-written names are kept when they are aliases of variables Clash made up. For example, `dSCL` in `let dSCL = fst _dI2C` now names the register holding that field.++  [#3503](https://github.com/clash-lang/clash-compiler/pull/3503)+- Fields of SystemVerilog structs for records are now named after the record fields, e.g. `baudCount` instead of `Tx_sel1` for the field `baudCount` of a record `Tx`. When a record field isn't a valid SystemVerilog identifier, such as a keyword like `input` or a name with a `'`, the struct's fields are named like `Tx_sel1_baudCount` instead. Fields of tuples and other products without field names keep names like `Tuple2_sel0`.+  [#3503](https://github.com/clash-lang/clash-compiler/pull/3503)+- Removing unused declarations no longer shuffles the order of the remaining declarations in the generated HDL.+  [#3503](https://github.com/clash-lang/clash-compiler/pull/3503)+- Comparing constructors of enumerations with derived `==`, such as `mode == Done`, no longer produces an `Int`-wide signal named `c$case_scrut` in the HDL.+  [#3503](https://github.com/clash-lang/clash-compiler/pull/3503)+- Alternatives of case statements in the generated HDL now mention the constructor they match in a comment, e.g. `2'b00 : busy = 1'b0; // Idle`.+  [#3503](https://github.com/clash-lang/clash-compiler/pull/3503)+- Signals holding a record field that the HDL matches on are now named after the record and the field, e.g. `s_mode` for the field `mode` of a signal `s`.+  [#3503](https://github.com/clash-lang/clash-compiler/pull/3503)+- Clash now reports errors in the module it compiles directly, instead of wrapping them in a message about loading the module from both precompiled and local sources.+  [#2365](https://github.com/clash-lang/clash-compiler/issues/2365) [#2680](https://github.com/clash-lang/clash-compiler/issues/2680)+- Improved the documentation on converting between number types.+  [#3537](https://github.com/clash-lang/clash-compiler/pull/3537)+- The error for an inline primitive with a mismatched name now points at the annotated function.+  [#2365](https://github.com/clash-lang/clash-compiler/issues/2365)++### Fixed:++- Clash's internal `split#` unfolding now returns zero for zero-width halves, matching its Haskell counterpart.+  [#3490](https://github.com/clash-lang/clash-compiler/pull/3490)+- `GHC.Num.Integer.integerLogBase#` and `GHC.Num.Natural.naturalLogBase#` are now constant folded accurately, even in cases where these functions return errors.+  [#3492](https://github.com/clash-lang/clash-compiler/pull/3492)+- Unhandled `error` calls are reported with their `HasCallStack` backtrace again on GHC 9.12 and later.+  [#3449](https://github.com/clash-lang/clash-compiler/pull/3449)+- Errors raised while compiling top entities concurrently now report the backtrace they were thrown with, instead of one pointing into `async`.+  [#3449](https://github.com/clash-lang/clash-compiler/pull/3449)+- Clash no longer takes quadratic or exponential time to compile designs that use `iterateI` with a function that inspects its argument more than once, e.g. `iterateI (\(Just n) -> if n == maxBound then Nothing else Just (n + 1)) (Just 0)`, when the resulting vector is consumed by functions such as `takeI` or `foldr`.+  [#3477](https://github.com/clash-lang/clash-compiler/issues/3477) [#3539](https://github.com/clash-lang/clash-compiler/pull/3539)+- Clash now reports an error when `clash-lib`'s `mkFunInput` gets called with a local variable as its function input.+  [#3499](https://github.com/clash-lang/clash-compiler/pull/3499)+- The VHDL backend now generates valid VHDL for entities without ports, such as a top entity whose ports are all zero-width. This can be helpful when creating self-contained VHDL test benches.+  [#3500](https://github.com/clash-lang/clash-compiler/pull/3500)+- Clash's evaluator no longer produces an `SNat` newtype constructor when evaluating `withSomeSNat`.+  [#3491](https://github.com/clash-lang/clash-compiler/pull/3491)+- Clash no longer crashes on `iterateI` with functions such as `map f` or `resize`.+  [#3495](https://github.com/clash-lang/clash-compiler/issues/3495)+- Constant `BitVector` indices in Verilog and SystemVerilog are now rendered as plain integers, avoiding `64'sd` prefixes that caused warnings in tools such as Verilator.+  [#3056](https://github.com/clash-lang/clash-compiler/issues/3056)+- Clash no longer duplicates components whose result is projected out of more than once.+  [#3517](https://github.com/clash-lang/clash-compiler/issues/3517) [#3519](https://github.com/clash-lang/clash-compiler/pull/3519)+- Clash no longer duplicates components when applying a primitive to another instantiation of a primitive in certain situations.+  [#3516](https://github.com/clash-lang/clash-compiler/issues/3516) [#3518](https://github.com/clash-lang/clash-compiler/pull/3518)+- Clash now reports a clear error for functions returning a non-representable type that it can't inline away.+  [#3521](https://github.com/clash-lang/clash-compiler/issues/3521)+- Generating Verilog or SystemVerilog for `BitVector` indexing now uses the built-in blackbox function directly, avoiding unnecessary interpreter sessions that slowed compilation and could crash the compiler.+  [#3522](https://github.com/clash-lang/clash-compiler/pull/3522)+ ## 1.10.3 - *14 Oct, 2026*  ### Added:
clash-prelude.cabal view
@@ -1,6 +1,6 @@ Cabal-version:        2.2 Name:                 clash-prelude-Version:              1.10.3+Version:              1.10.4 Synopsis:             Clash: a functional hardware description language - Prelude library Description:   Clash is a functional hardware description language that borrows both its
src/Clash/Class/BitPack/Internal.hs view
@@ -211,6 +211,11 @@ {-# INLINE[1] bitCoerce #-} -- | Coerce a value from one type to another through its bit representation. --+-- This keeps the bit pattern, not the numeric value. To keep the value, use+-- 'Clash.Class.NumConvert.numConvert' or+-- 'Clash.Class.NumConvert.maybeNumConvert'. See "Clash.Class.NumConvert" for an+-- overview of conversions between number types.+-- -- >>> pack (-5 :: Signed 6) -- 0b11_1011 -- >>> bitCoerce (-5 :: Signed 6) :: Unsigned 6
src/Clash/Class/NumConvert.hs view
@@ -1,5 +1,6 @@ {- | Copyright  :  (C) 2025     , Martijn Bastiaan+                  2026     , QBayLogic B.V. License    :  BSD2 (see the file LICENSE) Maintainer :  QBayLogic B.V. <devops@qbaylogic.com> @@ -11,9 +12,91 @@ * 'NumConvert': for conversions that, based on types, are guaranteed to succeed. * 'MaybeNumConvert': for conversions that may fail for some values. -As opposed to 'Prelude.fromIntegral', all conversions are translatable to-synthesizable HDL.+As opposed to 'Prelude.fromIntegral', no conversion silently changes the value. +== __Choosing a conversion__+Clash offers several ways to convert between number types such as+'Clash.Sized.BitVector.BitVector', 'Clash.Sized.Unsigned.Unsigned',+'Clash.Sized.Signed.Signed', 'Clash.Sized.Index.Index', 'Int' and 'Data.Word.Word8'.+Which one to use depends on what should happen to the value.++=== Keep the value, and the target type can hold every value of the source type+Use 'numConvert'. If the target type cannot represent every value of the source+type, the conversion is rejected at compile time.++>>> numConvert (3 :: Index 8) :: Unsigned 3+3+>>> numConvert (200 :: Unsigned 8) :: Signed 9+200+>>> numConvert (-3 :: Signed 4) :: Int+-3++=== Keep the value, but the target type might not hold it+Use 'maybeNumConvert'. It returns 'Nothing' for values the target type cannot+represent.++>>> maybeNumConvert (-3 :: Signed 8) :: Maybe (Unsigned 8)+Nothing+>>> maybeNumConvert (100 :: Unsigned 8) :: Maybe (Index 128)+Just 100++=== Change the width, keep the type+Use 'Clash.Class.Resize.resize', 'Clash.Class.Resize.zeroExtend',+'Clash.Class.Resize.signExtend' or 'Clash.Class.Resize.truncateB' from the+'Clash.Class.Resize.Resize' class. Making a number narrower with+'Clash.Class.Resize.truncateB' drops its most significant bits.+'Clash.Class.Resize.resize' does the same, except for signed numbers: it keeps+the sign bit and drops the bits next to it. 'Clash.Sized.Index.Index' is an+exception: a value that does not fit results in an+'Clash.XException.XException'.++>>> resize (-3 :: Signed 4) :: Signed 8+-3+>>> truncateB (300 :: Unsigned 16) :: Unsigned 8+44+>>> resize (7 :: Signed 4) :: Signed 3+3+>>> truncateB (7 :: Signed 4) :: Signed 3+-1++If you know a value fits, use 'Clash.Class.Resize.checkedResize' or+'Clash.Class.Resize.checkedTruncateB' to have simulation check that assumption.+To handle values that do not fit, use 'maybeNumConvert'.++=== Keep the bits, change the type+Use 'Clash.Class.BitPack.bitCoerce' to convert between types of the same bit+width, or 'Clash.Class.BitPack.pack' and 'Clash.Class.BitPack.unpack' to convert+to and from 'Clash.Sized.BitVector.BitVector'. These keep the bit pattern, not+the value: a negative 'Clash.Sized.Signed.Signed' number becomes a large+'Clash.Sized.Unsigned.Unsigned' one.++>>> bitCoerce (-5 :: Signed 6) :: Unsigned 6+59+>>> pack (5 :: Unsigned 4)+0b0101++Not every bit pattern represents an 'Clash.Sized.Index.Index'. Use+'Clash.Sized.Index.bv2i' to pick an 'Clash.Sized.Index.Index' that can hold all+of them:++>>> bv2i (12 :: BitVector 4)+12++=== Change the type and drop bits+Combine the conversions above. For example, to keep the 8 least significant bits+of a @Signed 16@ as an @Unsigned 8@:++>>> truncateB (bitCoerce (-1 :: Signed 16) :: Unsigned 16) :: Unsigned 8+255++=== Why not 'fromIntegral'?+'fromIntegral' converts through 'Integer', which has a fixed width in HDL (64+bits by default, see @-fclash-intwidth@). Bits above that width are lost. It+also hides what happens to values the target type cannot hold:+'Clash.Sized.Unsigned.Unsigned' and 'Clash.Sized.Signed.Signed' wrap around,+while 'Clash.Sized.Index.Index' results in an 'Clash.XException.XException'.+The functions above make that choice explicit.+ == __Relation to @convertible@__ Type classes exported here are similar to the @convertible@ package in that it aims to facilitate conversions between different types. It is different in three@@ -42,3 +125,11 @@ import Clash.Class.NumConvert.Internal.MaybeNumConvert import Clash.Class.NumConvert.Internal.NumConvert import Clash.Class.NumConvert.Internal.Canonical++{- $setup+>>> :set -fplugin GHC.TypeLits.Extra.Solver+>>> :set -fplugin GHC.TypeLits.KnownNat.Solver+>>> :set -fplugin GHC.TypeLits.Normalise+>>> import Clash.Prelude+>>> import Clash.Class.NumConvert+-}
src/Clash/Class/Resize.hs view
@@ -36,6 +36,8 @@ import GHC.TypeLits (OrderingI(EQI, GTI), cmpNat)  -- | Coerce a value to be represented by a different number of bits+--+-- To convert to a different type, see "Clash.Class.NumConvert". class Resize (f :: Nat -> Type) where   -- | A sign-preserving resize operation   --@@ -82,9 +84,10 @@ -- -- * __NB__: Check only affects simulation. I.e., no checks will be inserted -- into the generated HDL--- * __NB__: 'fromIntegral' is not well suited for Clash as it will go through--- 'Integer' which is arbitrarily bounded in HDL. Instead use--- 'Clash.Class.BitPack.bitCoerce' and the 'Resize' class.+-- * __NB__: 'fromIntegral' goes through 'Integer', which has a fixed width in+-- HDL. Prefer 'Clash.Class.NumConvert.numConvert' or+-- 'Clash.Class.NumConvert.maybeNumConvert'. See "Clash.Class.NumConvert" for an+-- overview of conversions between number types. checkedFromIntegral ::   forall a b.   HasCallStack =>
src/Clash/Explicit/Mealy.hs view
@@ -3,8 +3,9 @@                     2017     , Google Inc.                     2019     , Myrtle Software Ltd                     2023     , Alex Mason+                    2026     , QBayLogic B.V.   License    :  BSD2 (see the file LICENSE)-  Maintainer :  Christiaan Baaij <christiaan.baaij@gmail.com>+  Maintainer :  QBayLogic B.V. <devops@qbaylogic.com>    Whereas the output of a Moore machine depends on the /previous state/, the   output of a Mealy machine depends on /current transition/.@@ -139,7 +140,7 @@   -> Enable dom   -- ^ Global enable   -> (s -> i -> (s,o))-  -- ^ Transfer function in mealy machine form: @state -> input -> (newstate,output)@+  -- ^ Transition function in mealy machine form: @state -> input -> (newstate,output)@   -> s   -- ^ Initial state   -> (Signal dom i -> Signal dom o)@@ -197,7 +198,7 @@   -> Enable dom   -- ^ Global enable   -> (i -> State s o)-  -- ^ Transfer function in mealy machine handling inputs using @Control.Monad.Strict.State s@.+  -- ^ Transition function in mealy machine handling inputs using @Control.Monad.Strict.State s@.   -> s   -- ^ Initial state   -> (Signal dom i -> Signal dom o)@@ -244,7 +245,7 @@   -> Reset dom   -> Enable dom   -> (s -> i -> (s,o))-  -- ^ Transfer function in mealy machine form: @state -> input -> (newstate,output)@+  -- ^ Transition function in mealy machine form: @state -> input -> (newstate,output)@   -> s   -- ^ Initial state   -> (Unbundled dom i -> Unbundled dom o)@@ -264,7 +265,7 @@   -> Reset dom   -> Enable dom   -> (i -> State s o)-  -- ^ Transfer function in mealy machine handling inputs using @Control.Monad.Strict.State s@.+  -- ^ Transition function in mealy machine handling inputs using @Control.Monad.Strict.State s@.   -> s   -- ^ Initial state   -> (Unbundled dom i -> Unbundled dom o)
src/Clash/Explicit/Moore.hs view
@@ -2,8 +2,9 @@   Copyright  :  (C) 2013-2016, University of Twente,                     2017     , Google Inc.                     2019     , Myrtle Software Ltd+                    2026     , QBayLogic B.V.   License    :  BSD2 (see the file LICENSE)-  Maintainer :  Christiaan Baaij <christiaan.baaij@gmail.com>+  Maintainer :  QBayLogic B.V. <devops@qbaylogic.com>    Whereas the output of a Mealy machine depends on /current transition/, the   output of a Moore machine depends on the /previous state/.@@ -85,7 +86,7 @@   -> Reset dom   -> Enable dom   -> (s -> i -> s)-  -- ^ Transfer function in moore machine form: @state -> input -> newstate@+  -- ^ Transition function in moore machine form: @state -> input -> newstate@   -> (s -> o)   -- ^ Output function in moore machine form: @state -> output@   -> s@@ -149,7 +150,7 @@   -> Reset dom   -> Enable dom   -> (s -> i -> s)-  -- ^ Transfer function in moore machine form:+  -- ^ Transition function in moore machine form:   -- @state -> input -> newstate@   -> (s -> o)   -- ^ Output function in moore machine form:
src/Clash/Explicit/Prelude/Safe.hs view
@@ -2,7 +2,7 @@ Copyright  :  (C) 2013-2016, University of Twente,                   2017     , Google Inc.                   2019     , Myrtle Software Ltd,-                  2021-2022, QBayLogic B.V.+                  2021-2026, QBayLogic B.V. License    :  BSD2 (see the file LICENSE) Maintainer :  QBayLogic B.V. <devops@qbaylogic.com> @@ -244,13 +244,13 @@   -> Enable dom   -> SNat n   -> Signal dom Bool-riseEvery clk rst en SNat = moore clk rst en transfer output 0 (pure ())+riseEvery clk rst en SNat = moore clk rst en trans output 0 (pure ())   where     output :: Index n -> Bool     output = (== maxBound) -    transfer :: Index n -> () -> Index n-    transfer s _ = if (s == maxBound) then 0 else s+1+    trans :: Index n -> () -> Index n+    trans s _ = if (s == maxBound) then 0 else s+1 {-# INLINEABLE riseEvery #-}  -- | Oscillate a @'Bool'@ for a given number of cycles, given the starting state.@@ -264,10 +264,10 @@   -> SNat n   -> Signal dom Bool oscillate clk rst en begin SNat =-  moore clk rst en transfer snd (0, begin) (pure ())+  moore clk rst en trans snd (0, begin) (pure ())  where-  transfer :: (Index n, Bool) -> () -> (Index n, Bool)-  transfer (s, i) _ =+  trans :: (Index n, Bool) -> () -> (Index n, Bool)+  trans (s, i) _ =     if s == maxBound       then (0,   not i) -- reset state and oscillate output       else (s+1, i)     -- hold current output
src/Clash/Prelude/Mealy.hs view
@@ -3,8 +3,9 @@                     2017     , Google Inc.                     2019     , Myrtle Software Ltd                     2023     , Alex Mason+                    2026     , QBayLogic B.V.   License    :  BSD2 (see the file LICENSE)-  Maintainer :  Christiaan Baaij <christiaan.baaij@gmail.com>+  Maintainer :  QBayLogic B.V. <devops@qbaylogic.com>    Whereas the output of a Moore machine depends on the /previous state/, the   output of a Mealy machine depends on /current transition/.@@ -123,7 +124,7 @@   :: ( HiddenClockResetEnable dom      , NFDataX s )   => (s -> i -> (s,o))-  -- ^ Transfer function in mealy machine form: @state -> input -> (newstate,output)@+  -- ^ Transition function in mealy machine form: @state -> input -> (newstate,output)@   -> s   -- ^ Initial state   -> (Signal dom i -> Signal dom o)@@ -164,7 +165,7 @@      , Bundle i      , Bundle o )   => (s -> i -> (s,o))-  -- ^ Transfer function in mealy machine form: @state -> input -> (newstate,output)@+  -- ^ Transition function in mealy machine form: @state -> input -> (newstate,output)@   -> s   -- ^ Initial state   -> (Unbundled dom i -> Unbundled dom o)@@ -212,7 +213,7 @@   :: ( HiddenClockResetEnable dom      , NFDataX s )   => (i -> State s o)-  --  ^ Transfer function in mealy machine handling inputs using @Control.Monad.Strict.State s@.+  -- ^ Transition function in mealy machine handling inputs using @Control.Monad.Strict.State s@.   -> s   -- ^ Initial state   -> (Signal dom i -> Signal dom o)@@ -228,7 +229,7 @@      , Bundle i      , Bundle o  )   => (i -> State s o)-  --  ^ Transfer function in mealy machine handling inputs using @Control.Monad.Strict.State s@.+  -- ^ Transition function in mealy machine handling inputs using @Control.Monad.Strict.State s@.   -> s   -- ^ Initial state   -> (Unbundled dom i -> Unbundled dom o)@@ -244,7 +245,7 @@      , Bundle i      , Bundle o )   => (s -> i -> (s,o))-  -- ^ Transfer function in mealy machine form: @state -> input -> (newstate,output)@+  -- ^ Transition function in mealy machine form: @state -> input -> (newstate,output)@   -> s   -- ^ Initial state  -> (Unbundled dom i -> Unbundled dom o)
src/Clash/Prelude/Moore.hs view
@@ -2,8 +2,9 @@   Copyright  :  (C) 2013-2016, University of Twente                     2017     , Google Inc.                     2019     , Myrtle Software Ltd+                    2026     , QBayLogic B.V.   License    :  BSD2 (see the file LICENSE)-  Maintainer :  Christiaan Baaij <christiaan.baaij@gmail.com>+  Maintainer :  QBayLogic B.V. <devops@qbaylogic.com>    Whereas the output of a Mealy machine depends on /current transition/, the   output of a Moore machine depends on the /previous state/.@@ -82,7 +83,7 @@   :: ( HiddenClockResetEnable dom      , NFDataX s )   => (s -> i -> s)-  -- ^ Transfer function in moore machine form: @state -> input -> newstate@+  -- ^ Transition function in moore machine form: @state -> input -> newstate@   -> (s -> o)   -- ^ Output function in moore machine form: @state -> output@   -> s@@ -138,7 +139,7 @@      , Bundle i      , Bundle o )   => (s -> i -> s)-  -- ^ Transfer function in moore machine form: @state -> input -> newstate@+  -- ^ Transition function in moore machine form: @state -> input -> newstate@   -> (s -> o)   -- ^ Output function in moore machine form: @state -> output@   -> s
src/Clash/Sized/Index.hs view
@@ -42,5 +42,8 @@ -- -- 'bv2i' on the other hand will /never/ fail at run-time, because the -- 'BitVector' argument determines the size.+--+-- See "Clash.Class.NumConvert" for an overview of conversions between number+-- types. bv2i :: KnownNat n => BitVector n -> Index (2^n) bv2i = unpack#
src/Clash/Sized/Internal/BitVector.hs view
@@ -233,10 +233,13 @@ -- * Bit indices are descending -- * 'Num' instance performs /unsigned/ arithmetic. ----- __NB__: The usual Haskell method of converting an integral numeric type to--- another, 'fromIntegral', is not well suited for Clash as it will go through--- 'Integer' which is arbitrarily bounded in HDL. Instead use--- 'Clash.Class.BitPack.bitCoerce' and the 'Resize' class.+-- __NB__: To convert to another number type, use+-- 'Clash.Class.NumConvert.numConvert' if the target type can hold every value,+-- 'Clash.Class.NumConvert.maybeNumConvert' if it might not, the+-- 'Clash.Class.Resize.Resize' class to change the width, and+-- 'Clash.Class.BitPack.bitCoerce' only to reinterpret the bits. Avoid+-- 'fromIntegral': it goes through 'Integer', which has a fixed width in HDL.+-- See "Clash.Class.NumConvert" for an overview with examples. -- -- BitVector has the <https://downloads.haskell.org/ghc/latest/docs/html/users_guide/exts/roles.html type role> --@@ -260,10 +263,13 @@  -- | A single bit ----- __NB__: The usual Haskell method of converting an integral numeric type to--- another, 'fromIntegral', is not well suited for Clash as it will go through--- 'Integer' which is arbitrarily bounded in HDL. Instead use--- 'Clash.Class.BitPack.bitCoerce' and the 'Resize' class.+-- __NB__: To convert to another number type, use+-- 'Clash.Class.NumConvert.numConvert' if the target type can hold every value,+-- 'Clash.Class.NumConvert.maybeNumConvert' if it might not, the+-- 'Clash.Class.Resize.Resize' class to change the width, and+-- 'Clash.Class.BitPack.bitCoerce' only to reinterpret the bits. Avoid+-- 'fromIntegral': it goes through 'Integer', which has a fixed width in HDL.+-- See "Clash.Class.NumConvert" for an overview with examples. data Bit =   -- | The constructor, 'Bit', and  the fields, 'unsafeMask#' and 'unsafeToInteger#', are not   -- synthesizable.
src/Clash/Sized/Internal/Index.hs view
@@ -163,10 +163,13 @@ -- *** Exception: X: Clash.Sized.Index: result 8 is out of bounds: [0..7] -- ... ----- __NB__: The usual Haskell method of converting an integral numeric type to--- another, 'fromIntegral', is not well suited for Clash as it will go through--- 'Integer' which is arbitrarily bounded in HDL. Instead use--- 'Clash.Class.BitPack.bitCoerce' and the 'Resize' class.+-- __NB__: To convert to another number type, use+-- 'Clash.Class.NumConvert.numConvert' if the target type can hold every value,+-- 'Clash.Class.NumConvert.maybeNumConvert' if it might not, the+-- 'Clash.Class.Resize.Resize' class to change the width, and+-- 'Clash.Class.BitPack.bitCoerce' only to reinterpret the bits. Avoid+-- 'fromIntegral': it goes through 'Integer', which has a fixed width in HDL.+-- See "Clash.Class.NumConvert" for an overview with examples. -- -- Index has the <https://downloads.haskell.org/ghc/latest/docs/html/users_guide/exts/roles.html type role> --
src/Clash/Sized/Internal/Signed.hs view
@@ -161,10 +161,13 @@ -- a 'Signed' @n@ number has a range of: [-(2^(@n@-1)) .. 2^(@n@-1)-1] for -- @n > 0@. When @n = 0@, both the min and max bound are 0. ----- * __NB__: The usual Haskell method of converting an integral numeric type to--- another, 'fromIntegral', is not well suited for Clash as it will go through--- 'Integer' which is arbitrarily bounded in HDL. Instead use--- 'Clash.Class.BitPack.bitCoerce' and the 'Resize' class.+-- * __NB__: To convert to another number type, use+-- 'Clash.Class.NumConvert.numConvert' if the target type can hold every value,+-- 'Clash.Class.NumConvert.maybeNumConvert' if it might not, the+-- 'Clash.Class.Resize.Resize' class to change the width, and+-- 'Clash.Class.BitPack.bitCoerce' only to reinterpret the bits. Avoid+-- 'fromIntegral': it goes through 'Integer', which has a fixed width in HDL.+-- See "Clash.Class.NumConvert" for an overview with examples. -- * __NB__: The 'Num' operators perform @wrap-around@ on overflow. If you want -- saturation on overflow, check out the 'SaturatingNum' class. --
src/Clash/Sized/Internal/Unsigned.hs view
@@ -165,10 +165,13 @@ -- -- Given @n@ bits, an 'Unsigned' @n@ number has a range of: [0 .. 2^@n@-1] ----- * __NB__: The usual Haskell method of converting an integral numeric type to--- another, 'fromIntegral', is not well suited for Clash as it will go through--- 'Integer' which is arbitrarily bounded in HDL. Instead use--- 'Clash.Class.BitPack.bitCoerce' and the 'Resize' class.+-- * __NB__: To convert to another number type, use+-- 'Clash.Class.NumConvert.numConvert' if the target type can hold every value,+-- 'Clash.Class.NumConvert.maybeNumConvert' if it might not, the+-- 'Clash.Class.Resize.Resize' class to change the width, and+-- 'Clash.Class.BitPack.bitCoerce' only to reinterpret the bits. Avoid+-- 'fromIntegral': it goes through 'Integer', which has a fixed width in HDL.+-- See "Clash.Class.NumConvert" for an overview with examples. -- * __NB__: The 'Num' operators perform @wrap-around@ on overflow. If you want -- saturation on overflow, check out the 'SaturatingNum' class. --