Skip to content

std::maybe

A Maybe<T> is a value that may be absent: Some(value) or None. A function returns one when it may have no answer, as Map.get does for a missing key. Maybe, Some and None are in the prelude, so a program writes them without an import.

Read a Maybe with case, which must handle both variants:

fn describe(ages: Map<String, Int>, name: String) -> String
    case Map.get(ages, name)
        Some(age) -> "${name} is ${age}"
        None      -> "nobody is called ${name}"
    end
end

The functions here cover the common cases without a case. Test a Maybe with is_some and is_none. Change the value with map, flat_map and filter. Take the value out with with_default. Fall back to another Maybe with otherwise and or_else. Unnest a Maybe<Maybe<T>> with flatten. Turn it into a Result with to_result. collect and values work over many maybes at once.

A Maybe is an Iter of zero or one elements, so it goes wherever an Iter does. It renders, in Display and in Debug, as Some(...) around the rendered value or as None, never as the bare value or the empty string.

Import with import std::maybe.

Types

enum Maybe<T>
    Some T
    None
end

A value that may or may not be present.

n: Maybe<Int> = Maybe.None
assert "${Maybe.Some(3)}" == "Some(3)"
assert "${n}" == "None"

assert Maybe.Some(42)
    |> case
        .Some(v) -> v
        .None    -> 0
    end
    |> Int.equal(42)
fn is_some<T>(maybe: Maybe<T>) -> Bool

type function on Maybe

Returns True when the value is Some.

assert Maybe.is_some(Maybe.Some(3))
refute Maybe.is_some(Maybe.None)
fn is_none<T>(maybe: Maybe<T>) -> Bool

type function on Maybe

Returns True when the value is None.

refute Maybe.is_none(Maybe.Some(3))
assert Maybe.is_none(Maybe.None)
fn map<T, U>(maybe: Maybe<T>, f: (T) -> U) -> Maybe<U>

type function on Maybe

Applies f to the value inside Some. None stays None.

assert Maybe.map(Maybe.Some(3), &(&1 * 2)) == Maybe.Some(6)
assert Maybe.map(Maybe.None, &(&1 * 2)) == Maybe.None
fn with_default<T>(maybe: Maybe<T>, default: T) -> T

type function on Maybe

Returns the value inside Some, or the default if None.

assert Maybe.with_default(Maybe.Some(5), 0) == 5
assert Maybe.with_default(Maybe.None, 0) == 0
fn otherwise<T>(maybe: Maybe<T>, fallback: Maybe<T>) -> Maybe<T>

type function on Maybe

Returns maybe when it is Some, and otherwise fallback: the first of two places a value may come from. fallback is computed even when maybe is Some; or_else computes it only when needed.

import std::maps.Map

assert Maybe.otherwise(Maybe.Some(1), Maybe.Some(2)) == Maybe.Some(1)
assert Maybe.otherwise(Maybe.None, Maybe.Some(2)) == Maybe.Some(2)
nothing: Maybe<Int> = Maybe.None
assert Maybe.otherwise(nothing, Maybe.None) == Maybe.None

flags = {"port" => "8080"}
port = Map.get(flags, "listen") |> Maybe.otherwise(Map.get(flags, "port"))
assert port == Maybe.Some("8080")
fn or_else<T>(maybe: Maybe<T>, fallback: () -> Maybe<T>) -> Maybe<T>

type function on Maybe

Returns maybe when it is Some, and otherwise what fallback returns. fallback is called only for None, so it can do work, such as a lookup, that a Some makes unneeded.

assert Maybe.or_else(Maybe.Some(1), fn -> Maybe.Some(2)) == Maybe.Some(1)
assert Maybe.or_else(Maybe.None, fn -> Maybe.Some(2)) == Maybe.Some(2)
fn to_result<T, E>(maybe: Maybe<T>, error: E) -> Result<T, E>

type function on Maybe

Converts Maybe to Result. None becomes Err(error).

assert Maybe.to_result(Maybe.Some(3), "missing") == Result.Ok(3)
assert Maybe.to_result(Maybe.None, "missing") == Result.Err("missing")
fn flat_map<T, U>(maybe: Maybe<T>, f: (T) -> Maybe<U>) -> Maybe<U>

type function on Maybe

Applies f, which returns a Maybe itself, to the value inside Some and returns what f returns, not a Maybe of a Maybe. None stays None.

safe_div = fn a: Int, b: Int ->
    if b == 0 then Maybe.None else Maybe.Some(a / b)
end

assert Maybe.flat_map(Maybe.Some(10), &safe_div(&1, 2)) == Maybe.Some(5)
assert Maybe.flat_map(Maybe.Some(10), &safe_div(&1, 0)) == Maybe.None
fn filter<T>(maybe: Maybe<T>, keep: (T) -> Bool) -> Maybe<T>

