std::presence
Presence<T>: whether an input said anything about a value,
Present(value) or Absent. Where Maybe says a value may be missing,
Presence says an input may leave it out, so Presence<Maybe<T>> tells
“not given” (Absent) from “given as nothing” (Present(None)). A
JSON PATCH body is the common case: a field of that type reads a missing
key as Absent and a null as Present(None), and an Absent field is
left out when the struct is written.
Its owner functions are named after Maybe’s: test it with is_present
and is_absent, transform the value with map, merge it over what is
already there with with_default, fall back to another layer of input
with otherwise, and turn it into a Maybe with to_maybe, or a
Presence<Maybe<T>> into one with flatten. ? and !
do not take a Presence, since Absent is no failure; where it is one,
write Presence.to_maybe(p)?.
Import with import std::presence.
Exports
Section titled “Exports”Types
enum Presence
Section titled “enum Presence”enum Presence<T> Absent Present T end
Whether an input gave a value: Present(value), or Absent when it
said nothing about it.
absent: Presence<Int> = Presence.Absent
assert "${Presence.Present(3)}" == "Present(3)"
assert "${absent}" == "Absent"
// A PATCH body that clears `due` and leaves `title` alone.
patch = Json.decode_as<{title: Presence<String>, due: Presence<Maybe<Int>>}>(`{"due": null}`)
title: Presence<String> = Presence.Absent
due: Presence<Maybe<Int>> = Presence.Present(Maybe.None)
assert patch == Result.Ok({title:, due:})
// Written back, the Absent field leaves its key out.
assert Json.encode_as({title:, due:}) == `{"due":null}`
Presence.is_present
Section titled “Presence.is_present”fn is_present<T>(presence: Presence<T>) -> Bool
type function on Presence
Returns True when the value is Present.
assert Presence.is_present(Presence.Present(3))
absent: Presence<Int> = Presence.Absent
refute Presence.is_present(absent)
Presence.is_absent
Section titled “Presence.is_absent”fn is_absent<T>(presence: Presence<T>) -> Bool
type function on Presence
Returns True when the value is Absent.
refute Presence.is_absent(Presence.Present(3))
absent: Presence<Int> = Presence.Absent
assert Presence.is_absent(absent)
Presence.map
Section titled “Presence.map”fn map<T, U>(presence: Presence<T>, f: (T) -> U) -> Presence<U>
type function on Presence
Applies f to the value inside Present. Absent stays Absent.
assert Presence.map(Presence.Present(3), &(&1 * 2)) == Presence.Present(6)
assert Presence.map(Presence.Absent, &(&1 * 2)) == Presence.Absent
Presence.with_default
Section titled “Presence.with_default”fn with_default<T>(presence: Presence<T>, current: T) -> T
type function on Presence
Returns the value inside Present, or current when Absent: an input
merged over what is already there, as a PATCH body over a stored
record.
assert Presence.with_default(Presence.Present("new"), "old") == "new"
assert Presence.with_default(Presence.Absent, "old") == "old"
// A PATCH body's `due` clears the stored date with null, keeps it when left out.
stored = Maybe.Some(5)
assert Presence.with_default(Presence.Present(Maybe.None), stored) == Maybe.None
assert Presence.with_default(Presence.Absent, stored) == Maybe.Some(5)
Presence.otherwise
Section titled “Presence.otherwise”fn otherwise<T>(presence: Presence<T>, fallback: Presence<T>) -> Presence<T>
type function on Presence
Returns presence when it is Present, and otherwise fallback: the
layer of input that wins, as flags over the environment over a file.
assert Presence.otherwise(Presence.Present(1), Presence.Present(2)) == Presence.Present(1)
assert Presence.otherwise(Presence.Absent, Presence.Present(2)) == Presence.Present(2)
flag: Presence<Int> = Presence.Absent
env = Presence.Present(8080)
port = flag |> Presence.otherwise(env) |> Presence.with_default(80)
assert port == 8080
Presence.to_maybe
Section titled “Presence.to_maybe”fn to_maybe<T>(presence: Presence<T>) -> Maybe<T>
type function on Presence
Converts Presence to Maybe: Present(v) becomes Some(v), and Absent
becomes None. Where absence is a failure, Presence.to_maybe(p)?
propagates it.
assert Presence.to_maybe(Presence.Present(3)) == Maybe.Some(3)
absent: Presence<Int> = Presence.Absent
assert Presence.to_maybe(absent) == Maybe.None
Presence.flatten
Section titled “Presence.flatten”fn flatten<T>(presence: Presence<Maybe<T>>) -> Maybe<T>
type function on Presence
The value a Presence<Maybe<T>> gives: Some(v) for Present(Some(v)),
and None both when it is Absent and when it is Present(None). It is
the merge of a field that may arrive as null but never clears the
stored value: once validation has refused the null, the field’s new
value is Presence.flatten(p) |> Maybe.with_default(stored).
assert Presence.flatten(Presence.Present(Maybe.Some("a@b.c"))) == Maybe.Some("a@b.c")
assert Presence.flatten(Presence.Present(Maybe.None)) == Maybe.None
absent: Presence<Maybe<String>> = Presence.Absent
assert Presence.flatten(absent) == Maybe.None
email = Presence.Present(Maybe.Some("new@x.org"))
assert Presence.flatten(email) |> Maybe.with_default("old@x.org") == "new@x.org"
Presence.to_json
Section titled “Presence.to_json”impl ToJson for Presence<T>
fn to_json(value: Presence<T>) -> Json
impl ToJson.to_json
Present(v) writes v, and Absent writes null. As a struct
field, Absent writes nothing: to_json_field leaves its key out.
assert ToJson.to_json(Presence.Present(3)) == Json.Int(3)
assert ToJson.to_json_field(Presence.Present(3)) == Maybe.Some(Json.Int(3))
absent: Presence<Int> = Presence.Absent
assert ToJson.to_json_field(absent) == Maybe.None
Presence.to_json_field
Section titled “Presence.to_json_field”impl ToJson for Presence<T>
fn to_json_field(value: Presence<T>) -> Maybe<Json>
impl ToJson.to_json_field
Presence.from_json
Section titled “Presence.from_json”impl FromJson for Presence<T>
fn from_json(json: Json) -> Result<Presence<T>, Json.ShapeError>
impl FromJson.from_json
Reads T as Present, so a JSON null read as a Presence<Maybe<T>>
is Present(None). A missing key of a struct field reads as Absent.
assert FromJson.from_json<Presence<Int>>(Json.Int(3)) == Result.Ok(Presence.Present(3))
assert FromJson.from_json<Presence<Maybe<Int>>>(Json.Null)
== Result.Ok(Presence.Present(Maybe.None))
assert FromJson.from_missing<Presence<Int>>() == Maybe.Some(Presence.Absent)
Presence.from_missing
Section titled “Presence.from_missing”impl FromJson for Presence<T>
fn from_missing() -> Maybe<Presence<T>>
Presence.inspect
Section titled “Presence.inspect”impl Debug for Presence<T>
fn inspect<T>(value: Presence<T>) -> String where T: Debug
impl Debug.inspect
Presence.to_string
Section titled “Presence.to_string”impl Display for Presence<T>
fn to_string<T>(value: Presence<T>) -> String where T: Display
impl Display.to_string
Presence.equal
Section titled “Presence.equal”impl Equatable for Presence<T>
fn equal<T>(a: Presence<T>, b: Presence<T>) -> Bool where T: Equatable
impl Equatable.equal
Presence.hash
Section titled “Presence.hash”impl Hashable for Presence<T>
fn hash<T>(value: Presence<T>) -> Int where T: Hashable
impl Hashable.hash