:: Natural -> Nat -package:ghc-internal

Convert Natural to Nat

>>> fromNatural 4
4

>>> explicitShow (fromNatural 4)
"S (S (S (S Z)))"

Indicate if the value is a power of two and which one

Try downcasting Natural to Word value. Returns (##) if value doesn't fit in Word.

convert a Natural to any numeric type a

Calculate the frequency in Hz, given the period in ps I.e., to calculate the clock frequency of a clock with a period of 5000 ps:

>>> periodToHz 5000
2.0e8

Note that if p in periodToHz (fromIntegral p) is negative, fromIntegral will give an Underflow :: ArithException without a call stack, making debugging cumbersome. Before Clash 1.8, this function always returned a Ratio Natural. To get the old behavior of this function, use a type application:

>>> periodToHz @(Ratio Natural) 5000
200000000 % 1

NB: This function is not synthesizable

Generically generate a Semiring fromNatural for any product-like type implementing Generic. It is only defined for product types.

unsafeCoerce coerces a value from one type to another, bypassing the type-checker. There are several legitimate ways to use unsafeCoerce:

1. To coerce a lifted type such as Int to Any, put it in a list of Any, and then later coerce it back to Int before using it.
2. To produce e.g. (a+b) :~: (b+a) from unsafeCoerce Refl. Here the two sides really are the same type -- so nothing unsafe is happening -- but GHC is not clever enough to see it.
3. In Data.Typeable we have

eqTypeRep :: forall k1 k2 (a :: k1) (b :: k2).
TypeRep a -> TypeRep b -> Maybe (a :~~: b)
eqTypeRep a b
| sameTypeRep a b = Just (unsafeCoerce HRefl)
| otherwise       = Nothing

Here again, the unsafeCoerce HRefl is safe, because the two types really are the same -- but the proof of that relies on the complex, trusted implementation of Typeable.

1. (superseded) The "reflection trick", which takes advantage of the fact that in class C a where { op :: ty }, we can safely coerce between C a and ty (which have different kinds!) because it's really just a newtype. Note: there is no guarantee, at all that this behavior will be supported into perpetuity. It is now preferred to use withDict in GHC.Magic.Dict, which is type-safe. See Note [withDict] in GHC.Tc.Instance.Class for details.
2. (superseded) Casting between two types which have exactly the same structure: between a newtype of T and T, or between types which differ only in "phantom" type parameters. It is now preferred to use coerce from Data.Coerce, which is type-safe.

Other uses of unsafeCoerce are undefined. In particular, you should not use unsafeCoerce to cast a T to an algebraic data type D, unless T is also an algebraic data type. For example, do not cast Int->Int to Bool, even if you later cast that Bool back to Int->Int before applying it. The reasons have to do with GHC's internal representation details (for the cognoscenti, data values can be entered but function closures cannot). If you want a safe type to cast things to, use Any, which is not an algebraic data type.

Highly, terribly dangerous coercion from one representation type to another. Misuse of this function can invite the garbage collector to trounce upon your data and then laugh in your face. You don't want this function. Really. This becomes more obvious when looking at its actual type: forall (r1 :: RuntimeRep) (r2 :: RuntimeRep) (a :: TYPE r1) (b :: TYPE r2). a -> b Which often get's rendered as a -> b in haddock for technical reasons.

Highly, terribly dangerous coercion from one representation type to another. Misuse of this function can invite the garbage collector to trounce upon your data and then laugh in your face. You don't want this function. Really.

Coerce a value from one type to another, bypassing the type-checker. There are several legitimate ways to use unsafeCoerce:

1. To coerce e.g. Int to HValue, put it in a list of HValue, and then later coerce it back to Int before using it.
2. To produce e.g. (a+b) :~: (b+a) from unsafeCoerce Refl. Here the two sides really are the same type -- so nothing unsafe is happening -- but GHC is not clever enough to see it.
3. In Data.Typeable we have

eqTypeRep :: forall k1 k2 (a :: k1) (b :: k2).
TypeRep a -> TypeRep b -> Maybe (a :~~: b)
eqTypeRep a b
| sameTypeRep a b = Just (unsafeCoerce HRefl)
| otherwise       = Nothing

Here again, the unsafeCoerce HRefl is safe, because the two types really are the same -- but the proof of that relies on the complex, trusted implementation of Typeable.

1. The "reflection trick", which takes advantage of the fact that in class C a where { op :: ty }, we can safely coerce between C a and ty (which have different kinds!) because it's really just a newtype. Note: there is no guarantee, at all that this behavior will be supported into perpetuity.

Coerce a value from one type to another, bypassing the type-checker. There are several legitimate ways to use unsafeCoerce:

1. To coerce e.g. Int to HValue, put it in a list of HValue, and then later coerce it back to Int before using it.
2. To produce e.g. (a+b) :~: (b+a) from unsafeCoerce Refl. Here the two sides really are the same type -- so nothing unsafe is happening -- but GHC is not clever enough to see it.
3. In Data.Typeable we have

eqTypeRep :: forall k1 k2 (a :: k1) (b :: k2).
TypeRep a -> TypeRep b -> Maybe (a :~~: b)
eqTypeRep a b
| sameTypeRep a b = Just (unsafeCoerce HRefl)
| otherwise       = Nothing

Here again, the unsafeCoerce HRefl is safe, because the two types really are the same -- but the proof of that relies on the complex, trusted implementation of Typeable.

1. The "reflection trick", which takes advantage of the fact that in class C a where { op :: ty }, we can safely coerce between C a and ty (which have different kinds!) because it's really just a newtype. Note: there is no guarantee, at all that this behavior will be supported into perpetuity.

For safe zero-cost coercions you can instead use the coerce function from Data.Coerce.

Deliberately do not add a header to a value.

>>> let example1 = noHeader "hi" :: Headers '[Header "someheader" Int] String

>>> getHeaders example1
[]

toFields provides a convenient typeclass wrapper around the Field_ creation functions in Opaleye.SqlTypes. Besides convenience it doesn't provide any additional functionality. It can be used with functions like runInsert to insert custom Haskell types into the database. The following is an example of a function for inserting custom types.

customInsert
:: ( Default ToFields haskells fields )
=> Connection
-> Table fields fields'
-> [haskells]
-> IO Int64
customInsert conn table haskells = runInsert_ conn Insert {
iTable      = table
, iRows       = map toFields haskells
, iReturning  = rCount
, iOnConflict = Nothing
}

In order to use this function with your custom types, you need to define an instance of Default ToFields for your custom types.