-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Convert values from one type into another.
--   
--   Witch converts values from one type into another.
@package witch
@version 0.0.0.2


-- | This module provides the <a>From</a> type class for converting values
--   between various types. This aims to be a common interface for the
--   various <tt>xToY</tt> or <tt>yFromX</tt> functions you might write
--   instead. It is inspired by the <tt>std::convert::From</tt> trait that
--   the Rust programming language provides.
--   
--   Many Haskell libraries already provide similar functionality. Here's
--   how this module compares to them:
--   
--   <ul>
--   
--   <li><a>https://hackage.haskell.org/package/base-4.14.0.0/docs/Data-Coerce.html</a>:
--   This type class is convenient because it's automatically inferred by
--   the compiler, but it only works for types that have the same runtime
--   representation.</li>
--   
--   <li><a>https://hackage.haskell.org/package/convertible-1.1.1.0/docs/Data-Convertible-Base.html</a>:
--   This type class allows for conversions to fail.</li>
--   
--   <li><a>https://hackage.haskell.org/package/basement-0.0.11/docs/Basement-From.html</a>:
--   This type class is essentially the same, but the <tt>basement</tt>
--   package is an alternative standard library that some people may not
--   want to depend on.</li>
--   
--   <li><a>https://hackage.haskell.org/package/inj-base-0.2.0.0/docs/Inj-Base.html</a>:
--   This type class requires conversions to be injective, as opposed to
--   merely suggesting it. Also some conversions fail at runtime.</li>
--   
--   <li><a>https://github.com/mbj/conversions/blob/6ac6c52/src/Data/Conversions/FromType.hs</a>:
--   This type class comes with many convenient helper functions, but some
--   of the provided instances fail at runtime.</li>
--   
--   <li><a>https://github.com/kframework/kore/blob/626f230/kore/src/From.hs</a>:
--   This package is not available on Hackage, but otherwise is very
--   similar to this one.</li>
--   </ul>
module Witch

-- | This type class represents a way to convert values from some type into
--   another type. The constraint <tt>From a b</tt> means that you can
--   convert from a value of type <tt>a</tt> into a value of type
--   <tt>b</tt>.
--   
--   This is primarily intended for "zero cost" conversions like
--   <tt>newtype</tt>s. For example if you wanted to have a type to
--   represent someone's name, you could say:
--   
--   <pre>
--   newtype Name = Name String
--   instance From String Name
--   instance From Name String
--   </pre>
--   
--   And then you could convert back and forth between <tt>Name</tt>s and
--   <tt>String</tt>s:
--   
--   <pre>
--   let someString = "Taylor"
--   let someName = Name someString
--   into @Name someString -- convert from string to name
--   into @String someName -- convert from name to string
--   </pre>
--   
--   This type class does not have any laws, but it does have some
--   expectations:
--   
--   <ul>
--   <li>Conversions should be total. A conversion should never fail or
--   crash. Avoid writing instances like <tt>From Int (Maybe Char)</tt>.
--   (It might be worthwhile to have a separate <tt>TryFrom</tt> type class
--   for this.)</li>
--   <li>Conversions should be unambiguous. For example there are many ways
--   to decode a <tt>ByteString</tt> into <tt>Text</tt>, so you shouldn't
--   provide an instance for that.</li>
--   <li>Conversions should be cheap, ideally free. For example converting
--   from <tt>String</tt> to <tt>Text</tt> is probably fine, but converting
--   from a UTF-8 encoded <tt>ByteString</tt> to <tt>Text</tt> is
--   problematic.</li>
--   <li>Conversions should be lossless. In other words if you have
--   <tt>From a b</tt> then no two <tt>a</tt> values should be converted to
--   the same <tt>b</tt> value. For example <tt>From Int Integer</tt> is
--   fine because every <tt>Int</tt> can be mapped to a corresponding
--   <tt>Integer</tt>, but <tt>From Integer Int</tt> is not good because
--   some <tt>Integer</tt>s are out of bounds and would need to be
--   clamped.</li>
--   <li>If you have both <tt>From a b</tt> and <tt>From b a</tt>, then
--   <tt>from . from</tt> should be the same as <a>id</a>. In other words
--   <tt>a</tt> and <tt>b</tt> are isomorphic.</li>
--   <li>If you have both <tt>From a b</tt> and <tt>From b c</tt>, then
--   it's up to you if you want to provide <tt>From a c</tt>. Sometimes
--   using <a>via</a> is ergonomic enough, other times you want the extra
--   instance. (It would be nice if we could provide <tt>instance (From a
--   b, From b c) =&gt; From a c where from = via @b</tt>.)</li>
--   </ul>
class From a b

