ResultTypes API

Result(val::T, exception_type::Type{E}=Exception) -> Result{T, E}

Create a Result that could hold a value of type T or an exception of type E, and store val in it. If the exception type is not provided, the supertype Exception is used as E.

ErrorResult(::Type{T}, exception::E) -> Result{T, E}
ErrorResult(::Type{T}, exception::AbstractString="") -> Result{T, ErrorException}

Create a Result that could hold a value of type T or an exception of type E, and store exception in it. If the exception is provided as text, it is wrapped in the generic ErrorException. If no exception is provided, an ErrorException with an empty string is used. If the type argument is not provided, Any is used.

ErrorResult is a convenience function for creating a Result and is not its own type.

unwrap(result::Result{T, E}) -> T
unwrap(val::T) -> T
unwrap(::Type{T}, result_or_val) -> T

Assumes result holds a value of type T and returns it. If result holds an exception instead, that exception is thrown.

If unwrap's argument is not a Result, it is returned.

The two-argument form of unwrap calls unwrap on its second argument, then converts it to type T.

unwrap_error(result::Result{T, E}) -> E
unwrap_error(exception::E) -> E

Assumes result holds an exception of type E and returns it. If result holds a value instead, throw an exception.

If unwrap_error's argument is an Exception, that exception is returned.

ResultTypes.iserror(x) -> Bool

If x is an Exception, return true. If x is an ErrorResult (a Result containing an Exception), return true. Return false in all other cases.

@try x
@try(x)

if x is an error (i.e., iserror(x) == true), unwrap the error and return from the current function. Otherwise, unwrap x.

If the unwrapped exception is of the wrong type, there must be a Base.convert method which will convert it to the correct type. (See the example in the extended help below.)

This macro is meant to reduce boilerplate when calling functions returning Results.

Extended help

A typical set of functions using ResultTypes might look something like this:

Base.convert(::Type{FooError}, err::BarError) = FooError("Got a BarError: $(err.msg)")

function isbar(y)::Result{Bool, BarError}
    bad_value(y) && return BarError("Bad value: $y")
    return y == "bar"
end

function foo(x)::Result{Int, FooError}
    result = isbar(x)
    ResultTypes.iserror(result) && return unwrap_error(result)
    is_b = unwrap(result)

    return is_b ? 42 : 13
end

With the @try macro, foo gets shortened to

function foo(x)::Result{Int, FooError}
    is_b = @try(isbar(x))
    return is_b ? 42 : 13
end

@try x err
@try(x, err)

if x is an error, return a new exception err. Otherwise, unwrap x.

This version of @try does not require any exceptions to be converted.

Extended help

Example:

function isbar(y)::Result{Bool, BarError}
    bad_value(y) && return BarError("Bad value: $y")
    return y == "bar"
end

function foo(x)::Result{Int, FooError}
    is_b = @try(isbar(x), FooError())
    return is_b ? 42 : 13
end