Results.Functions: Functions and Combinators

to_nullable(val::Option{T})::Union{T, Nothing}
to_nullable(val::Result{T, E})::Union{T, Nothing}

Convert a Result{T, E} or Option{T} into a simple nullable value Union{T, Nothing}. Note that this may lose structure (this transformation is non-injective, as Some(nothing) and nothing map to the same value).

to_option(value::Union{T, Nothing})::Option{T}
to_option(value::Result)::Option

Converts a nullable value to an Option. Also converts a Result to an Option, turning Ok into Some and Err into None.

Examples

julia> to_option("value")
Some("value")
julia> to_option(Some(5))
Some(Some(5))
julia> to_option(nothing) |> println
nothing

to_result(value::T, err)::Ok{T}
to_result(value::None, err::E)::Err{E}
to_result(value::None, err::Function)::Err

Converts a nullable value to a Result, using the supplied error value in place of a nothing. Also converts an Option into a Result, turning Some into Ok and None into Err.

Examples

julia> to_result("value", "error")
Ok("value")
julia> to_result(nothing, "error")
Err("error")
julia> to_result("value", () -> println("lazily calculates errors"))
Ok("value")
julia> to_result(Ok(5), nothing)
Ok(Ok(5))

to_result(err)::Function

Partially-applied version of to_result.

Examples

julia> 5 |> to_result("error")
Ok(5)
julia> nothing |> to_result("error")
Err("error")

unwrap(o::Option{T})::T
unwrap(r::Result{T, E})::T
unwrap(o::Union{Option, Result}, error::Function)
unwrap(o::Union{Option, Result}, error::Exception)
unwrap(o::Union{Option, Result}, error::String)

Unwrap an Ok value. Throws an error if r is Err instead.

In the two argument form, error is raised if it is an Exception. If it is a string, it is passed as a message to UnwrapError. If it is a function, it is called with an error value to produce an error.

Examples

julia> unwrap(Ok(5))
5
julia> unwrap(Err(0))
ERROR: Results.Types.UnwrapError("unwrap() called on an Err: 0")
julia> unwrap(none)
ERROR: Results.Types.UnwrapError("unwrap() called on None")
julia> unwrap(none, "value is none")
ERROR: Results.Types.UnwrapError("value is none")
julia> unwrap(nothing, BoundsError([1,2]))
ERROR: BoundsError: attempt to access 2-element Array{Int64,1}
julia> unwrap(Err(5), v -> "Error value '" * string(v) * "'")
ERROR: Results.Types.UnwrapError("Error value '5'")

unwrap_or(o::Option{T}, default)::T
unwrap_or(r::Result{T, E}, default)::T

Unwrap an Ok value, or return default. default may be T or a function returning T.

Examples

julia> unwrap_or(Ok("value"), "error")
"value"
julia> unwrap_or(Err(5), "error")
"error"
julia> unwrap_or(Some("value"), () -> begin println("Generating error"); "error" end)
"value"
julia> unwrap_or(None(), () -> begin println("Generating error"); "error" end)
Generating error
"error"

and_then(result::Result, funcs...)::Result

Bind result to the proceeding functions. If result is Ok, its contents will be passed to each function in turn. Any Err value will be returned immediately.

Examples

julia> Ok("Build") ⊗ val -> Ok(string(val, " a ")) ⊗ val -> Ok(string(val, "string"))
Ok("Build a string")
julia> Err("Error") ⊗ val -> Ok(string(val, " a ")) ⊗ val -> Ok(string(val, "string"))
Err("Error")
julia> Ok("Build") ⊗ val -> Err("Error") ⊗ function (val) error("long circuited"); Ok("value") end
Err("Error")

and_then(func::Base.Callable)::Function

Partially-applied version of and_then.

and_then(option::Option, funcs...)::Option

Bind option to the proceeding functions. While option is Some, its contents will be passed to each function in turn. Any None will be returned immediately.

Examples

julia> Some("Build") ⊗ val -> Some(string(val, " a ")) ⊗ val -> Some(string(val, "string"))
Some("Build a string")
julia> none ⊗ val -> Some(string(val, " a ")) ⊗ val -> Some(string(val, "string"))

julia> Some("Build") ⊗ val -> none ⊗ function (val) error("long circuited"); Some("value") end

flatten(o::Option{Option{T}})::Option{T}
flatten(r::Result{Result{T, E1}, E2})::Result{T, Union{E1, E2}}

Flatten one layer of a nested Option or Result type.

Examples

julia> Ok(Ok(5)) |> flatten
Ok(5)
julia> Ok(Err("inner")) |> flatten
Err("inner")
julia> Some(Some(Some(5))) |> flatten
Some(Some(5))
julia> Ok(Some(5)) |> flatten  # mixed Option and Result types not supported
ERROR: MethodError

map_err(f, result::Result)::Result

Map f over the contents of an Err value, leaving an Ok value untouched.

map_err(f)::Function

Partially-applied version of map_err.

ok(r::Result{T, E})::Option{T}

