A Result is either Ok meaning the computation succeeded, or it is an Err meaning that there was some failure.

Apply a function to a result. If the result is Ok, it will be converted. If the result is an Err, the same error value will propegate through.

map sqrt (Ok 4.0)          == Ok 2.0
map sqrt (Err "bad input") == Err "bad input"

Chain together a sequence of computations that may fail. It is helpful to see its definition:

andThen : Result e a -> (a -> Result e b) -> Result e b
andThen result callback =
    case result of
      Ok value -> callback value
      Err msg -> Err msg

This means we only continue with the callback if things are going well. For example, say you need to use (toInt : String -> Result String Int) to parse a month and make sure it is between 1 and 12:

toValidMonth : Int -> Result String Int
toValidMonth month =
    if month >= 1 && month <= 12
        then Ok month
        else Err "months must be between 1 and 12"


toMonth : String -> Result String Int
toMonth rawString =
    toInt rawString `andThen` toValidMonth


-- toMonth "4" == Ok 4
-- toMonth "9" == Ok 9
-- toMonth "a" == Err "cannot parse to an Int"
-- toMonth "0" == Err "months must be between 1 and 12"

This allows us to come out of a chain of operations with quite a specific error message. It is often best to create a custom type that explicitly represents the exact ways your computation may fail. This way it is easy to handle in your code.

Convert to a simpler Maybe if the actual error message is not needed or you need to interact with some code that primarily uses maybes.

parseInt : String -> Result ParseError Int


maybeParseInt : String -> Maybe Int
maybeParseInt string =
    toMaybe (parseInt string)

Convert from a simple Maybe to interact with some code that primarily uses Results.

parseInt : String -> Maybe Int


resultParseInt : String -> Result String Int
resultParseInt string =
    fromMaybe ("error parsing string: " ++ show string) (parseInt string)