type function on Maybe

Keeps the value inside Some when keep returns True for it, and otherwise returns None.

assert Maybe.filter(Maybe.Some(4), &(&1 > 2)) == Maybe.Some(4)
assert Maybe.filter(Maybe.Some(1), &(&1 > 2)) == Maybe.None
nothing: Maybe<Int> = Maybe.None
assert Maybe.filter(nothing, &(&1 > 2)) == Maybe.None

// An empty setting counts as unset.
host = Maybe.Some("") |> Maybe.filter(&(&1 != "")) |> Maybe.with_default("localhost")
assert host == "localhost"
fn flatten<T>(maybe: Maybe<Maybe<T>>) -> Maybe<T>

type function on Maybe

Removes one level of nesting: Some(Some(v)) becomes Some(v), and both Some(None) and None become None.

assert Maybe.flatten(Maybe.Some(Maybe.Some(3))) == Maybe.Some(3)
assert Maybe.flatten(Maybe.Some(Maybe.None)) == Maybe.None

nothing: Maybe<Maybe<Int>> = Maybe.None
assert Maybe.flatten(nothing) == Maybe.None
assert Maybe.flatten(Maybe.None) == Maybe.None
fn collect<T>(maybes: Iter<Maybe<T>>) -> Maybe<List<T>>

type function on Maybe

Returns Some of every value in order when every element is Some, and otherwise None. It stops consuming the iterator at the first None.

import std::ranges.Range

assert Maybe.collect([Maybe.Some(1), Maybe.Some(2)]) == Maybe.Some([1, 2])
assert Maybe.collect([Maybe.Some(1), Maybe.None, Maybe.Some(3)]) == Maybe.None
none: List<Maybe<Int>> = []
assert Maybe.collect(none) == Maybe.Some([])

halved =
    [4, 2, 8]
    |> Iter.map(fn n ->
        if n % 2 == 0 then Maybe.Some(n / 2) else Maybe.None
    end)
    |> Maybe.collect()

assert halved == Maybe.Some([2, 1, 4])

// On an endless source, collect stops reading at the first None.
stopped =
    Range.naturals()
    |> Iter.map(fn n -> if n < 3 then Maybe.Some(n) else Maybe.None)
    |> Maybe.collect()

assert stopped == Maybe.None
fn values<T>(maybes: Iter<Maybe<T>>) -> Iter<T>

type function on Maybe

Yields the Some values in order and drops every None. It is lazy, so it works on an endless source.

assert Maybe.values([Maybe.Some(1), Maybe.None, Maybe.Some(3)]) |> Iter.to_list() == [1, 3]
nones: List<Maybe<Int>> = [Maybe.None, Maybe.None]
assert Maybe.values(nones) |> Iter.is_empty()

halves =
    [4, 3, 8]
    |> Iter.map(fn n ->
        if n % 2 == 0 then Maybe.Some(n / 2) else Maybe.None
    end)
    |> Maybe.values()
    |> Iter.to_list()

assert halves == [2, 4]

evens =
    Iter.from(0)
    |> Iter.map(fn n -> if n % 2 == 0 then Maybe.Some(n) else Maybe.None)
    |> Maybe.values()
    |> Iter.take(3)
    |> Iter.to_list()

assert evens == [0, 2, 4]

impl Iter for Maybe<T>

fn each_while(maybe: Maybe<T>, yield: (T) -> Bool) -> Bool

impl Iter.each_while

A Maybe iterates as zero or one elements: Some(x) pushes x to yield, and None pushes nothing. So a Maybe goes wherever an Iter does, as in Iter.concat(lines, reaction) or a flat_map whose function returns a Maybe.

assert Iter.to_list(Maybe.Some(3)) == [3]
none: Maybe<Int> = Maybe.None
assert Iter.to_list(none) == []
assert Iter.concat(["a"], Maybe.Some("b")) |> Iter.to_list() == ["a", "b"]

assert [1, 2, 3]
|> Iter.flat_map(fn n ->
    if n % 2 == 1 then Maybe.Some(n * 10) else Maybe.None
end)
|> Iter.to_list() == [10, 30]

impl Iter for Maybe<T>

fn known_count(maybe: Maybe<T>) -> Maybe<Int>

impl Iter.known_count

impl Debug for Maybe<T>

fn inspect<T>(value: Maybe<T>) -> String where T: Debug

impl Debug.inspect

impl Display for Maybe<T>

fn to_string<T>(value: Maybe<T>) -> String where T: Display

impl Display.to_string

impl Equatable for Maybe<T>

fn equal<T>(a: Maybe<T>, b: Maybe<T>) -> Bool where T: Equatable

impl Equatable.equal

impl Hashable for Maybe<T>

fn hash<T>(value: Maybe<T>) -> Int where T: Hashable

impl Hashable.hash