Data.Result

data Result error value

The Result type is used to represent computations that may succeed or fail.

Constructors

• Error error
• Ok value

Instances

• Functor (Result a)
• Invariant (Result a)
• Bifunctor Result
• Apply (Result e)

  The Apply instance allows functions contained within a Ok to transform a value contained within a Ok using the (<*>) operator:

  Ok f <*> Ok x == Ok (f x)
  

  Error values are left untouched:

  Error f <*> Ok x == Error x
  Ok f <*> Error y == Error y
  

  Combining Functor's <$> with Apply's <*> can be used to transform a pure function to take Result-typed arguments so f :: a -> b -> c becomes f :: Result l a -> Result l b -> Result l c:

  f <$> Ok x <*> Ok y == Ok (f x y)
  

  The Error-preserving behaviour of both operators means the result of an expression like the above but where any one of the values is Error means the whole result becomes Error also, taking the first Error value found:

  f <$> Error x <*> Ok y == Error x
  f <$> Ok x <*> Error y == Error y
  f <$> Error x <*> Error y == Error x
  

• Applicative (Result e)

  The Applicative instance enables lifting of values into Result with the pure function:

  pure x :: Result _ _ == Ok x
  

  Combining Functor's <$> with Apply's <*> and Applicative's pure can be used to pass a mixture of Result and non-Result typed values to a function that does not usually expect them, by using pure for any value that is not already Result typed:

  f <$> Ok x <*> pure y == Ok (f x y)
  

  Even though pure = Ok it is recommended to use pure in situations like this as it allows the choice of Applicative to be changed later without having to go through and replace Ok with a new constructor.

• Alt (Result e)

  The Alt instance allows for a choice to be made between two Result values with the <|> operator, where the first Ok encountered is taken.

  Ok x <|> Ok y == Ok x
  Error x <|> Ok y == Ok y
  Error x <|> Error y == Error y
  

• Bind (Result e)

  The Bind instance allows sequencing of Result values and functions that return an Result by using the >>= operator:

  Error x >>= f = Error x
  Ok x >>= f = f x
  

• Monad (Result e)

  The Monad instance guarantees that there are both Applicative and Bind instances for Result. This also enables the do syntactic sugar:

  do
    x' <- x
    y' <- y
    pure (f x' y')
  

  Which is equivalent to:

  x >>= (\x' -> y >>= (\y' -> pure (f x' y')))
  

• Extend (Result e)

  The Extend instance allows sequencing of Result values and functions that accept an Result and return a non-Result result using the <<= operator.

  f <<= Error x = Error x
  f <<= Ok x = Ok (f (Ok x))
  

• (Show a, Show b) => Show (Result a b)

  The Show instance allows Result values to be rendered as a string with show whenever there is an Show instance for both type the Result can contain.

• (Eq a, Eq b) => Eq (Result a b)
• (Eq a) => Eq1 (Result a)
• (Ord a, Ord b) => Ord (Result a b)
• (Ord a) => Ord1 (Result a)
• (Bounded a, Bounded b) => Bounded (Result a b)
• Foldable (Result a)
• Bifoldable Result
• Traversable (Result a)
• Bitraversable Result
• (Semigroup b) => Semigroup (Result a b)

fromEither :: forall v e. Either e v -> Result e v

Convert an Either to a Result.

fromEither (Left "error") == Error "error"
fromEither (Right "value") == Ok "value"

toEither :: forall v e. Result e v -> Either e v

Convert a Result to an Either.

toEither (Error "error") == Left "error"
toEither (Ok "value") == Right "value"

result :: forall c b a. (a -> c) -> (b -> c) -> Result a b -> c

Takes two functions and an Result value, if the value is a Error the inner value is applied to the first function, if the value is a Ok the inner value is applied to the second function.

Result f g (Error x) == f x
Result f g (Ok y) == g y

choose :: forall b a m. Alt m => m a -> m b -> m (Result a b)

Combine two alternatives.

isError :: forall b a. Result a b -> Boolean

Returns true when the Result value was constructed with Error.

isOk :: forall b a. Result a b -> Boolean

Returns true when the Result value was constructed with Ok.

fromError :: forall b a. Partial => Result a b -> a

A partial function that extracts the value from the Error data constructor. Passing a Ok to fromError will throw an error at runtime.

fromOk :: forall b a. Partial => Result a b -> b

A partial function that extracts the value from the Ok data constructor. Passing a Error to fromOk will throw an error at runtime.

note :: forall b a. a -> Maybe b -> Result a b

Takes a default and a Maybe value, if the value is a Just, turn it into a Ok, if the value is a Nothing use the provided default as a Error

note "default" Nothing = Error "default"
note "default" (Just 1) = Ok 1

hush :: forall b a. Result a b -> Maybe b

Turns an Result into a Maybe, by throwing eventual Error values away and converting them into Nothing. Ok values get turned into Justs.

hush (Error "ParseError") = Nothing
hush (Ok 42) = Just 42