:: a -> a

Identity function.

id x = x

This function might seem useless at first glance, but it can be very useful in a higher order context.

Examples

>>> length $ filter id [True, True, False, True]
3

>>> Just (Just 3) >>= id
Just 3

>>> foldr id 0 [(^3), (*5), (+2)]
1000

The call inline f arranges that f is inlined, regardless of its size. More precisely, the call inline f rewrites to the right-hand side of f's definition. This allows the programmer to control inlining from a particular call site rather than the definition site of the function (c.f. INLINE pragmas). This inlining occurs regardless of the argument to the call or the size of f's definition; it is unconditional. The main caveat is that f's definition must be visible to the compiler; it is therefore recommended to mark the function with an INLINABLE pragma at its definition so that GHC guarantees to record its unfolding regardless of size. If no inlining takes place, the inline function expands to the identity function in Phase zero, so its use imposes no overhead.

The call noinline f arranges that f will not be inlined. It is removed during CorePrep so that its use imposes no overhead (besides the fact that it blocks inlining.)

The lazy function restrains strictness analysis a little. The call lazy e means the same as e, but lazy has a magical property so far as strictness analysis is concerned: it is lazy in its first argument, even though its semantics is strict. After strictness analysis has run, calls to lazy are inlined to be the identity function. This behaviour is occasionally useful when controlling evaluation order. Notably, lazy is used in the library definition of par:

par :: a -> b -> b
par x y = case (par# x) of _ -> lazy y

If lazy were not lazy, par would look strict in y which would defeat the whole purpose of par.

Identity function.

id x = x

Bring all regular text in a pandoc structure to uppercase. This function correctly handles cases where a lowercase character doesn't match to a single uppercase character – e.g. “Straße” would be converted to “STRASSE”, not “STRAßE”.

The identity function, returns the give value unchanged.

Renamed version of id.

>>> identity 10
10

>>> fmap identity [1,2,3]
[1,2,3]

Force deduplication, i.e. share a function or operator between multiple branches. By default Clash converts

case x of
A -> 3 * y
B -> x * x

to

let f_arg0 = case x of {A -> 3; _ -> x}
f_arg1 = case x of {A -> y; _ -> x}
f_out  = f_arg0 * f_arg1
in  case x of
A -> f_out
B -> f_out

However, it won't do this for:

case x of
A -> 3 + y
B -> x + x

Because according to the internal heuristics the multiplexer introduced for the deduplication are more expensive than the addition. This might not be the case for your particular platform. In these cases you can force Clash to deduplicate by:

case x of
A -> deDup (3 + y)
B -> deDup (x + x)

Do not deduplicate, i.e. keep, an applied function inside a case-alternative; do not try to share the function between multiple branches. By default Clash converts

case x of
A -> f 3 y
B -> f x x
C -> h x

to

let f_arg0 = case x of {A -> 3; _ -> x}
f_arg1 = case x of {A -> y; _ -> x}
f_out  = f f_arg0 f_arg1
in  case x of
A -> f_out
B -> f_out
C -> h x

i.e. it deduplicates functions (and operators such as multiplication) between case-alternatives to save on area. This comes at the cost of multiplexing the arguments for the deduplicated function. There are two reasons you would want to stop Clash from doing this:

1. The deduplicated function is in the critical path, and the addition of the multiplexers further increased the propagation delay.
2. Clash's heuristics were off, and the addition of the multiplexers actually made the final circuit larger instead of smaller.

In these cases you want to tell Clash not to deduplicate:

case x of
A -> noDeDup f 3 y
B -> f x x
C -> h x

Where the application of f in the A-alternative is now explicitly not deduplicated, and given that the f in the B-alternative is the only remaining application of f in the case-expression it is also not deduplicated. Note that if the C-alternative also had an application of f, then the applications of f in the B- and C-alternatives would have been deduplicated; i.e. the final circuit would have had two application of f.

Convert XException to ErrorCall This is useful when tracking the source of XException that gets eaten up by pack inside of your circuit; since pack translates XException into undefined bits. So for example if you have some large function f:

f a b = ... pack a ... pack b ...

Where it is basically an error if either a or b ever throws an XException, and so you want that to be reported the moment a or b is used, instead of it being thrown when evaluating the result of f, then do:

{-# LANGUAGE ViewPatterns #-}
f (xToError -> a) (xToError -> b) = ...

Unlike xToErrorCtx, where we have an extra String argument to distinguish one call to xToError to the other, xToError will use the CallStack mechanism to aid the user in distinguishing different call to xToError. We can also use BangPatterns to report the potential XException being thrown by a or b even earlier, i.e. when f is applied:

{-# LANGUAGE ViewPatterns, BangPatterns #-}
f (xToError -> !a) (xToError -> !b) = ...

NB: Fully synthesizable, so doesn't have to be removed before synthesis

Example

>>> :set -XViewPatterns -XDataKinds

>>> import Clash.Sized.BitVector

>>> import GHC.Stack

>>> :{
let f, g, h, h' :: HasCallStack => Bit -> BitVector 8 -> BitVector 8
f = g
g = h
h (xToError -> a) (xToError -> b) = slice d7 d0 (pack a ++# b)
h' a b = slice d7 d0 (pack a ++# b)
:}

>>> h' (errorX "QQ") 3
0b0000_0011

>>> f (errorX "QQ") 3
*** Exception: CallStack (from HasCallStack):
xToError, called at ...
h, called at ...
g, called at ...
f, called at ...
X: QQ
CallStack (from HasCallStack):
errorX, called at ...

When ghc-debug support has been built into the program and enabled at runtime with --debug=-N, this calls ghc-debug's withGhcDebug; otherwise it's a no-op.

Identity function.

id x = x

Like traceShowId, but using anythingToString

Sets a breakpoint in pure code

When evaluated, displays the names of variables visible from the callsite and starts a prompt where entering a variable will display its value. You may want to use this instead of breakpoint if there are value which should stay unevaluated or you are only interested in certain values. Only the current thread is blocked while the prompt is active. To resume execution, press enter with a blank prompt.

A default view function used when expression antiquotes are empty, or when pattern antiquotes omit a view pattern. See the documentation for rexPreprocessPat and rexPreprocessExp for more details. You can locally shadow this rexView with your own version, if you wish. One good option is readMay from the safe package: http://hackage.haskell.org/package/safe/docs/Safe.html#v:readMay. The type of this identity rexView is fully polymorphic so that it can be used with either String or ByteString.