Witch

This module provides the From type class for converting values between various types. This aims to be a common interface for the various xToY or yFromX functions you might write instead. It is inspired by the std::convert::From trait that the Rust programming language provides.

Many Haskell libraries already provide similar functionality. Here's how this module compares to them:

• https://hackage.haskell.org/package/base-4.14.0.0/docs/Data-Coerce.html: 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.
• https://hackage.haskell.org/package/convertible-1.1.1.0/docs/Data-Convertible-Base.html: This type class allows for conversions to fail.
• https://hackage.haskell.org/package/basement-0.0.11/docs/Basement-From.html: This type class is essentially the same, but the basement package is an alternative standard library that some people may not want to depend on.
• https://hackage.haskell.org/package/inj-base-0.2.0.0/docs/Inj-Base.html: This type class requires conversions to be injective, as opposed to merely suggesting it. Also some conversions fail at runtime.
• https://github.com/mbj/conversions/blob/6ac6c52/src/Data/Conversions/FromType.hs: This type class comes with many convenient helper functions, but some of the provided instances fail at runtime.
• https://github.com/kframework/kore/blob/626f230/kore/src/From.hs: This package is not available on Hackage, but otherwise is very similar to this one.

Documentation

class From a b where

This type class represents a way to convert values from some type into another type. The constraint From a b means that you can convert from a value of type a into a value of type b.

This is primarily intended for "zero cost" conversions like newtypes. For example if you wanted to have a type to represent someone's name, you could say:

newtype Name = Name String
instance From String Name
instance From Name String

And then you could convert back and forth between Names and Strings:

let someString = "Taylor"
let someName = Name someString
into @Name someString -- convert from string to name
into @String someName -- convert from name to string

This type class does not have any laws, but it does have some expectations:

• Conversions should be total. A conversion should never fail or crash. Avoid writing instances like From Int (Maybe Char). (It might be worthwhile to have a separate TryFrom type class for this.)
• Conversions should be unambiguous. For example there are many ways to decode a ByteString into Text, so you shouldn't provide an instance for that.
• Conversions should be cheap, ideally free. For example converting from String to Text is probably fine, but converting from a UTF-8 encoded ByteString to Text is problematic.
• Conversions should be lossless. In other words if you have From a b then no two a values should be converted to the same b value. For example From Int Integer is fine because every Int can be mapped to a corresponding Integer, but From Integer Int is not good because some Integers are out of bounds and would need to be clamped.
• If you have both From a b and From b a, then from . from should be the same as id. In other words a and b are isomorphic.
• If you have both From a b and From b c, then it's up to you if you want to provide From a c. Sometimes using via is ergonomic enough, other times you want the extra instance. (It would be nice if we could provide instance (From a b, From b c) => From a c where from = via @b.)

Minimal complete definition

Nothing

Methods

from :: a -> b

This method converts a value from one type into another. This is intended to be used with the TypeApplications language extension. For example, here are a few ways to convert from an Int into an Integer:

from @Int @Integer 123
from @_ @Integer (123 :: Int)
from @Int @_ 123 :: Integer
from @Int 123 :: Integer
from (123 :: Int) :: Integer

Often the context around an expression will make the explicit type signatures unnecessary. If you find yourself using a partial type signature, consider using into instead. For example:

let someInt = 123 :: Int
from @_ @Integer someInt -- avoid this
into @Integer someInt -- prefer this

The default implementation of from simply calls coerce, which works for types that have the same runtime representation.

default from :: Coercible a b => a -> b

Instances

From Bool Int

fromEnum

Defined in Witch

Methods

from :: Bool -> Int

From Char Int

fromEnum

Defined in Witch

Methods

from :: Char -> Int

From Float Double

realToFrac

Defined in Witch

Methods

from :: Float -> Double

From Int Integer

fromIntegral

Defined in Witch

Methods

from :: Int -> Integer

From Int8 Int16

fromIntegral

Defined in Witch

Methods

from :: Int8 -> Int16

From Int16 Int32

fromIntegral

Defined in Witch

Methods

from :: Int16 -> Int32

From Int32 Int64

fromIntegral

Defined in Witch

Methods

from :: Int32 -> Int64

From Integer Rational

fromIntegral

Defined in Witch

Methods

from :: Integer -> Rational

From Natural Integer

fromIntegral

Defined in Witch

Methods

from :: Natural -> Integer

From Word Natural

fromIntegral

Defined in Witch

Methods

from :: Word -> Natural

From Word8 Word16

fromIntegral

Defined in Witch

Methods

from :: Word8 -> Word16

From Word16 Word32

fromIntegral

Defined in Witch

Methods

from :: Word16 -> Word32

From Word32 Word64

fromIntegral

Defined in Witch

Methods

from :: Word32 -> Word64

From a a

id

Defined in Witch

Methods

from :: a -> a

From Void x

absurd

Defined in Witch

Methods

from :: Void -> x

From String Text

pack

Defined in Witch

Methods

from :: String -> Text

From ByteString ByteString

toStrict

Defined in Witch

Methods

from :: ByteString0 -> ByteString

From ByteString ByteString

fromStrict

Defined in Witch

Methods

from :: ByteString -> ByteString0

From Text Text

toStrict

Defined in Witch

Methods

from :: Text0 -> Text

From Text String

unpack

Defined in Witch

Methods

from :: Text -> String

From Text Text

fromStrict

Defined in Witch

Methods

from :: Text -> Text0

From a (Maybe a)

Just

Defined in Witch

Methods

from :: a -> Maybe a

From a [a]

pure

Defined in Witch

Methods

from :: a -> [a]

From ByteString [Word8]

unpack

Defined in Witch

Methods

from :: ByteString -> [Word8]

From a (Either x a)

Right

Defined in Witch

Methods

from :: a -> Either x a

From a (Either a x)

Left

Defined in Witch

Methods

from :: a -> Either a x

From a (x -> a)

const

Defined in Witch

Methods

from :: a -> x -> a

From [Word8] ByteString

pack

Defined in Witch

Methods

from :: [Word8] -> ByteString

Ord a => From [a] (Set a)

fromList

Note that this will remove duplicate elements from the list.

Defined in Witch

Methods

from :: [a] -> Set a

From [a] (Seq a)

fromList

Defined in Witch

Methods

from :: [a] -> Seq a

From (NonEmpty a) [a]

toList

Defined in Witch

Methods

from :: NonEmpty a -> [a]

From (Seq a) [a]

toList

Defined in Witch

Methods

from :: Seq a -> [a]

From (Set a) [a]

toAscList

Defined in Witch

Methods

from :: Set a -> [a]

Ord k => From [(k, v)] (Map k v)

fromList

Note that if there are duplicate keys in the list, the one closest to the end will win.

Defined in Witch

Methods

from :: [(k, v)] -> Map k v

From (x, a) a

snd

Defined in Witch

Methods

from :: (x, a) -> a

From (a, x) a

fst

Defined in Witch

Methods

from :: (a, x) -> a

From (Map k v) [(k, v)]

toAscList

Defined in Witch

Methods

from :: Map k v -> [(k, v)]

From (a, b) (b, a)

swap

Defined in Witch

Methods

from :: (a, b) -> (b, a)

into :: forall b a. From a b => a -> b

This function converts a value from one type into another. This is the same as from except that the type variables are in the opposite order.

via :: forall b a c. (From a b, From b c) => a -> c

This function converts a value from one type into another by going through some third type. This is the same as calling from (or into) 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, via @b @a @c first converts from a to b, and then from b to c. Often both a and c will be inferred from context, which means you can just write via @b.