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.
Exports
Section titled “Exports”Types
enum Maybe
Section titled “enum Maybe”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)
Maybe.is_some
Section titled “Maybe.is_some”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)
Maybe.is_none
Section titled “Maybe.is_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)
Maybe.map
Section titled “Maybe.map”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
Maybe.with_default
Section titled “Maybe.with_default”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
Maybe.otherwise
Section titled “Maybe.otherwise”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")
Maybe.or_else
Section titled “Maybe.or_else”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)
Maybe.to_result
Section titled “Maybe.to_result”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")
Maybe.flat_map
Section titled “Maybe.flat_map”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
Maybe.filter
Section titled “Maybe.filter”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"
Maybe.flatten
Section titled “Maybe.flatten”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
Maybe.collect
Section titled “Maybe.collect”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
Maybe.values
Section titled “Maybe.values”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]
Maybe.each_while
Section titled “Maybe.each_while”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]
Maybe.known_count
Section titled “Maybe.known_count”impl Iter for Maybe<T>
fn known_count(maybe: Maybe<T>) -> Maybe<Int>
impl Iter.known_count
Maybe.inspect
Section titled “Maybe.inspect”impl Debug for Maybe<T>
fn inspect<T>(value: Maybe<T>) -> String where T: Debug
impl Debug.inspect
Maybe.to_string
Section titled “Maybe.to_string”impl Display for Maybe<T>
fn to_string<T>(value: Maybe<T>) -> String where T: Display
impl Display.to_string
Maybe.equal
Section titled “Maybe.equal”impl Equatable for Maybe<T>
fn equal<T>(a: Maybe<T>, b: Maybe<T>) -> Bool where T: Equatable
impl Equatable.equal
Maybe.hash
Section titled “Maybe.hash”impl Hashable for Maybe<T>
fn hash<T>(value: Maybe<T>) -> Int where T: Hashable
impl Hashable.hash