Convert a Result into an Option, discarding any Err value.

Examples

julia> ok(Ok(5))
Some(5)
julia> ok(Err("error")) |> println
nothing

ok_or(o::Some{T}, err)::Ok{T}
ok_or(::None, err::E)::Err{E}
ok_or(::None, err::Function)::Err

Convert an Option into a Result, using the supplied error value in place of None.

Examples

julia> ok_or(Some(5), "error")
Ok(5)
julia> ok_or(None(), "error")
Err("error")
julia> ok_or(None(), () -> "lazy error")
Err("lazy error")
julia> None() |> ok_or("partially applied")
Err("partially applied")

ok_or(err)::Function

Partially-applied version of ok_or.

try_collect(iter)
try_collect(result::Result, results...)::Result{Vector}
try_collect(option::Option, options...)::Option{Vector}

Collect an iterator of Options or Results into a single Option or Result containing an array. Short-circuits on error.

Examples

julia> try_collect([Ok(5), Ok(10), Ok(3)])
Ok([5, 10, 3])
julia> try_collect([Ok(10), Err("err1"), Err("err2")])
Err("err1")
julia> try_collect([Ok(10), None(), Ok(5)])  # be careful mixing Result with Option!
Ok(Union{Nothing, Int64}[10, nothing, 5])

try_collect_option(iter)::Option{Vector}
try_collect_option(options...)::Option{Vector}

Version of try_collect specialized for use with Option Prefer this over try_collect whenever possible to prevent surprising behavior.

try_collect_result(iter)::Result{Vector}
try_collect_result(results...)::Result{Vector}

Version of try_collect specialized for use with Result. Prefer this over try_collect whenever possible to prevent surprising behavior.

try_map(f, opt::Option...)::Option
try_map(f, rslt::Result...)::Result
try_map(f::Option, rslt::Option...)::Option
try_map(f::Result, rslt::Result...)::Result

Map f over the contents of an Ok or Some value, leaving a None or Err value untouched.

Example

julia> try_map((x) -> 2*x, Ok(5))
Ok(10)
julia> try_map(+, Err("First error"), Err("Second error"))
Err("First error")
julia> try_map.((x) -> 2*x, [Ok(5), Err("missing value")])
2-element Array{Any,1}:
 Ok(10)
 Err("missing value")
julia> try_map(Ok(+), Ok(5), Ok(10))
Ok(15)

try_map(f::Callable)::Function

Partially-applied version of try_map.

has_val(result::Union{Result, Option})::Bool

Returns true for a successful Result or Option.

is_err(r::Result)::Bool

Return whether a Result is Err.

is_err(r::Result, value)::Bool

Return whether a Result contains an error equal to value.

is_none(o::Option)::Bool

Return whether an Option is None. Equivalent to Base.isnothing.

is_ok(r::Result)::Bool

Return whether a Result is Ok or Err.

is_ok(r::Result, value)::Bool

Return whether a Result contains a value equal to value.

is_some(o::Option)::Bool

Return whether an Option is Some.

is_some(o::Option, value)::Bool

Return whether an Option contains a value equal to value.

Shorthand for try_map. Enter as \leftarrow.

Example

julia> Ok(x -> 2*x) ← Ok(5)
Ok(10)
julia> x -> 2*x ← Ok(5)  # Be careful with precedence!
#1 (generic function with 1 method)
julia> (x -> 2*x) ← (x -> x+7) ← Some(3)
Some(20)

Argument-swapped version of try_map. Enter as \rightarrow.

Example

julia> Some(5) → x -> 2*x
Some(10)
julia> Ok(5) → (x -> 2*x) → (x -> x+7)  # arrows in Julia are right-associative!
ERROR: MethodError
julia> Ok(5) → (x -> 2*x) ∘ (x -> x+7) # but this will work
Ok(24)

Shorthand for and_then (monadic bind). Enter with \otimes

strip_option_type(ty::Type)::Type

Return the passed type with one layer of Option values stripped.

strip_result_type(ty::Type)::Type

Return the passed type with one layer of Result values stripped.

(!)(result::Result{T,E})::Result{E,T}

Flip an Ok value to an Err value and vice versa.

(&)(result::Result, results...)::Result
(&)(option::Option, options...)::Option

Return the final Ok/Some only if every argument is Ok/Some. Otherwise return the first Err value.

Values can be supplied either as Result/Options or as functions that yield a Result/Option.

Examples

julia> Ok("v1") & Ok("v2") & () -> Ok("v3")
Ok("v3")

julia> Ok("v1") & () -> Err(2) & () -> Ok("v2")
Err(2)

julia> Some(5) & Some(10) & None()

(|)(result::Result, results...)::Result
(|)(option::Option, options...)::Option

Return the first Ok value found. If no arguments are Ok, return the final Err value.

Values can be supplied either as Results or as functions that yield a Result.

Examples

julia> Err("err1") | Ok("v2") | () -> Ok("v3")
Ok("v2")
julia> Err("err1") | () -> Err("err2") | Err("err3")
Err("err3")