isomorphism-class-0.3.1.2: Isomorphism typeclass as a lawful solution to the conversion problem

Safe Haskell | None
Language | Haskell2010

IsomorphismClass

Contents

- Typeclasses
- Optics
- Testing

Description

# UX

Essentially the whole API is just two functions: `to` and `from`. Both perform a conversion between two types. The only difference between them is in what the first type application parameter specifies. E.g.:

    toText = to @Text

    fromBuilder = from @Builder

The types are self-evident:

    > :t to @Text
    to @Text :: IsomorphicTo Text b => b -> Text

    > :t from @Builder
    from @Builder :: IsomorphicTo Builder b => Builder -> b

In other words `to` and `from` let you explicitly specify either the source or the target type of a conversion when you need to help the type inferencer or the reader.

# Examples

    combineEncodings :: ShortByteString -> ByteArray -> ByteString -> [Word8]
    combineEncodings a b c =
      from @Builder $
        to a <> to b <> to c

Which is equivalent to:

    combineEncodings :: ShortByteString -> ByteArray -> ByteString -> [Word8]
    combineEncodings a b c =
      LazyByteString.unpack $
        Builder.toLazyByteString $
          mconcat
            [ Builder.shortByteString a,
              Builder.shortByteString
                ( let ByteArray.ByteArray array = b
                   in ShortByteString.SBS array
                ),
              Builder.lazyByteString c
            ]

Synopsis

- class IsomorphicTo b a => IsomorphicTo a b where
  - to :: b -> a
- from :: IsomorphicTo a b => a -> b
- isomorphicToIso :: (IsomorphicTo a b, Profunctor p, Functor f) => p b (f b) -> p a (f a)
- isomorphicToProperties :: (IsomorphicTo a b, Eq a, Eq b, Arbitrary a, Show a, Arbitrary b, Show b) => Proxy a -> Proxy b -> [(String, Property)]

# Typeclasses

class IsomorphicTo b a => IsomorphicTo a b where Source #

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 `IsomorphicTo a b` as "B is isomorphic to A".

### Laws

B is isomorphic to A if and only if there exists a conversion from B to A (`to`) and a conversion from A to B (`from`) such that:

- ``from` . `to` = `id`` - For all values of B converting from B to A and then converting from A to B produces a value that is identical to the original.
- ``to` . `from` = `id`` - For all values of A converting from A to B and then converting from B to A produces a value that is identical to the original.

### Testing

For testing whether your instances conform to these laws use `isomorphicToProperties`.

### Instance Definition

For each pair of isomorphic types (A and B) the compiler will require you to define two instances, namely: `IsomorphicTo A B` and `IsomorphicTo B A`.

Methods

to :: b -> a Source #

Convert a value into an isomophic type.

#### Instances

Instances details

