{"comments":"The Prim.Coerce module is embedded in the PureScript compiler. Unlike `Prim`, it is not imported implicitly. It contains an automatically solved type class for coercing types that have provably-identical runtime representations with [purescript-safe-coerce](https://pursuit.purescript.org/packages/purescript-safe-coerce).","declarations":[{"children":[],"comments":"Coercible is a two-parameter type class that has instances for types `a`\nand `b` if the compiler can infer that they have the same representation.\nCoercible constraints are solved according to the following rules:\n\n* _reflexivity_, any type has the same representation as itself:\n`Coercible a a` holds.\n\n* _symmetry_, if a type `a` can be coerced to some other type `b`, then `b`\ncan also be coerced back to `a`: `Coercible a b` implies `Coercible b a`.\n\n* _transitivity_, if a type `a` can be coerced to some other type `b` which\ncan be coerced to some other type `c`, then `a` can also be coerced to `c`:\n`Coercible a b` and `Coercible b c` imply `Coercible a c`.\n\n* Newtypes can be freely wrapped and unwrapped when their constructor is\nin scope:\n\n      newtype Age = Age Int\n\n`Coercible Int Age` and `Coercible Age Int` hold since `Age` has the same\nruntime representation than `Int`.\n\nNewtype constructors have to be in scope to preserve abstraction. It's\ncommon to declare a newtype to encode some invariants (non emptiness of\narrays with `Data.Array.NonEmpty.NonEmptyArray` for example), hide its\nconstructor and export smart constructors instead. Without this restriction,\nthe guarantees provided by such newtypes would be void.\n\n* If none of the above are applicable, two types of kind `Type` may be\ncoercible, but only if their heads are the same. For example,\n`Coercible (Maybe a) (Either a b)` does not hold because `Maybe` and\n`Either` are different. Those types don't share a common runtime\nrepresentation so coercing between them would be unsafe. In addition their\narguments may need to be identical or coercible, depending on the _roles_\nof the head's type parameters. Roles are documented in [the PureScript\nlanguage reference](https://github.com/purescript/documentation/blob/master/language/Roles.md).\n\nCoercible being polykinded, we can also coerce more than types of kind `Type`:\n\n* Rows are coercible when they have the same labels, when the corresponding\npairs of types are coercible and when their tails are coercible:\n`Coercible ( label :: a | r ) ( label :: b | s )` holds when\n`Coercible a b` and `Coercible r s` do. Closed rows cannot be coerced to\nopen rows.\n\n* Higher kinded types are coercible if they are coercible when fully\nsaturated: `Coercible (f :: _ -> Type) (g :: _ -> Type)` holds when\n`Coercible (f a) (g a)` does.\n\nThis rule may seem puzzling since there is no term of type `_ -> Type` to\napply `coerce` to, but it is necessary when coercing types with higher\nkinded parameters.\n","info":{"arguments":[["a",{"annotation":[],"contents":"k","tag":"TypeVar"}],["b",{"annotation":[],"contents":"k","tag":"TypeVar"}]],"declType":"typeClass","fundeps":[],"superclasses":[]},"kind":null,"sourceSpan":null,"title":"Coercible"}],"name":"Prim.Coerce","reExports":[]}