-- | This method converts a value from one type into another. This is
--   intended to be used with the <tt>TypeApplications</tt> language
--   extension. For example, here are a few ways to convert from an
--   <a>Int</a> into an <a>Integer</a>:
--   
--   <pre>
--   from @Int @Integer 123
--   from @_ @Integer (123 :: Int)
--   from @Int @_ 123 :: Integer
--   from @Int 123 :: Integer
--   from (123 :: Int) :: Integer
--   </pre>
--   
--   Often the context around an expression will make the explicit type
--   signatures unnecessary. If you find yourself using a partial type
--   signature, consider using <a>into</a> instead. For example:
--   
--   <pre>
--   let someInt = 123 :: Int
--   from @_ @Integer someInt -- avoid this
--   into @Integer someInt -- prefer this
--   </pre>
--   
--   The default implementation of <a>from</a> simply calls <a>coerce</a>,
--   which works for types that have the same runtime representation.
from :: From a b => a -> b

-- | This method converts a value from one type into another. This is
--   intended to be used with the <tt>TypeApplications</tt> language
--   extension. For example, here are a few ways to convert from an
--   <a>Int</a> into an <a>Integer</a>:
--   
--   <pre>
--   from @Int @Integer 123
--   from @_ @Integer (123 :: Int)
--   from @Int @_ 123 :: Integer
--   from @Int 123 :: Integer
--   from (123 :: Int) :: Integer
--   </pre>
--   
--   Often the context around an expression will make the explicit type
--   signatures unnecessary. If you find yourself using a partial type
--   signature, consider using <a>into</a> instead. For example:
--   
--   <pre>
--   let someInt = 123 :: Int
--   from @_ @Integer someInt -- avoid this
--   into @Integer someInt -- prefer this
--   </pre>
--   
--   The default implementation of <a>from</a> simply calls <a>coerce</a>,
--   which works for types that have the same runtime representation.
from :: (From a b, Coercible a b) => a -> b

-- | This function converts a value from one type into another. This is the
--   same as <a>from</a> except that the type variables are in the opposite
--   order.
into :: forall b a. From a b => a -> b

-- | This function converts a value from one type into another by going
--   through some third type. This is the same as calling <a>from</a> (or
--   <a>into</a>) twice, but can sometimes be more convenient.
--   
--   Note that the type in the middle of the conversion is the first type
--   variable of this function. In other words, <tt>via @b @a @c</tt> first
--   converts from <tt>a</tt> to <tt>b</tt>, and then from <tt>b</tt> to
--   <tt>c</tt>. Often both <tt>a</tt> and <tt>c</tt> will be inferred from
--   context, which means you can just write <tt>via @b</tt>.
via :: forall b a c. (From a b, From b c) => a -> c
instance Witch.From a a
instance Witch.From a (x -> a)
instance Witch.From a [a]
instance Witch.From a (GHC.Maybe.Maybe a)
instance Witch.From a (Data.Either.Either a x)
instance Witch.From a (Data.Either.Either x a)
instance Witch.From Data.Void.Void x
instance Witch.From (a, x) a
instance Witch.From (x, a) a
instance Witch.From (a, b) (b, a)
instance Witch.From (GHC.Base.NonEmpty a) [a]
instance Witch.From GHC.Word.Word8 GHC.Word.Word16
instance Witch.From GHC.Word.Word16 GHC.Word.Word32
instance Witch.From GHC.Word.Word32 GHC.Word.Word64
instance Witch.From GHC.Types.Word GHC.Natural.Natural
instance Witch.From GHC.Natural.Natural GHC.Integer.Type.Integer
instance Witch.From GHC.Int.Int8 GHC.Int.Int16
instance Witch.From GHC.Int.Int16 GHC.Int.Int32
instance Witch.From GHC.Int.Int32 GHC.Int.Int64
instance Witch.From GHC.Types.Int GHC.Integer.Type.Integer
instance Witch.From GHC.Integer.Type.Integer GHC.Real.Rational
instance Witch.From GHC.Types.Float GHC.Types.Double
instance Witch.From GHC.Types.Bool GHC.Types.Int
instance Witch.From GHC.Types.Char GHC.Types.Int
instance Witch.From [GHC.Word.Word8] Data.ByteString.Internal.ByteString
instance Witch.From Data.ByteString.Internal.ByteString [GHC.Word.Word8]
instance Witch.From Data.ByteString.Internal.ByteString Data.ByteString.Lazy.Internal.ByteString
instance Witch.From Data.ByteString.Lazy.Internal.ByteString Data.ByteString.Internal.ByteString
instance Witch.From GHC.Base.String Data.Text.Internal.Text
instance Witch.From Data.Text.Internal.Text GHC.Base.String
instance Witch.From Data.Text.Internal.Text Data.Text.Internal.Lazy.Text
instance Witch.From Data.Text.Internal.Lazy.Text Data.Text.Internal.Text
instance Witch.From [a] (Data.Sequence.Internal.Seq a)
instance Witch.From (Data.Sequence.Internal.Seq a) [a]
instance GHC.Classes.Ord a => Witch.From [a] (Data.Set.Internal.Set a)
instance Witch.From (Data.Set.Internal.Set a) [a]
instance GHC.Classes.Ord k => Witch.From [(k, v)] (Data.Map.Internal.Map k v)
instance Witch.From (Data.Map.Internal.Map k v) [(k, v)]