IsomorphicTo ByteArray Builder Source # |
Instance details Defined in IsomorphismClass.Relations.ByteArrayAndLazyByteStringBuilder Methods to :: Builder -> ByteArray Source #
IsomorphicTo ByteArray ByteString Source # |
Instance details Defined in IsomorphismClass.Relations.ByteArrayAndByteString Methods to :: ByteString -> ByteArray Source #
IsomorphicTo ByteArray ByteString Source # |
Instance details Defined in IsomorphismClass.Relations.ByteArrayAndLazyByteString Methods to :: ByteString -> ByteArray Source #
IsomorphicTo ByteArray ShortByteString Source # |
Instance details Defined in IsomorphismClass.Relations.ByteArrayAndShortByteString Methods to :: ShortByteString -> ByteArray Source #
IsomorphicTo Pico DiffTime Source # |
Instance details Defined in IsomorphismClass.Relations.DiffTimeAndPico Methods to :: DiffTime -> Pico Source #
IsomorphicTo Pico NominalDiffTime Source # |
Instance details Defined in IsomorphismClass.Relations.NominalDiffTimeAndPico Methods to :: NominalDiffTime -> Pico Source #
IsomorphicTo Builder ByteArray Source # |
Instance details Defined in IsomorphismClass.Relations.ByteArrayAndLazyByteStringBuilder Methods to :: ByteArray -> Builder Source #
IsomorphicTo Builder ByteString Source # |
Instance details Defined in IsomorphismClass.Relations.ByteStringAndLazyByteStringBuilder Methods to :: ByteString -> Builder Source #
IsomorphicTo Builder ByteString Source # |
Instance details Defined in IsomorphismClass.Relations.LazyByteStringAndLazyByteStringBuilder Methods to :: ByteString -> Builder Source #
IsomorphicTo Builder ShortByteString Source # |
Instance details Defined in IsomorphismClass.Relations.LazyByteStringBuilderAndShortByteString Methods to :: ShortByteString -> Builder Source #
IsomorphicTo ByteString ByteArray Source # |
Instance details Defined in IsomorphismClass.Relations.ByteArrayAndByteString Methods to :: ByteArray -> ByteString Source #
IsomorphicTo ByteString Builder Source # |
Instance details Defined in IsomorphismClass.Relations.ByteStringAndLazyByteStringBuilder Methods to :: Builder -> ByteString Source #
IsomorphicTo ByteString ByteString Source # |
Instance details Defined in IsomorphismClass.Relations.ByteStringAndLazyByteString Methods to :: ByteString -> ByteString Source #
IsomorphicTo ByteString ShortByteString Source # |
Instance details Defined in IsomorphismClass.Relations.ByteStringAndShortByteString Methods to :: ShortByteString -> ByteString Source #
IsomorphicTo ByteString ByteArray Source # |
Instance details Defined in IsomorphismClass.Relations.ByteArrayAndLazyByteString Methods to :: ByteArray -> ByteString Source #
IsomorphicTo ByteString Builder Source # |
Instance details Defined in IsomorphismClass.Relations.LazyByteStringAndLazyByteStringBuilder Methods to :: Builder -> ByteString Source #
IsomorphicTo ByteString ByteString Source # |
Instance details Defined in IsomorphismClass.Relations.ByteStringAndLazyByteString Methods to :: ByteString -> ByteString Source #
IsomorphicTo ByteString ShortByteString Source # |
Instance details Defined in IsomorphismClass.Relations.LazyByteStringAndShortByteString Methods to :: ShortByteString -> ByteString Source #
IsomorphicTo ShortByteString ByteArray Source # |
Instance details Defined in IsomorphismClass.Relations.ByteArrayAndShortByteString Methods to :: ByteArray -> ShortByteString Source #
IsomorphicTo ShortByteString Builder Source # |
Instance details Defined in IsomorphismClass.Relations.LazyByteStringBuilderAndShortByteString Methods to :: Builder -> ShortByteString Source #
IsomorphicTo ShortByteString ByteString Source # |
Instance details Defined in IsomorphismClass.Relations.ByteStringAndShortByteString Methods to :: ByteString -> ShortByteString Source #
IsomorphicTo ShortByteString ByteString Source # |
Instance details Defined in IsomorphismClass.Relations.LazyByteStringAndShortByteString Methods to :: ByteString -> ShortByteString Source #
IsomorphicTo Int16 Word16 Source # |
Instance details Defined in IsomorphismClass.Relations.Int16AndWord16 Methods to :: Word16 -> Int16 Source #
IsomorphicTo Int32 Word32 Source # |
Instance details Defined in IsomorphismClass.Relations.Int32AndWord32 Methods to :: Word32 -> Int32 Source #
IsomorphicTo Int64 Word64 Source # |
Instance details Defined in IsomorphismClass.Relations.Int64AndWord64 Methods to :: Word64 -> Int64 Source #
IsomorphicTo Int8 Word8 Source # |
Instance details Defined in IsomorphismClass.Relations.Int8AndWord8 Methods to :: Word8 -> Int8 Source #
IsomorphicTo Word16 Int16 Source # |
Instance details Defined in IsomorphismClass.Relations.Int16AndWord16 Methods to :: Int16 -> Word16 Source #
IsomorphicTo Word32 Int32 Source # |
Instance details Defined in IsomorphismClass.Relations.Int32AndWord32 Methods to :: Int32 -> Word32 Source #
IsomorphicTo Word64 Int64 Source # |
Instance details Defined in IsomorphismClass.Relations.Int64AndWord64 Methods to :: Int64 -> Word64 Source #
IsomorphicTo Word8 Int8 Source # |
Instance details Defined in IsomorphismClass.Relations.Int8AndWord8 Methods to :: Int8 -> Word8 Source #
IsomorphicTo Text Builder Source # |
Instance details Defined in IsomorphismClass.Relations.LazyTextBuilderAndText Methods to :: Builder -> Text Source #
IsomorphicTo Text Text Source # |
Instance details Defined in IsomorphismClass.Relations.LazyTextAndText Methods to :: Text -> Text Source #
IsomorphicTo Text StrictBuilder Source # |
Instance details Defined in IsomorphismClass.Relations.StrictTextBuilderAndText Methods to :: StrictBuilder -> Text Source #
IsomorphicTo Builder Text Source # |
Instance details Defined in IsomorphismClass.Relations.LazyTextBuilderAndText Methods to :: Text -> Builder Source #
IsomorphicTo Builder Text Source # |
Instance details Defined in IsomorphismClass.Relations.LazyTextAndLazyTextBuilder Methods to :: Text -> Builder Source #
IsomorphicTo Builder StrictBuilder Source # |
Instance details Defined in IsomorphismClass.Relations.LazyTextBuilderAndStrictTextBuilder Methods to :: StrictBuilder -> Builder Source #
IsomorphicTo Text Text Source # |
Instance details Defined in IsomorphismClass.Relations.LazyTextAndText Methods to :: Text -> Text Source #
IsomorphicTo Text Builder Source # |
Instance details Defined in IsomorphismClass.Relations.LazyTextAndLazyTextBuilder Methods to :: Builder -> Text Source #
IsomorphicTo Text StrictBuilder Source # |
Instance details Defined in IsomorphismClass.Relations.LazyTextAndStrictTextBuilder Methods to :: StrictBuilder -> Text Source #
IsomorphicTo StrictBuilder Text Source # |
Instance details Defined in IsomorphismClass.Relations.StrictTextBuilderAndText Methods to :: Text -> StrictBuilder Source #
IsomorphicTo StrictBuilder Builder Source # |
Instance details Defined in IsomorphismClass.Relations.LazyTextBuilderAndStrictTextBuilder Methods to :: Builder -> StrictBuilder Source #
IsomorphicTo StrictBuilder Text Source # |
Instance details Defined in IsomorphismClass.Relations.LazyTextAndStrictTextBuilder Methods to :: Text -> StrictBuilder Source #
IsomorphicTo DiffTime Pico Source # |
Instance details Defined in IsomorphismClass.Relations.DiffTimeAndPico Methods to :: Pico -> DiffTime Source #
IsomorphicTo DiffTime NominalDiffTime Source # |
Instance details Defined in IsomorphismClass.Relations.DiffTimeAndNominalDiffTime Methods to :: NominalDiffTime -> DiffTime Source #
IsomorphicTo NominalDiffTime Pico Source # |
Instance details Defined in IsomorphismClass.Relations.NominalDiffTimeAndPico Methods to :: Pico -> NominalDiffTime Source #
IsomorphicTo NominalDiffTime DiffTime Source # |
Instance details Defined in IsomorphismClass.Relations.DiffTimeAndNominalDiffTime Methods to :: DiffTime -> NominalDiffTime Source #
IsomorphicTo Int Word Source # |
Instance details Defined in IsomorphismClass.Relations.IntAndWord Methods to :: Word -> Int Source #
IsomorphicTo Word Int Source # |
Instance details Defined in IsomorphismClass.Relations.IntAndWord Methods to :: Int -> Word Source #
IsomorphicTo a a Source # | Every type is isomorphic to itself.
Instance details Defined in IsomorphismClass.Classes.IsomorphicTo Methods to :: a -> a Source #
IsomorphicTo ByteArray [Word8] Source # |
Instance details Defined in IsomorphismClass.Relations.ByteArrayAndWord8List Methods to :: [Word8] -> ByteArray Source #
IsomorphicTo Builder [Word8] Source # |
Instance details Defined in IsomorphismClass.Relations.LazyByteStringBuilderAndWord8List Methods to :: [Word8] -> Builder Source #
IsomorphicTo ByteString [Word8] Source # |
Instance details Defined in IsomorphismClass.Relations.ByteStringAndWord8List Methods to :: [Word8] -> ByteString Source #
IsomorphicTo ByteString [Word8] Source # |
Instance details Defined in IsomorphismClass.Relations.LazyByteStringAndWord8List Methods to :: [Word8] -> ByteString Source #
IsomorphicTo ShortByteString [Word8] Source # |
Instance details Defined in IsomorphismClass.Relations.ShortByteStringAndWord8List Methods to :: [Word8] -> ShortByteString Source #
IsomorphicTo IntSet (Set Int) Source # |
Instance details Defined in IsomorphismClass.Relations.IntSetAndSetOfInt Methods to :: Set Int -> IntSet Source #
IsomorphicTo (Set Int) IntSet Source # |
Instance details Defined in IsomorphismClass.Relations.IntSetAndSetOfInt Methods to :: IntSet -> Set Int Source #
IsomorphicTo [Word8] ByteArray Source # |
Instance details Defined in IsomorphismClass.Relations.ByteArrayAndWord8List Methods to :: ByteArray -> [Word8] Source #
IsomorphicTo [Word8] Builder Source # |
Instance details Defined in IsomorphismClass.Relations.LazyByteStringBuilderAndWord8List Methods to :: Builder -> [Word8] Source #
IsomorphicTo [Word8] ByteString Source # |
Instance details Defined in IsomorphismClass.Relations.ByteStringAndWord8List Methods to :: ByteString -> [Word8] Source #
IsomorphicTo [Word8] ByteString Source # |
Instance details Defined in IsomorphismClass.Relations.LazyByteStringAndWord8List Methods to :: ByteString -> [Word8] Source #
IsomorphicTo [Word8] ShortByteString Source # |
Instance details Defined in IsomorphismClass.Relations.ShortByteStringAndWord8List Methods to :: ShortByteString -> [Word8] Source #
IsomorphicTo (Seq a) (Vector a) Source # |
Instance details Defined in IsomorphismClass.Relations.BoxedVectorAndSeq Methods to :: Vector a -> Seq a Source #
IsomorphicTo (Seq a) [a] Source # |
Instance details Defined in IsomorphismClass.Relations.ListAndSeq Methods to :: [a] -> Seq a Source #
IsomorphicTo (Vector a) (Seq a) Source # |
Instance details Defined in IsomorphismClass.Relations.BoxedVectorAndSeq Methods to :: Seq a -> Vector a Source #
IsomorphicTo (Vector a) [a] Source # |
Instance details Defined in IsomorphismClass.Relations.BoxedVectorAndList Methods to :: [a] -> Vector a Source #
IsomorphicTo [a] (Seq a) Source # |
Instance details Defined in IsomorphismClass.Relations.ListAndSeq Methods to :: Seq a -> [a] Source #
IsomorphicTo [a] (Vector a) Source # |
Instance details Defined in IsomorphismClass.Relations.BoxedVectorAndList Methods to :: Vector a -> [a] Source #
IsomorphicTo (IntMap v) (Map Int v) Source # |
Instance details Defined in IsomorphismClass.Relations.IntMapAndMapOfInt Methods to :: Map Int v -> IntMap v Source #
IsomorphicTo (Map Int v) (IntMap v) Source # |
Instance details Defined in IsomorphismClass.Relations.IntMapAndMapOfInt Methods to :: IntMap v -> Map Int v Source #

from :: IsomorphicTo a b => a -> b Source #

`to` in reverse direction.

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

    fromText :: IsomorphicTo Text b => Text -> b
    fromText = from @Text

The first type application of the `to` function on the other hand specifies the output data type.

# Optics

isomorphicToIso :: (IsomorphicTo a b, Profunctor p, Functor f) => p b (f b) -> p a (f a) Source #

Van-Laarhoven-style Isomorphism, compatible with the "lens" library.

# Testing

isomorphicToProperties :: (IsomorphicTo a b, Eq a, Eq b, Arbitrary a, Show a, Arbitrary b, Show b) => Proxy a -> Proxy b -> [(String, Property)] Source #

Properties testing whether an instance satisfies the laws of `IsomorphicTo`.

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 "IsomorphicTo laws" do
        traverse_
          (uncurry prop)
          (isomorphicToProperties @Int32 @Word32 Proxy Proxy)