Clash offers several ways to convert between number types such as BitVector, Unsigned, Signed, Index, Int and 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 resize, zeroExtend, signExtend or truncateB from the Resize class. Making a number narrower with truncateB drops its most significant bits. resize does the same, except for signed numbers: it keeps the sign bit and drops the bits next to it. Index is an exception: a value that does not fit results in an 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 checkedResize or checkedTruncateB to have simulation check that assumption. To handle values that do not fit, use maybeNumConvert.

Keep the bits, change the type

Use bitCoerce to convert between types of the same bit width, or pack and unpack to convert to and from BitVector. These keep the bit pattern, not the value: a negative Signed number becomes a large Unsigned one.

>>> bitCoerce (-5 :: Signed 6) :: Unsigned 6
59
>>> pack (5 :: Unsigned 4)
0b0101

Not every bit pattern represents an Index. Use maybeUnpack to reject such patterns, or bv2i to pick an Index that can hold all of them:

>>> maybeUnpack (12 :: BitVector 4) :: Maybe (Index 10)
Nothing
>>> 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: Unsigned and Signed wrap around, while Index results in an XException. The functions above make that choice explicit.

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 ways:

1. It offers no partial functions
2. All its conversions are translatable to synthesizable HDL
3. It is focused on (Clash's) number types

If you want to implement NumConvert and MaybeNumConvert for your own type, see NumConvertCanonical.