witch-1.2.0.2: Convert values from one type into another.

Safe Haskell | Safe-Inferred
Language | Haskell2010

Witch.Utility

Synopsis

- as :: forall source. source -> source
- into :: forall target source. From source target => source -> target
- over :: forall target source. (From source target, From target source) => (target -> target) -> source -> source
- via :: forall through source target. (From source through, From through target) => source -> target
- tryInto :: forall target source. TryFrom source target => source -> Either (TryFromException source target) target
- tryVia :: forall through source target. (TryFrom source through, TryFrom through target) => source -> Either (TryFromException source target) target
- maybeTryFrom :: (source -> Maybe target) -> source -> Either (TryFromException source target) target
- eitherTryFrom :: Exception exception => (source -> Either exception target) -> source -> Either (TryFromException source target) target
- unsafeFrom :: forall source target. (HasCallStack, TryFrom source target, Show source, Typeable source, Typeable target) => source -> target
- unsafeInto :: forall target source. (HasCallStack, TryFrom source target, Show source, Typeable source, Typeable target) => source -> target
- withSource :: newSource -> TryFromException oldSource target -> TryFromException newSource target
- withTarget :: forall newTarget source oldTarget. TryFromException source oldTarget -> TryFromException source newTarget

# Documentation

as :: forall source. source -> source Source #

This is the same as `id`. 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

into :: forall target source. From source target => source -> target Source #

This is the same as `from` except that the type variables are in the opposite order.

    -- Avoid this:
    from x :: t

    -- Prefer this:
    into @t x

over :: forall target source. (From source target, From target source) => (target -> target) -> source -> 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 . into @t

    -- Prefer this:
    over @t f

via :: forall through source target. (From source through, From through target) => source -> target Source #

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 `From` 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

tryInto :: forall target source. TryFrom source target => source -> Either (TryFromException source target) target Source #

This is the same as `tryFrom` except that the type variables are in the opposite order.

    -- Avoid this:
    tryFrom x :: Either (TryFromException s t) t

    -- Prefer this:
    tryInto @t x

tryVia :: forall through source target. (TryFrom source through, TryFrom through target) => source -> Either (TryFromException source target) target Source #

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

    -- Avoid this:
    case tryInto @u x of
      Left (TryFromException _ e) -> Left $ TryFromException x e
      Right y -> case tryFrom @u y of
        Left (TryFromException _ e) -> Left $ TryFromException x e
        Right z -> Right z

    -- Prefer this:
    tryVia @u

maybeTryFrom :: (source -> Maybe target) -> source -> Either (TryFromException source target) target Source #

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

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

    -- Prefer this:
    tryFrom = maybeTryFrom f

eitherTryFrom :: Exception exception => (source -> Either exception target) -> source -> Either (TryFromException source target) target Source #

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

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

    -- Prefer this:
    tryFrom = eitherTryFrom f

unsafeFrom :: forall source target. (HasCallStack, TryFrom source target, Show source, Typeable source, Typeable target) => source -> target Source #

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

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

    -- Prefer this:
    unsafeFrom @s

unsafeInto :: forall target source. (HasCallStack, TryFrom source target, Show source, Typeable source, Typeable target) => source -> target Source #

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

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

    -- Prefer this:
    unsafeInto @t

withSource :: newSource -> TryFromException oldSource target -> TryFromException newSource target Source #

withTarget :: forall newTarget source oldTarget. TryFromException source oldTarget -> TryFromException source newTarget Source #