Create a synchronous function from a combinational function describing a mealy machine

macT
  :: Int        -- Current state
  -> (Int,Int)  -- Input
  -> (Int,Int)  -- (Updated state, output)
macT s (x,y) = (s',s)
  where
    s' = x * y + s

mac :: HiddenClockResetEnable dom  => Signal dom (Int, Int) -> Signal dom Int
mac = mealy macT 0

>>> simulate @System mac [(0,0),(1,1),(2,2),(3,3),(4,4)]
[0,0,1,5,14...
...

Synchronous sequential functions can be composed just like their combinational counterpart:

dualMac
  :: HiddenClockResetEnable dom
  => (Signal dom Int, Signal dom Int)
  -> (Signal dom Int, Signal dom Int)
  -> Signal dom Int
dualMac (a,b) (x,y) = s1 + s2
  where
    s1 = mealy macT 0 (bundle (a,x))
    s2 = mealy macT 0 (bundle (b,y))

Create a synchronous function from a combinational function describing a mealy machine using the state monad. This can be particularly useful when combined with lenses or optics to replicate imperative algorithms.

data DelayState = DelayState
  { _history    :: Vec 4 Int
  , _untilValid :: Index 4
  }
  deriving (Generic, NFDataX)
makeLenses ''DelayState

initialDelayState = DelayState (repeat 0) maxBound

delayS :: Int -> State DelayState (Maybe Int)
delayS n = do
  history   %= (n +>>)
  remaining <- use untilValid
  if remaining > 0
  then do
     untilValid -= 1
     return Nothing
   else do
     out <- uses history last
     return (Just out)

delayTop :: HiddenClockResetEnable dom  => Signal dom Int -> Signal dom (Maybe Int)
delayTop = mealyS delayS initialDelayState

>>> L.take 7 $ simulate @System delayTop [1,2,3,4,5,6,7,8]
[Nothing,Nothing,Nothing,Just 1,Just 2,Just 3,Just 4]
...

A version of mealy that does automatic Bundleing

Given a function f of type:

f :: Int -> (Bool, Int) -> (Int, (Int, Bool))

When we want to make compositions of f in g using mealy, we have to write:

g a b c = (b1,b2,i2)
  where
    (i1,b1) = unbundle (mealy f 0 (bundle (a,b)))
    (i2,b2) = unbundle (mealy f 3 (bundle (c,i1)))

Using mealyB however we can write:

g a b c = (b1,b2,i2)
  where
    (i1,b1) = mealyB f 0 (a,b)
    (i2,b2) = mealyB f 3 (c,i1)

A version of mealyS that does automatic Bundleing, see mealyB for details.

Infix version of mealyB

Create a synchronous function from a combinational function describing a moore machine

macT
  :: Int        -- Current state
  -> (Int,Int)  -- Input
  -> Int        -- Updated state
macT s (x,y) = x * y + s

mac
  :: HiddenClockResetEnable dom
  => Signal dom (Int, Int)
  -> Signal dom Int
mac = moore mac id 0

>>> simulate @System mac [(0,0),(1,1),(2,2),(3,3),(4,4)]
[0,0,1,5,14,30,...
...

Synchronous sequential functions can be composed just like their combinational counterpart:

dualMac
  :: HiddenClockResetEnable dom
  => (Signal dom Int, Signal dom Int)
  -> (Signal dom Int, Signal dom Int)
  -> Signal dom Int
dualMac (a,b) (x,y) = s1 + s2
  where
    s1 = moore macT id 0 (bundle (a,x))
    s2 = moore macT id 0 (bundle (b,y))

A version of moore that does automatic Bundleing

Given a functions t and o of types:

t :: Int -> (Bool, Int) -> Int
o :: Int -> (Int, Bool)

When we want to make compositions of t and o in g using moore, we have to write:

g a b c = (b1,b2,i2)
  where
    (i1,b1) = unbundle (moore t o 0 (bundle (a,b)))
    (i2,b2) = unbundle (moore t o 3 (bundle (c,i1)))

Using mooreB however we can write:

g a b c = (b1,b2,i2)
  where
    (i1,b1) = mooreB t o 0 (a,b)
    (i2,b2) = mooreB t o 3 (c,i1)

Create a register function for product-type like signals (e.g. '(Signal a, Signal b)')

rP :: HiddenClockResetEnable dom
   => (Signal dom Int, Signal dom Int)
   -> (Signal dom Int, Signal dom Int)
rP = registerB (8,8)

>>> simulateB @System rP [(1,1),(2,2),(3,3)] :: [(Int,Int)]
[(8,8),(1,1),(2,2),(3,3)...
...

An asynchronous/combinational ROM with space for n elements

See also:

• See Clash.Sized.Fixed and Clash.Prelude.BlockRam for ideas on how to use ROMs and RAMs.
• A large Vec for the content may be too inefficient, depending on how it is constructed. See asyncRomFile and asyncRomBlob for different approaches that scale well.

An asynchronous/combinational ROM with space for 2^n elements

See also:

• See Clash.Sized.Fixed and Clash.Prelude.BlockRam for ideas on how to use ROMs and RAMs.
• A large Vec for the content may be too inefficient, depending on how it is constructed. See asyncRomFilePow2 and asyncRomBlobPow2 for different approaches that scale well.

A ROM with a synchronous read port, with space for n elements

• NB: Read value is delayed by 1 cycle
• NB: Initial output value is undefined, reading it will throw an XException

See also:

• See Clash.Sized.Fixed and Clash.Prelude.BlockRam for ideas on how to use ROMs and RAMs.
• A large Vec for the content may be too inefficient, depending on how it is constructed. See romFile and romBlob for different approaches that scale well.

A ROM with a synchronous read port, with space for 2^n elements

• NB: Read value is delayed by 1 cycle
• NB: Initial output value is undefined, reading it will throw an XException

See also:

• See Clash.Sized.Fixed and Clash.Prelude.BlockRam for ideas on how to use ROMs and RAMs.
• A large Vec for the content may be too inefficient, depending on how it is constructed. See romFilePow2 and romBlobPow2 for different approaches that scale well.

An asynchronous/combinational ROM with space for n elements

See also:

• See Clash.Sized.Fixed and Clash.Prelude.BlockRam for ideas on how to use ROMs and RAMs.

An asynchronous/combinational ROM with space for 2^n elements

See also:

• See Clash.Sized.Fixed and Clash.Prelude.BlockRam for ideas on how to use ROMs and RAMs.

A ROM with a synchronous read port, with space for n elements

• NB: Read value is delayed by 1 cycle
• NB: Initial output value is undefined, reading it will throw an XException

See also:

• See Clash.Sized.Fixed and Clash.Explicit.BlockRam for ideas on how to use ROMs and RAMs.

A ROM with a synchronous read port, with space for 2^n elements

• NB: Read value is delayed by 1 cycle
• NB: Initial output value is undefined, reading it will throw an XException

See also:

• See Clash.Sized.Fixed and Clash.Explicit.BlockRam for ideas on how to use ROMs and RAMs.

Create a RAM with space for n elements

• NB: Initial content of the RAM is undefined, reading it will throw an XException

See also:

• See Clash.Prelude.BlockRam for more information on how to use a RAM.

Create a RAM with space for 2^n elements

• NB: Initial content of the RAM is undefined, reading it will throw an XException

See also:

• See Clash.Prelude.BlockRam for more information on how to use a RAM.

Create a block RAM with space for n elements

• NB: Read value is delayed by 1 cycle
• NB: Initial output value is undefined, reading it will throw an XException

See also:

• See Clash.Prelude.BlockRam for more information on how to use a Block RAM.
• Use the adapter readNew for obtaining write-before-read semantics like this: readNew (blockRam inits) rd wrM.
• A large Vec for the initial content may be too inefficient, depending on how it is constructed. See blockRamFile and blockRamBlob for different approaches that scale well.

Example

bram40
  :: HiddenClock dom
  => Signal dom (Unsigned 6)
  -> Signal dom (Maybe (Unsigned 6, Bit))
  -> Signal dom Bit
bram40 = blockRam (replicate d40 1)

Create a block RAM with space for 2^n elements

• NB: Read value is delayed by 1 cycle
• NB: Initial output value is undefined, reading it will throw an XException

See also:

• See Clash.Prelude.BlockRam for more information on how to use a block RAM.
• Use the adapter readNew for obtaining write-before-read semantics like this: readNew (blockRamPow2 inits) rd wrM.
• A large Vec for the initial content may be too inefficient, depending on how it is constructed. See blockRamFilePow2 and blockRamBlobPow2 for different approaches that scale well.

Example

bram32
  :: HiddenClock dom
  => Signal dom (Unsigned 5)
  -> Signal dom (Maybe (Unsigned 5, Bit))
  -> Signal dom Bit
bram32 = blockRamPow2 (replicate d32 1)

Create a block RAM with space for n elements

• NB: Read value is delayed by 1 cycle
• NB: Initial output value is undefined, reading it will throw an XException

See also:

• See Clash.Prelude.BlockRam for more information on how to use a block RAM.
• Use the adapter readNew for obtaining write-before-read semantics like this: readNew (blockRamBlob content) rd wrM.

Create a block RAM with space for 2^n elements

• NB: Read value is delayed by 1 cycle
• NB: Initial output value is undefined, reading it will throw an XException

See also:

• See Clash.Prelude.BlockRam for more information on how to use a block RAM.
• Use the adapter readNew for obtaining write-before-read semantics like this: readNew (blockRamBlobPow2 content) rd wrM.

Efficient storage of memory content

It holds n words of BitVector m.

Create a MemBlob binding from a list of values

Since this uses Template Haskell, nothing in the arguments given to createMemBlob can refer to something defined in the same module.

Example

createMemBlob "content" Nothing [15 :: Unsigned 8 .. 17]

ram clk en = blockRamBlob clk en content

>>> import qualified Prelude as P
>>> let es = [ Nothing, Just (7 :: Unsigned 8), Just 8 ]
>>> :{
createMemBlob "content0" (Just 0) es
createMemBlob "content1" (Just 1) es
x = 1
:}

>>> let pr = mapM_ (putStrLn . show)
>>> pr $ P.map pack es
0b0_...._....
0b1_0000_0111
0b1_0000_1000
>>> pr $ unpackMemBlob content0
0b0_0000_0000
0b1_0000_0111
0b1_0000_1000
>>> pr $ unpackMemBlob content1
0b0_1111_1111
0b1_0000_0111
0b1_0000_1000

>>> :{
createMemBlob "contentN" Nothing es
x = 1
:}
<interactive>:...: error:...
    packBVs: cannot convert don't care values. Please specify a mapping to a definite value.

Create a MemBlob from a list of values

Since this uses Template Haskell, nothing in the arguments given to memBlobTH can refer to something defined in the same module.

Example

ram clk en = blockRamBlob clk en $(memBlobTH Nothing [15 :: Unsigned 8 .. 17])

>>> import qualified Prelude as P
>>> let es = [ Nothing, Just (7 :: Unsigned 8), Just 8 ]
>>> content0 = $(memBlobTH (Just 0) es)
>>> content1 = $(memBlobTH (Just 1) es)
>>> let pr = mapM_ (putStrLn . show)
>>> pr $ P.map pack es
0b0_...._....
0b1_0000_0111
0b1_0000_1000
>>> pr $ unpackMemBlob content0
0b0_0000_0000
0b1_0000_0111
0b1_0000_1000
>>> pr $ unpackMemBlob content1
0b0_1111_1111
0b1_0000_0111
0b1_0000_1000

>>> $(memBlobTH Nothing es)
<interactive>:...: error:...
    • packBVs: cannot convert don't care values. Please specify a mapping to a definite value.
    • In the untyped splice: $(memBlobTH Nothing es)

Convert a MemBlob back to a list

NB: Not synthesizable

Create a read-after-write block RAM from a read-before-write one

>>> :t readNew (blockRam (0 :> 1 :> Nil))
readNew (blockRam (0 :> 1 :> Nil))
  :: ...
     ...
     ... =>
     Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a

# 867 "srcClashPrelude/BlockRam.hs"

Produces vendor-agnostic HDL that will be inferred as a true dual-port block RAM

Any value that is being written on a particular port is also the value that will be read on that port, i.e. the same-port read/write behavior is: WriteFirst. For mixed-port read/write, when port A writes to the address port B reads from, the output of port B is undefined, and vice versa.

Port operation

Give a pulse when the Signal goes from minBound to maxBound

Give a pulse when the Signal goes from maxBound to minBound

Give a pulse every n clock cycles. This is a useful helper function when combined with functions like regEn or mux, in order to delay a register by a known amount.

To be precise: the given signal will be False for the next n-1 cycles, followed by a single True value:

>>> Prelude.last (sampleN @System 1025 (riseEvery d1024)) == True
True
>>> Prelude.or (sampleN @System 1024 (riseEvery d1024)) == False
True

For example, to update a counter once every 10 million cycles:

counter = regEn 0 (riseEvery (SNat :: SNat 10000000)) (counter + 1)

Oscillate a Bool for a given number of cycles. This is a convenient function when combined with something like regEn, as it allows you to easily hold a register value for a given number of cycles. The input Bool determines what the initial value is.

To oscillate on an interval of 5 cycles:

>>> sampleN @System 11 (oscillate False d5)
[False,False,False,False,False,False,True,True,True,True,True]

To oscillate between True and False:

>>> sampleN @System 11 (oscillate False d1)
[False,False,True,False,True,False,True,False,True,False,True]

An alternative definition for the above could be:

>>> let osc' = register False (not <$> osc')
>>> sampleN @System 200 (oscillate False d1) == sampleN @System 200 osc'
True

Convert a vector to a list.

>>> toList (1:>2:>3:>Nil)
[1,2,3]

NB: This function is not synthesizable

"generate n f x" returns a vector with n repeated applications of f to x.

generate (SNat :: SNat 4) f x == (f x :> f (f x) :> f (f (f x)) :> f (f (f (f x))) :> Nil)
generate d4 f x               == (f x :> f (f x) :> f (f (f x)) :> f (f (f (f x))) :> Nil)

>>> generate d4 (+1) 1
2 :> 3 :> 4 :> 5 :> Nil

"generate n f z" corresponds to the following circuit layout:

Append two vectors.

>>> (1:>2:>3:>Nil) ++ (7:>8:>Nil)
1 :> 2 :> 3 :> 7 :> 8 :> Nil

foldr, applied to a binary operator, a starting value (typically the right-identity of the operator), and a vector, reduces the vector using the binary operator, from right to left:

foldr f z (x1 :> ... :> xn1 :> xn :> Nil) == x1 `f` (... (xn1 `f` (xn `f` z))...)
foldr r z Nil                             == z

>>> foldr (/) 1 (5 :> 4 :> 3 :> 2 :> Nil)
1.875

"foldr f z xs" corresponds to the following circuit layout:

NB: "foldr f z xs" produces a linear structure, which has a depth, or delay, of O(length xs). Use fold if your binary operator f is associative, as "fold f xs" produces a structure with a depth of O(log_2(length xs)).

"map f xs" is the vector obtained by applying f to each element of xs, i.e.,

map f (x1 :> x2 :>  ... :> xn :> Nil) == (f x1 :> f x2 :> ... :> f xn :> Nil)

and corresponds to the following circuit layout:

Merge two vectors, alternating their elements, i.e.,

>>> merge (1 :> 2 :> 3 :> 4 :> Nil) (5 :> 6 :> 7 :> 8 :> Nil)
1 :> 5 :> 2 :> 6 :> 3 :> 7 :> 4 :> 8 :> Nil

"replace n a xs" returns the vector xs where the n'th element is replaced by a.

NB: Vector elements have an ASCENDING subscript starting from 0 and ending at length - 1.

>>> replace 3 7 (1:>2:>3:>4:>5:>Nil)
1 :> 2 :> 3 :> 7 :> 5 :> Nil
>>> replace 0 7 (1:>2:>3:>4:>5:>Nil)
7 :> 2 :> 3 :> 4 :> 5 :> Nil
>>> replace 9 7 (1:>2:>3:>4:>5:>Nil)
1 :> 2 :> 3 :> 4 :> 5 :> *** Exception: Clash.Sized.Vector.replace: index 9 is larger than maximum index 4
...

Extract the first element of a vector

>>> head (1:>2:>3:>Nil)
1

>>> head Nil
<interactive>:...
    • Couldn't match type ‘1’ with ‘0’
      Expected: Vec (0 + 1) a
        Actual: Vec 0 a
    • In the first argument of ‘head’, namely ‘Nil’
      In the expression: head Nil
      In an equation for ‘it’: it = head Nil

# 448 "srcClashSized/Vector.hs"

Extract the last element of a vector

>>> last (1:>2:>3:>Nil)
3

>>> last Nil
<interactive>:...
    • Couldn't match type ‘1’ with ‘0’
      Expected: Vec (0 + 1) a
        Actual: Vec 0 a
    • In the first argument of ‘last’, namely ‘Nil’
      In the expression: last Nil
      In an equation for ‘it’: it = last Nil

# 540 "srcClashSized/Vector.hs"

zip takes two vectors and returns a vector of corresponding pairs.

>>> zip (1:>2:>3:>4:>Nil) (4:>3:>2:>1:>Nil)
(1,4) :> (2,3) :> (3,2) :> (4,1) :> Nil

unzip transforms a vector of pairs into a vector of first components and a vector of second components.

>>> unzip ((1,4):>(2,3):>(3,2):>(4,1):>Nil)
(1 :> 2 :> 3 :> 4 :> Nil,4 :> 3 :> 2 :> 1 :> Nil)

Concatenate a vector of vectors.

>>> concat ((1:>2:>3:>Nil) :> (4:>5:>6:>Nil) :> (7:>8:>9:>Nil) :> (10:>11:>12:>Nil) :> Nil)
1 :> 2 :> 3 :> 4 :> 5 :> 6 :> 7 :> 8 :> 9 :> 10 :> 11 :> 12 :> Nil

unzip3 transforms a vector of triplets into a vector of first components, a vector of second components, and a vector of third components.

>>> unzip3 ((1,4,5):>(2,3,6):>(3,2,7):>(4,1,8):>Nil)
(1 :> 2 :> 3 :> 4 :> Nil,4 :> 3 :> 2 :> 1 :> Nil,5 :> 6 :> 7 :> 8 :> Nil)

The largest element of a non-empty vector

The least element of a non-empty vector

Map a function over all the elements of a vector and concatentate the resulting vectors.

>>> concatMap (replicate d3) (1:>2:>3:>Nil)
1 :> 1 :> 1 :> 2 :> 2 :> 2 :> 3 :> 3 :> 3 :> Nil

zipWith generalizes zip by zipping with the function given as the first argument, instead of a tupling function. For example, "zipWith (+)" applied to two vectors produces the vector of corresponding sums.

zipWith f (x1 :> x2 :> ... xn :> Nil) (y1 :> y2 :> ... :> yn :> Nil) == (f x1 y1 :> f x2 y2 :> ... :> f xn yn :> Nil)

"zipWith f xs ys" corresponds to the following circuit layout:

NB: zipWith is strict in its second argument, and lazy in its third. This matters when zipWith is used in a recursive setting. See lazyV for more information.

The length of a Vector as an Int value.

>>> length (6 :> 7 :> 8 :> Nil)
3

"elemIndex a xs" returns the index of the first element which is equal (by ==) to the query element a, or Nothing if there is no such element.

>>> elemIndex 3 (1:>3:>2:>4:>3:>5:>6:>Nil)
Just 1
>>> elemIndex 8 (1:>3:>2:>4:>3:>5:>6:>Nil)
Nothing

"findIndex p xs" returns the index of the first element of xs satisfying the predicate p, or Nothing if there is no such element.

>>> findIndex (> 3) (1:>3:>2:>4:>3:>5:>6:>Nil)
Just 3
>>> findIndex (> 8) (1:>3:>2:>4:>3:>5:>6:>Nil)
Nothing

Create a vector of one element

>>> singleton 5
5 :> Nil

Transpose a matrix: go from row-major to column-major

>>> let xss = (1:>2:>Nil):>(3:>4:>Nil):>(5:>6:>Nil):>Nil
>>> xss
(1 :> 2 :> Nil) :> (3 :> 4 :> Nil) :> (5 :> 6 :> Nil) :> Nil
>>> transpose xss
(1 :> 3 :> 5 :> Nil) :> (2 :> 4 :> 6 :> Nil) :> Nil

"unfoldr n f s" builds a vector of length n from a seed value s, where every element a is created by successive calls of f on s. Unlike unfoldr from Data.List the generating function f cannot dictate the length of the resulting vector, it must be statically known.

a simple use of unfoldr:

>>> unfoldr d10 (\s -> (s,s-1)) 10
10 :> 9 :> 8 :> 7 :> 6 :> 5 :> 4 :> 3 :> 2 :> 1 :> Nil

unzip4 takes a vector of quadruples and returns four vectors, analogous to unzip.

unzip5 takes a vector of five-tuples and returns five vectors, analogous to unzip.

unzip6 takes a vector of six-tuples and returns six vectors, analogous to unzip.

unzip7 takes a vector of seven-tuples and returns seven vectors, analogous to unzip.

zip4 takes four vectors and returns a list of quadruples, analogous to zip.

zip5 takes five vectors and returns a list of five-tuples, analogous to zip.

zip6 takes six vectors and returns a list of six-tuples, analogous to zip.

zip7 takes seven vectors and returns a list of seven-tuples, analogous to zip.

The mapAccumL function behaves like a combination of map and foldl; it applies a function to each element of a vector, passing an accumulating parameter from left to right, and returning a final value of this accumulator together with the new vector.

>>> mapAccumL (\acc x -> (acc + x,acc + 1)) 0 (1 :> 2 :> 3 :> 4 :> Nil)
(10,1 :> 2 :> 4 :> 7 :> Nil)

"mapAccumL f acc xs" corresponds to the following circuit layout:

The mapAccumR function behaves like a combination of map and foldr; it applies a function to each element of a vector, passing an accumulating parameter from right to left, and returning a final value of this accumulator together with the new vector.

>>> mapAccumR (\acc x -> (acc + x,acc + 1)) 0 (1 :> 2 :> 3 :> 4 :> Nil)
(10,10 :> 8 :> 5 :> 1 :> Nil)

"mapAccumR f acc xs" corresponds to the following circuit layout:

"xs !! n" returns the n'th element of xs.

NB: Vector elements have an ASCENDING subscript starting from 0 and ending at length - 1.

>>> (1:>2:>3:>4:>5:>Nil) !! 4
5
>>> (1:>2:>3:>4:>5:>Nil) !! (length (1:>2:>3:>4:>5:>Nil) - 1)
5
>>> (1:>2:>3:>4:>5:>Nil) !! 1
2
>>> (1:>2:>3:>4:>5:>Nil) !! 14
*** Exception: Clash.Sized.Vector.(!!): index 14 is larger than maximum index 4
...

"drop n xs" returns the suffix of xs after the first n elements.

>>> drop (SNat :: SNat 3) (1:>2:>3:>4:>5:>Nil)
4 :> 5 :> Nil
>>> drop d3               (1:>2:>3:>4:>5:>Nil)
4 :> 5 :> Nil
>>> drop d0               (1:>2:>Nil)
1 :> 2 :> Nil

>>> drop d4               (1:>2:>Nil)
<interactive>:...: error:...
    • Couldn't match...type ‘4 + n0...
      The type variable ‘n0’ is ambiguous
    • In the first argument of ‘print’, namely ‘it’
      In a stmt of an interactive GHCi command: print it

# 1682 "srcClashSized/Vector.hs"

Extract all the elements of a vector except the last element

>>> init (1:>2:>3:>Nil)
1 :> 2 :> Nil

>>> init Nil
<interactive>:...
    • Couldn't match type ‘1’ with ‘0’
      Expected: Vec (0 + 1) a
        Actual: Vec 0 a
    • In the first argument of ‘init’, namely ‘Nil’
      In the expression: init Nil
      In an equation for ‘it’: it = init Nil

# 587 "srcClashSized/Vector.hs"

"iterate n f x" returns a vector starting with x followed by n repeated applications of f to x.

iterate (SNat :: SNat 4) f x == (x :> f x :> f (f x) :> f (f (f x)) :> Nil)
iterate d4 f x               == (x :> f x :> f (f x) :> f (f (f x)) :> Nil)

>>> iterate d4 (+1) 1
1 :> 2 :> 3 :> 4 :> Nil

"iterate n f z" corresponds to the following circuit layout:

"repeat a" creates a vector with as many copies of a as demanded by the context.

>>> repeat 6 :: Vec 5 Int
6 :> 6 :> 6 :> 6 :> 6 :> Nil

"replicate n a" returns a vector that has n copies of a.

>>> replicate (SNat :: SNat 3) 6
6 :> 6 :> 6 :> Nil
>>> replicate d3 6
6 :> 6 :> 6 :> Nil

The elements in a vector in reverse order.

>>> reverse (1:>2:>3:>4:>Nil)
4 :> 3 :> 2 :> 1 :> Nil

scanl is similar to foldl, but returns a vector of successive reduced values from the left:

scanl f z (x1 :> x2 :> ... :> Nil) == z :> (z `f` x1) :> ((z `f` x1) `f` x2) :> ... :> Nil

>>> scanl (+) 0 (5 :> 4 :> 3 :> 2 :> Nil)
0 :> 5 :> 9 :> 12 :> 14 :> Nil

"scanl f z xs" corresponds to the following circuit layout:

• NB:

  last (scanl f z xs) == foldl f z xs

• For a different trade-off between circuit size and logic depth for associative operators, see Clash.Sized.RTree

scanl with no seed value

>>> scanl1 (-) (1 :> 2 :> 3 :> 4 :> Nil)
1 :> -1 :> -4 :> -8 :> Nil

scanr is similar to foldr, but returns a vector of successive reduced values from the right:

scanr f z (... :> xn1 :> xn :> Nil) == ... :> (xn1 `f` (xn `f` z)) :> (xn `f` z) :> z :> Nil

>>> scanr (+) 0 (5 :> 4 :> 3 :> 2 :> Nil)
14 :> 9 :> 5 :> 2 :> 0 :> Nil

"scanr f z xs" corresponds to the following circuit layout:

• NB:

  head (scanr f z xs) == foldr f z xs

• For a different trade-off between circuit size and logic depth for associative operators, see Clash.Sized.RTree

scanr with no seed value

>>> scanr1 (-) (1 :> 2 :> 3 :> 4 :> Nil)
-2 :> 3 :> -1 :> 4 :> Nil

Split a vector into two vectors at the given point.

>>> splitAt (SNat :: SNat 3) (1:>2:>3:>7:>8:>Nil)
(1 :> 2 :> 3 :> Nil,7 :> 8 :> Nil)
>>> splitAt d3 (1:>2:>3:>7:>8:>Nil)
(1 :> 2 :> 3 :> Nil,7 :> 8 :> Nil)

Extract the elements after the head of a vector

>>> tail (1:>2:>3:>Nil)
2 :> 3 :> Nil

>>> tail Nil
<interactive>:...
    • Couldn't match type ‘1’ with ‘0’
      Expected: Vec (0 + 1) a
        Actual: Vec 0 a
    • In the first argument of ‘tail’, namely ‘Nil’
      In the expression: tail Nil
      In an equation for ‘it’: it = tail Nil

# 494 "srcClashSized/Vector.hs"

"take n xs" returns the n-length prefix of xs.

>>> take (SNat :: SNat 3) (1:>2:>3:>4:>5:>Nil)
1 :> 2 :> 3 :> Nil
>>> take d3               (1:>2:>3:>4:>5:>Nil)
1 :> 2 :> 3 :> Nil
>>> take d0               (1:>2:>Nil)
Nil

>>> take d4               (1:>2:>Nil)
<interactive>:...
    • Couldn't match type ‘4 + n0’ with ‘2’
      Expected: Vec (4 + n0) a
        Actual: Vec (1 + 1) a
      The type variable ‘n0’ is ambiguous
    • In the second argument of ‘take’, namely ‘(1 :> 2 :> Nil)’
      In the expression: take d4 (1 :> 2 :> Nil)
      In an equation for ‘it’: it = take d4 (1 :> 2 :> Nil)

# 1632 "srcClashSized/Vector.hs"

zip3 takes three vectors and returns a vector of corresponding triplets.

>>> zip3 (1:>2:>3:>4:>Nil) (4:>3:>2:>1:>Nil) (5:>6:>7:>8:>Nil)
(1,4,5) :> (2,3,6) :> (3,2,7) :> (4,1,8) :> Nil

zipWith3 generalizes zip3 by zipping with the function given as the first argument, instead of a tupling function.

zipWith3 f (x1 :> x2 :> ... xn :> Nil) (y1 :> y2 :> ... :> yn :> Nil) (z1 :> z2 :> ... :> zn :> Nil) == (f x1 y1 z1 :> f x2 y2 z2 :> ... :> f xn yn zn :> Nil)

"zipWith3 f xs ys zs" corresponds to the following circuit layout:

NB: zipWith3 is strict in its second argument, and lazy in its third and fourth. This matters when zipWith3 is used in a recursive setting. See lazyV for more information.

foldl, applied to a binary operator, a starting value (typically the left-identity of the operator), and a vector, reduces the vector using the binary operator, from left to right:

foldl f z (x1 :> x2 :> ... :> xn :> Nil) == (...((z `f` x1) `f` x2) `f`...) `f` xn
foldl f z Nil                            == z

>>> foldl (/) 1 (5 :> 4 :> 3 :> 2 :> Nil)
8.333333333333333e-3

"foldl f z xs" corresponds to the following circuit layout:

NB: "foldl f z xs" produces a linear structure, which has a depth, or delay, of O(length xs). Use fold if your binary operator f is associative, as "fold f xs" produces a structure with a depth of O(log_2(length xs)).

foldl1 is a variant of foldl that has no starting value argument, and thus must be applied to non-empty vectors.

foldl1 f (x1 :> x2 :> x3 :> ... :> xn :> Nil) == (...((x1 `f` x2) `f` x3) `f`...) `f` xn
foldl1 f (x1 :> Nil)                          == x1
foldl1 f Nil                                  == TYPE ERROR

>>> foldl1 (/) (1 :> 5 :> 4 :> 3 :> 2 :> Nil)
8.333333333333333e-3

"foldl1 f xs" corresponds to the following circuit layout:

NB: "foldl1 f z xs" produces a linear structure, which has a depth, or delay, of O(length xs). Use fold if your binary operator f is associative, as "fold f xs" produces a structure with a depth of O(log_2(length xs)).

foldr1 is a variant of foldr that has no starting value argument, and thus must be applied to non-empty vectors.

foldr1 f (x1 :> ... :> xn2 :> xn1 :> xn :> Nil) == x1 `f` (... (xn2 `f` (xn1 `f` xn))...)
foldr1 f (x1 :> Nil)                            == x1
foldr1 f Nil                                    == TYPE ERROR

>>> foldr1 (/) (5 :> 4 :> 3 :> 2 :> 1 :> Nil)
1.875

"foldr1 f xs" corresponds to the following circuit layout:

NB: "foldr1 f z xs" produces a linear structure, which has a depth, or delay, of O(length xs). Use fold if your binary operator f is associative, as "fold f xs" produces a structure with a depth of O(log_2(length xs)).

fold is a variant of foldr1 and foldl1, but instead of reducing from right to left, or left to right, it reduces a vector using a tree-like structure. The depth, or delay, of the structure produced by "fold f xs", is hence O(log_2(length xs)), and not O(length xs).

NB: The binary operator "f" in "fold f xs" must be associative.

fold f (x1 :> x2 :> ... :> xn1 :> xn :> Nil) == ((x1 `f` x2) `f` ...) `f` (... `f` (xn1 `f` xn))
fold f (x1 :> Nil)                           == x1
fold f Nil                                   == TYPE ERROR

>>> fold (+) (5 :> 4 :> 3 :> 2 :> 1 :> Nil)
15

"fold f xs" corresponds to the following circuit layout:

Fixed size vectors.

• Lists with their length encoded in their type
• Vector elements have an ASCENDING subscript starting from 0 and ending at length - 1.