gleam_stdlib - v0.70.0

gleam/option

Types

Option

</>

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

all

</> 
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 all([Some(1), Some(2)]) == Some([1, 2])

assert all([Some(1), None]) == None

flatten

</> 
pub fn flatten(option: Option(Option(a))) -> Option(a)

Merges a nested Option into a single layer.

Examples

assert flatten(Some(Some(1))) == Some(1)

assert flatten(Some(None)) == None

assert flatten(None) == None

from_result

</> 
pub fn from_result(result: Result(a, e)) -> Option(a)

Converts a Result type to an Option type.

Examples

assert from_result(Ok(1)) == Some(1)

assert from_result(Error("some_error")) == None

is_none

</> 
pub fn is_none(option: Option(a)) -> Bool

Checks whether the Option is a None value.

Examples

assert !is_none(Some(1))

assert is_none(None)

is_some

</> 
pub fn is_some(option: Option(a)) -> Bool

Checks whether the Option is a Some value.

Examples

assert is_some(Some(1))

assert !is_some(None)

lazy_or

</> 
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 lazy_or(Some(1), fn() { Some(2) }) == Some(1)

assert lazy_or(Some(1), fn() { None }) == Some(1)

assert lazy_or(None, fn() { Some(2) }) == Some(2)

assert lazy_or(None, fn() { None }) == None

lazy_unwrap

</> 
pub fn lazy_unwrap(option: Option(a), or default: fn() -> a) -> a

Extracts the value from an Option, evaluating the default function if the option is None.

Examples

assert lazy_unwrap(Some(1), fn() { 0 }) == 1

assert lazy_unwrap(None, fn() { 0 }) == 0

map

</> 
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 map(over: Some(1), with: fn(x) { x + 1 }) == Some(2)

assert map(over: None, with: fn(x) { x + 1 }) == None

or

</> 
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 or(Some(1), Some(2)) == Some(1)

assert or(Some(1), None) == Some(1)

assert or(None, Some(2)) == Some(2)

assert or(None, None) == None

then

</> 
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 then(Some(1), fn(x) { Some(x + 1) }) == Some(2)

assert then(Some(1), fn(x) { Some(#("a", x)) }) == Some(#("a", 1))

assert then(Some(1), fn(_) { None }) == None

assert then(None, fn(x) { Some(x + 1) }) == None

to_result

</> 
pub fn to_result(option: Option(a), e: e) -> Result(a, e)

Converts an Option type to a Result type.

Examples

assert to_result(Some(1), "some_error") == Ok(1)

assert to_result(None, "some_error") == Error("some_error")

unwrap

</> 
pub fn unwrap(option: Option(a), or default: a) -> a

Extracts the value from an Option, returning a default value if there is none.

Examples

assert unwrap(Some(1), 0) == 1

assert unwrap(None, 0) == 0

values

</> 
pub fn values(options: List(Option(a))) -> List(a)

Given a list of Options, returns only the values inside Some.

Examples

assert values([Some(1), None, Some(3)]) == [1, 3]
✨ Search Document