Module

Data.Result

#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)
The Functor instance allows functions to transform the contents of a Ok with the <$> operator:
```
f <$> Ok x == Ok (f x)
```
Error values are untouched:
```
f <$> Error y == Error y
```
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)
The Eq instance allows Result values to be checked for equality with == and inequality with /= whenever there is an Eq instance for both types the Result can contain.
(Eq a) => Eq1 (Result a)
(Ord a, Ord b) => Ord (Result a b)
The Ord instance allows Result values to be compared with compare, >, >=, < and <= whenever there is an Ord instance for both types the Result can contain.

Any Error value is considered to be less than a Ok value.
(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

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

Convert an Either to a Result.

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

#toEither

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

Convert a Result to an Either.

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

#result

result :: forall a b c. (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

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

Combine two alternatives.

#isError

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

Returns true when the Result value was constructed with Error.

#isOk

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

Returns true when the Result value was constructed with Ok.

#fromError

fromError :: forall a b. 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

fromOk :: forall a b. 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

note :: forall a b. 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

hush :: forall a b. 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