gleam/option
Types
Option represents a value that may be present or not. Some means the value is
present, None means the value is not.
This is Gleam’s alternative to having a value that could be Null, as is possible in some other languages.
Option and Result
In other languages fallible functions may return either Result or
Option depending on whether there is more information to be given about the
failure. In Gleam all fallible functions return Result, and Nil is used
as the error if there is no extra detail to give. This consistency removes
the boilerplate that would otherwise be needed to convert between Option
and Result types, and makes APIs more predictable.
The Option type should only be used for taking optional values as
function arguments, or for storing them in other data structures.
pub type Option(a) {
Some(a)
None
}Constructors
-
Some(a) -
None
Values
pub fn all(list: List(Option(a))) -> Option(List(a))Combines a list of Options into a single Option.
If all elements in the list are Some then returns a Some holding the list of values.
If any element is None then returns None.
Examples
assert option.all([Some(1), Some(2)]) == Some([1, 2])
assert option.all([Some(1), None]) == None
pub fn flatten(option: Option(Option(a))) -> Option(a)Merges a nested Option into a single layer.
Examples
assert option.flatten(Some(Some(1))) == Some(1)
assert option.flatten(Some(None)) == None
assert option.flatten(None) == None
pub fn from_result(result: Result(a, e)) -> Option(a)Converts a Result type to an Option type.
Examples
assert option.from_result(Ok(1)) == Some(1)
assert option.from_result(Error("some_error")) == None
pub fn is_none(option: Option(a)) -> BoolChecks whether the Option is a None value.
Examples
assert !option.is_none(Some(1))
assert option.is_none(None)
pub fn is_some(option: Option(a)) -> BoolChecks whether the Option is a Some value.
Examples
assert option.is_some(Some(1))
assert !option.is_some(None)
pub fn lazy_or(
first: Option(a),
second: fn() -> Option(a),
) -> Option(a)Returns the first value if it is Some, otherwise evaluates the given function for a fallback value.
Examples
assert option.lazy_or(Some(1), fn() { Some(2) }) == Some(1)
assert option.lazy_or(Some(1), fn() { None }) == Some(1)
assert option.lazy_or(None, fn() { Some(2) }) == Some(2)
assert option.lazy_or(None, fn() { None }) == None
pub fn lazy_unwrap(option: Option(a), or default: fn() -> a) -> aExtracts the value from an Option, evaluating the default function if the option is None.
Examples
assert option.lazy_unwrap(Some(1), fn() { 0 }) == 1
assert option.lazy_unwrap(None, fn() { 0 }) == 0
pub fn map(
over option: Option(a),
with fun: fn(a) -> b,
) -> Option(b)Updates a value held within the Some of an Option by calling a given function
on it.
If the Option is a None rather than Some, the function is not called and the
Option stays the same.
Examples
assert option.map(over: Some(1), with: fn(x) { x + 1 }) == Some(2)
assert option.map(over: None, with: fn(x) { x + 1 }) == None
pub fn or(first: Option(a), second: Option(a)) -> Option(a)Returns the first value if it is Some, otherwise returns the second value.
Examples
assert option.or(Some(1), Some(2)) == Some(1)
assert option.or(Some(1), None) == Some(1)
assert option.or(None, Some(2)) == Some(2)
assert option.or(None, None) == None
pub fn then(
option: Option(a),
apply fun: fn(a) -> Option(b),
) -> Option(b)Updates a value held within the Some of an Option by calling a given function
on it, where the given function also returns an Option. The two options are
then merged together into one Option.
If the Option is a None rather than Some the function is not called and the
option stays the same.
This function is the equivalent of calling map followed by flatten, and
it is useful for chaining together multiple functions that return Option.
Examples
assert option.then(Some(1), fn(x) { Some(x + 1) }) == Some(2)
assert option.then(Some(1), fn(x) { Some(#("a", x)) }) == Some(#("a", 1))
assert option.then(Some(1), fn(_) { None }) == None
assert option.then(None, fn(x) { Some(x + 1) }) == None
pub fn to_result(option: Option(a), e: e) -> Result(a, e)Converts an Option type to a Result type.
Examples
assert option.to_result(Some(1), "some_error") == Ok(1)
assert option.to_result(None, "some_error") == Error("some_error")
pub fn unwrap(option: Option(a), or default: a) -> aExtracts the value from an Option, returning a default value if there is none.
Examples
assert option.unwrap(Some(1), 0) == 1
assert option.unwrap(None, 0) == 0