Coercible is a two-parameter class that has instances for types a and b if the compiler can infer that they have the same representation. This class does not have regular instances; instead they are created on-the-fly during type-checking. Trying to manually declare an instance of Coercible is an error.

Nevertheless one can pretend that the following three kinds of instances exist. First, as a trivial base-case:

instance Coercible a a

Furthermore, for every type constructor there is an instance that allows to coerce under the type constructor. For example, let D be a prototypical type constructor (data or newtype) with three type arguments, which have roles nominal, representational resp. phantom. Then there is an instance of the form

instance Coercible b b' => Coercible (D a b c) (D a b' c')

Note that the nominal type arguments are equal, the representational type arguments can differ, but need to have a Coercible instance themself, and the phantom type arguments can be changed arbitrarily.

The third kind of instance exists for every newtype NT = MkNT T and comes in two variants, namely

instance Coercible a T => Coercible a NT

instance Coercible T b => Coercible NT b

This instance is only usable if the constructor MkNT is in scope.

If, as a library author of a type constructor like Set a, you want to prevent a user of your module to write coerce :: Set T -> Set NT, you need to set the role of Set's type parameter to nominal, by writing

type role Set nominal

For more details about this feature, please refer to Safe Coercions by Joachim Breitner, Richard A. Eisenberg, Simon Peyton Jones and Stephanie Weirich.

Since: ghc-prim-0.4.0

Unsafely create a dictionary for any constraint.

Coerce a dictionary unsafely from one type to another

Coerce a dictionary unsafely from one type to a newtype of that type

Coerce a dictionary unsafely from a newtype of a type to the base type

Unsafely create an SChar value directly from a Char. Use this function with care:

• The Char value must match the Char c encoded in the return type SChar c.
• Be wary of using this function to create multiple values of type SChar T, where T is a type family that does not reduce (e.g., Any from GHC.Exts). If you do, GHC is liable to optimize away one of the values and replace it with the other during a common subexpression elimination pass. If the two values have different underlying Char values, this could be disastrous.

Unsafely create an SNat value directly from a Natural. Use this function with care:

• The Natural value must match the Nat n encoded in the return type SNat n.
• Be wary of using this function to create multiple values of type SNat T, where T is a type family that does not reduce (e.g., Any from GHC.Exts). If you do, GHC is liable to optimize away one of the values and replace it with the other during a common subexpression elimination pass. If the two values have different underlying Natural values, this could be disastrous.

Unsafely create an SSymbol value directly from a String. Use this function with care:

• The String value must match the Symbol s encoded in the return type SSymbol s.
• Be wary of using this function to create multiple values of type SSymbol T, where T is a type family that does not reduce (e.g., Any from GHC.Exts). If you do, GHC is liable to optimize away one of the values and replace it with the other during a common subexpression elimination pass. If the two values have different underlying String values, this could be disastrous.