Documentation

Sub a b witnesses a zero-cost conversion a -> b.

Sub is a newtype wrapper around Coercion, but made opaque to hide the ability to coerce into other direction.

This is convenient for newtype wrappers which give additional guarantees.

As an example, think about the following code:

-- | A pair @(x::a, y::a)@, but guaranteed @x <= y@
newtype Range a = MkRange (a,a)

getRange :: Range a -> (a,a)
getRange = coerce
mkRange :: Ord a => a -> a -> Range a
mkRange x y = if x <= y then MkRange (x,y) else MkRange (y,x)

If you want to provide this type from a library you maintain, you would want to keep Range abstract from outside of the module.

An user may want to convert [Range a] to [(a,a)] without actually traversing the list. This is possible if the user have access to the internals, or you export a Coercion (Range a) (a,a) value. But doing so breaks the guarantee, because it also allows to use Coercible in the other direction, as in coerce (10,5) :: Range Int.

By exporting only Sub (Range a) (a,a) value from your module, this user can get Sub [Range a] [(a,a)] using mapR, without being able to make an invalid value.