docs.json

{"reExports":[],"name":"Prim.Coerce","comments":"The Prim.Coerce module is embedded in the PureScript compiler. Unlike `Prim`, it is not imported implicitly. It contains automatically solved type classes for working with types that have provably-identical runtime representations.","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.\nThis class does not have regular instances; instead they are created\non-the-fly during type-checking according to a set of rules.\n\nFirst, Coercible obeys reflexivity - any type has the same representation\nas itself:\n\n    instance coercibleReflexive :: Coercible a a\n\nSecond, Coercible obeys symmetry - if a type `a` can be coerced to some\nother type `b`, then `b` can also be coerced back to `a`:\n\n    instance coercibleSymmetric :: Coercible a b => Coercible b a\n\nThird, Coercible obeys transitivity - if a type `a` can be coerced to some\nother type `b` which can be coerced to some other type `c`, then `a` can\nalso be coerced to `c`:\n\n    instance coercibleTransitive :: (Coercible a b, Coercible b c) => Coercible a c\n\nFourth, for every type constructor there is an instance that allows one\nto coerce under the type constructor (`data` or `newtype`). For example,\ngiven a definition:\n\ndata D a b = D a\n\nthere is an instance:\n\n    instance coercibleConstructor :: Coercible a a' => Coercible (D a b) (D a' b')\n\nNote that, since the type variable `a` plays a role in `D`'s representation,\nwe require that the types `a` and `a'` are themselves `Coercible`. However,\nsince the variable `b` does not play a part in `D`'s representation (a type\nsuch as `b` is thus typically referred to as a \"phantom\" type), `b` and `b'`\ncan differ arbitrarily.\n\nFifth, for every `newtype NT = MkNT T`, there is a pair of instances which\npermit coercion in and out of the `newtype`:\n\n    instance coercibleNewtypeLeft  :: Coercible a T => Coercible a NT\n    instance coercibleNewtypeRight :: Coercible T b => Coercible NT b\n\nTo prevent breaking abstractions, these instances are only usable if the\nconstructor `MkNT` is in scope.\n\nSixth, every pair of unsaturated type constructors can be coerced if\nthere is an instance for the fully saturated types. For example,\ngiven the definitions:\n\nnewtype NT1 a = MkNT1 a\nnewtype NT2 a b = MkNT2 b\n\nthere is an instance:\n\n    instance coercibleUnsaturedTypes :: Coercible (NT1 b) (NT2 a b) => Coercible NT1 (NT2 a)\n\nThis rule may seem puzzling since it is impossible to apply `coerce` to a term\nof type `NT1` but it is necessary to coerce types with higher kinded parameters.\n\nSeventh, every pair of rows can be coerced if they have the same labels,\nthe corresponding types for each label and their tails are coercible:\n\n    instance coercibleRow :: (Coercible a b, Coercible r s) => Coercible ( label :: a | r ) ( label :: b | s )\n\nClosed rows can't be coerced to open rows.\n","title":"Coercible","info":{"fundeps":[],"arguments":[["a",{"annotation":[],"tag":"TypeVar","contents":"k"}],["b",{"annotation":[],"tag":"TypeVar","contents":"k"}]],"declType":"typeClass","superclasses":[]},"sourceSpan":null}]}