Witch

This module provides the Cast 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 Cast source target where

This type class represents a way to convert values from some type into another type. The constraint Cast 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 Cast String Name
instance Cast 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 Cast Int (Maybe Char). (It might be worthwhile to have a separate TryCast 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 Cast a b then no two a values should be converted to the same b value. For example Cast Int Integer is fine because every Int can be mapped to a corresponding Integer, but Cast Integer Int is not good because some Integers are out of bounds and would need to be clamped.
• If you have both Cast a b and Cast b a, then cast . cast should be the same as id. In other words a and b are isomorphic.
• If you have both Cast a b and Cast b c, then it's up to you if you want to provide Cast a c. Sometimes using via is ergonomic enough, other times you want the extra instance. (It would be nice if we could provide instance (Cast a b, Cast b c) => Cast a c where cast = via @b.)

Minimal complete definition

Nothing

Methods

cast :: source -> target

This method implements the conversion of a value between types. In practice most instances don't need an explicit implementation. At call sites you'll usually want to use from or into instead of cast.

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

default cast :: Coercible source target => source -> target

Instances

Cast Bool Int

fromEnum

Defined in Witch

Methods

cast :: Bool -> Int

Cast Char Int

fromEnum

Defined in Witch

Methods

cast :: Char -> Int

Cast Float Double

realToFrac

Defined in Witch

Methods

cast :: Float -> Double

Cast Int Integer

fromIntegral

Defined in Witch

Methods

cast :: Int -> Integer

Cast Int8 Int16

fromIntegral

Defined in Witch

Methods

cast :: Int8 -> Int16

Cast Int16 Int32

fromIntegral

Defined in Witch

Methods

cast :: Int16 -> Int32

Cast Int32 Int64

fromIntegral

Defined in Witch

Methods

cast :: Int32 -> Int64

Cast Integer Rational

fromIntegral

Defined in Witch

Methods

cast :: Integer -> Rational

Cast Natural Integer

fromIntegral

Defined in Witch

Methods

cast :: Natural -> Integer

Cast Word Natural

fromIntegral

Defined in Witch

Methods

cast :: Word -> Natural

Cast Word8 Word16

fromIntegral

Defined in Witch

Methods

cast :: Word8 -> Word16

Cast Word16 Word32

fromIntegral

Defined in Witch

Methods

cast :: Word16 -> Word32

Cast Word32 Word64

fromIntegral

Defined in Witch

Methods

cast :: Word32 -> Word64

Cast a a

id

Defined in Witch

Methods

cast :: a -> a

Cast Void x

absurd

Defined in Witch

Methods

cast :: Void -> x

Cast String Text

pack

Note that some Char values cannot be represented in Text and will be replaced by U+FFFD.

Defined in Witch

Methods

cast :: String -> Text

Cast ByteString ByteString

toStrict

Defined in Witch

Methods

cast :: ByteString0 -> ByteString

Cast ByteString ByteString

fromStrict

Defined in Witch

Methods

cast :: ByteString -> ByteString0

Cast Text Text

toStrict

Defined in Witch

Methods

cast :: Text0 -> Text

Cast Text String

unpack

Defined in Witch

Methods

cast :: Text -> String

Cast Text Text

fromStrict

Defined in Witch

Methods

cast :: Text -> Text0

Cast a (Maybe a)

Just

Defined in Witch

Methods

cast :: a -> Maybe a

Cast a [a]

pure

Defined in Witch

Methods

cast :: a -> [a]

Cast ByteString [Word8]

unpack

Defined in Witch

Methods

cast :: ByteString -> [Word8]

Cast a (Either x a)

Right

Defined in Witch

Methods

cast :: a -> Either x a

Cast a (Either a x)

Left

Defined in Witch

Methods

cast :: a -> Either a x

Cast a (x -> a)

const

Defined in Witch

Methods

cast :: a -> x -> a

Cast [Word8] ByteString

pack

Defined in Witch

Methods

cast :: [Word8] -> ByteString

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

fromList

Note that this will remove duplicate elements from the list.

Defined in Witch

Methods

cast :: [a] -> Set a

Cast [a] (Seq a)

fromList

Defined in Witch

Methods

cast :: [a] -> Seq a

Cast (NonEmpty a) [a]

toList

Defined in Witch

Methods

cast :: NonEmpty a -> [a]

Cast (Seq a) [a]

toList

Defined in Witch

Methods

cast :: Seq a -> [a]

Cast (Set a) [a]

toAscList

Defined in Witch

Methods

cast :: Set a -> [a]

Ord k => Cast [(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

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

Cast (x, a) a

snd

Defined in Witch

Methods

cast :: (x, a) -> a

Cast (a, x) a

fst

Defined in Witch

Methods

cast :: (a, x) -> a

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

toAscList

Defined in Witch

Methods

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

Cast (a, b) (b, a)

swap

Defined in Witch

Methods

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

from :: forall s target source. (Ambiguous s ~ source, Cast source target) => source -> target

This function converts a value from one type into another. This is intended to be used with the TypeApplications language extension. The Ambiguous type in the signature makes a type application required. If you'd prefer not to provide a type application, use cast instead.

As an 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

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

into :: forall t source target. (Ambiguous t ~ target, Cast source target) => source -> target

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 through source target. (Cast source through, Cast through target) => source -> target

This function converts a value from one type into another by going through some third type. This is the same as calling cast (or 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.