Evidence that all values of type b form a subset of all values of type a.

From Wikipedia:

In mathematics, a set A is a subset of a set B if all elements of A are also elements of B; B is then a superset of A. It is possible for A and B to be equal; if they are unequal, then A is a proper subset of B. The relationship of one set being a subset of another is called inclusion (or sometimes containment). A is a subset of B may also be expressed as B includes (or contains) A or A is included (or contained) in B. A k-subset is a subset with k elements.

Laws

to is injective

For every two values of type b that are not equal converting with to produces values that are not equal as well:

\(b1, b2) -> b1 == b2 || to @a b1 /= to @a b2

maybeFrom is a partial inverse of to

For all values of b converting to a and then attempting to convert back to b always succeeds and produces a value that is equal to the original:

\b -> maybeFrom (to @a b) == Just b

maybeFrom characterizes the image of to

maybeFrom succeeds exactly on values that are in the image of to:

\a b -> maybeFrom a == Just b ==> to b == a

Mathematical foundation

These laws establish that type b forms a subset of type a in the mathematical sense. The to function provides the canonical injection, while maybeFrom recognizes which values of a correspond to values from the subset b.

Testing

For testing whether your instances conform to these laws use isSomeProperties.

Lossy or canonicalizing conversion. Captures mappings from multiple alternative inputs into one output.

E.g.,

• ByteString can be decoded into Text with UTF-8 leniently, replacing the invalid chars with a default char.
• String has a wider range of supported chars than Text, so some chars get replaced too.

Laws

onfrom is an inverse of to

\b -> b == onfrom (to @a b)

onfrom is surjective

Every value of type b can be obtained by applying onfrom to some value of type a:

\b -> exists a. onfrom @a @b a == b

Note: This property cannot be directly tested with QuickCheck as it requires existential quantification.

Law hierarchy

IsMany extends IsSome, so all laws from IsSome also apply here. The combination ensures that onfrom provides a canonical (possibly lossy) conversion from a to b, while to provides the lossless injection from b to a.

Testing

For testing whether your instances conform to these laws use isManyProperties.

Bidirectional conversion between two types with no loss of information.

The bidirectionality is encoded via a recursive dependency with arguments flipped.

You can read the signature Is a b as "B is A".

Laws

from is an inverse of to

For all values of b converting from b to a and then converting from a to b produces the original value:

\b -> b == from @a (to @a b)

to is an inverse of from

For all values of a converting from a to b and then converting from b to a produces the original value:

\a -> a == to @a (from @a @b a)

Mathematical relationship

These two laws together establish that to and from form a true isomorphism between types a and b. Note that from is implemented as to from the reverse Is instance, ensuring the symmetry required for isomorphisms.

from equals onfrom

For isomorphic types, both ways of converting should be equivalent:

\a -> from @a @b a == onfrom @a @b a

Testing

For testing whether your instances conform to these laws use isProperties.

Instance Definition

For each pair of isomorphic types (A and B) the compiler will require you to define six instances, namely: Is A B and Is B A, IsMany A B and IsMany B A, IsSome A B and IsSome B A.

Instances of Is do not define any functions and serve merely as a statement that the laws are satisfied.

Example: Lazy Text and Text

instance IsSome Data.Text.Lazy.LazyText Data.Text.Text where
  to = LazyText.fromStrict

instance IsSome Data.Text.Text Data.Text.Lazy.LazyText where
  to = LazyText.toStrict

instance IsMany Data.Text.Lazy.LazyText Data.Text.Text

instance IsMany Data.Text.Text Data.Text.Lazy.LazyText

instance Is Data.Text.Lazy.LazyText Data.Text.Text

instance Is Data.Text.Text Data.Text.Lazy.LazyText

Convert a value of a subset type to a superset type, specifying the source subset type first.

Alias to to with the only difference in the argument order.

E.g.,

fromText = from @Text

Try to convert a value of a superset type to a subset type specifying the target subset type first.

Alias to maybeFrom with the only difference in the argument order.

Particularly useful in combination with the TypeApplications extension, where it allows to specify the target type, e.g.:

maybeToInt16 :: Int32 -> Maybe Int16
maybeToInt16 = maybeTo @Int16

percent = maybeTo @Percent someDouble

Like maybeFrom, but returns an Either with the provided error on failure.

Useful for raising custom errors when conversion fails.

Alias to tryFrom, which lets you specify the target type of the conversion first using TypeApplications.

Alias to onfrom, which lets you specify the target type of the conversion first using TypeApplications.

In mathematics onto is another name for Surjective function.

E.g.,

lenientDecodeUtf8 = onto @Text

combineTexts :: Text -> ByteString -> Int -> Text
combineTexts name email height =
  from @StrictTextBuilder $
    "Height of " <> to name <> " is " <> onto (show height) <> " and email is " <> onto email

Van-Laarhoven-style Prism, compatible with libraries like "lens" and "optics".

Van-Laarhoven-style Isomorphism, compatible with libraries like "lens" and "optics".

Van-Laarhoven-style Isomorphism, compatible with libraries like "lens" and "optics".

Helper for deriving common instances on types which have an instance of IsSome a using the DerivingVia extension.

E.g.,

newtype Percent = Percent Double
  deriving newtype (Show, Eq, Ord)
  deriving (Read, Arbitrary) via (ViaIsSome Double Percent)

instance IsSome Double Percent where
  to (Percent double) = double
  maybeFrom double =
    if double < 0 || double > 1
      then Nothing
      else Just (Percent double)

In the code above all the instances that are able to construct the values of Percent are automatically derived based on the IsSome Double Percent instance. This guarantees that they only construct values that pass thru the checks defined in maybeFrom.

Properties testing whether an instance satisfies the laws of IsSome.

The instance is identified via the proxy types that you provide.

E.g., here's how you can integrate it into an Hspec test-suite:

spec = do
  describe "IsSome laws" do
    traverse_
      (uncurry prop)
      (isSomeProperties @Int32 @Int16 Proxy Proxy)

Properties testing whether an instance satisfies the laws of IsMany.

The instance is identified via the proxy types that you provide.

E.g., here's how you can integrate it into an Hspec test-suite:

spec = do
  describe "IsMany laws" do
    traverse_
      (uncurry prop)
      (isManyProperties @String @Text Proxy Proxy)

Properties testing whether an instance satisfies the laws of Is.

The instance is identified via the proxy types that you provide.

E.g., here's how you can integrate it into an Hspec test-suite:

spec = do
  describe "Is laws" do
    traverse_
      (uncurry prop)
      (isProperties @Int32 @Word32 Proxy Proxy)