Witch.Utility

Documentation

as :: forall s source. Identity s ~ source => source -> source

This is the same as id except that it requires a type application. This can be an ergonomic way to pin down a polymorphic type in a function pipeline. For example:

-- Avoid this:
f . (\ x -> x :: Int) . g

-- Prefer this:
f . as @Int . g

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

This is the same as cast except that it requires a type application for the source type.

-- Avoid this:
cast (x :: s)

-- Prefer this:
from @s x

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

This is the same as cast except that it requires a type application for the target type.

-- Avoid this:
cast x :: t

-- Prefer this:
into @t x

over :: forall t source target. (Identity t ~ target, Cast source target, Cast target source) => (target -> target) -> source -> source

This function converts from some source type into some target type, applies the given function, then converts back into the source type. This is useful when you have two types that are isomorphic but some function that only works with one of them.

-- Avoid this:
from @t . f . from @s

-- Prefer this:
over @t f

via :: forall u source target through. (Identity u ~ through, Cast source through, Cast through target) => source -> target

This function first converts from some source type into some through type, and then converts that into some target type. Usually this is used when writing Cast instances. Sometimes this can be used to work around the lack of an instance that should probably exist.

-- Avoid this:
from @u . into @u

-- Prefer this:
via @u

tryFrom :: forall s target source. (Identity s ~ source, TryCast source target) => source -> Either (TryCastException source target) target

This is the same as tryCast except that it requires a type application for the source type.

-- Avoid this:
tryCast (x :: s)

-- Prefer this:
tryFrom @s x

tryInto :: forall t source target. (Identity t ~ target, TryCast source target) => source -> Either (TryCastException source target) target

This is the same as tryCast except that it requires a type application for the target type.

-- Avoid this:
tryCast x :: Either (TryCastException s t) t

-- Prefer this:
tryInto @t x

maybeTryCast :: (source -> Maybe target) -> source -> Either (TryCastException source target) target

This function can be used to implement tryCast with a function that returns Maybe. For example:

-- Avoid this:
tryCast s = case f s of
  Nothing -> Left $ TryCastException s Nothing
  Just t -> Right t

-- Prefer this:
tryCast = maybeTryCast f

eitherTryCast :: Exception exception => (source -> Either exception target) -> source -> Either (TryCastException source target) target

This function can be used to implement tryCast with a function that returns Either. For example:

-- Avoid this:
tryCast s = case f s of
  Left e -> Left . TryCastException s . Just $ toException e
  Right t -> Right t

-- Prefer this:
tryCast = eitherTryCast f

tryVia :: forall u source target through. (Identity u ~ through, TryCast source through, TryCast through target) => source -> Either (TryCastException source target) target

This is similar to via except that it works with TryCast instances instead. This function is especially convenient because juggling the types in the TryCastException can be tedious.

-- Avoid this:
fmap (tryFrom @u) . tryInto @u

-- Prefer this:
tryVia @u

unsafeCast :: forall source target. (HasCallStack, TryCast source target, Show source, Typeable source, Typeable target) => source -> target

This function is like tryCast except that it will throw an impure exception if the conversion fails.

-- Avoid this:
either throw id . cast

-- Prefer this:
unsafeCast

unsafeFrom :: forall s target source. (Identity s ~ source, HasCallStack, TryCast source target, Show source, Typeable source, Typeable target) => source -> target

This function is like from except that it will throw an impure exception if the conversion fails.

-- Avoid this:
either throw id . from @s

-- Prefer this:
unsafeFrom @s

unsafeInto :: forall t source target. (Identity t ~ target, HasCallStack, TryCast source target, Show source, Typeable source, Typeable target) => source -> target

This function is like into except that it will throw an impure exception if the conversion fails.

-- Avoid this:
either throw id . into @t

-- Prefer this:
unsafeInto @t