object

optional(Optional)

Optional term handling predicates. Requires passing an optional term (constructed using the optional object predicates) as a parameter.

Availability:
logtalk_load(optionals(loader))
Author: Paulo Moura
Version: 1:9:0
Date: 2025-06-19
Compilation flags:
static, context_switching_calls
Dependencies:
(none)
Remarks:
(none)
Inherited public predicates:
(none)

Public predicates

is_empty/0

True if the optional term is empty. See also the if_empty/1 predicate.

Compilation flags:
static
Mode and number of proofs:
is_empty - zero_or_one

is_present/0

True if the optional term holds a value. See also the if_present/1 predicate.

Compilation flags:
static
Mode and number of proofs:
is_present - zero_or_one

if_empty/1

Calls a goal if the optional term is empty. Succeeds otherwise.

Compilation flags:
static
Template:
if_empty(Goal)
Meta-predicate template:
if_empty(0)
Mode and number of proofs:
if_empty(+callable) - zero_or_more

if_present/1

Applies a closure to the value hold by the optional term if not empty. Succeeds otherwise.

Compilation flags:
static
Template:
if_present(Closure)
Meta-predicate template:
if_present(1)
Mode and number of proofs:
if_present(+callable) - zero_or_more

if_present_or_else/2

Applies a closure to the value hold by the optional term if not empty. Otherwise calls the given goal.

Compilation flags:
static
Template:
if_present_or_else(Closure,Goal)
Meta-predicate template:
if_present_or_else(1,0)
Mode and number of proofs:
if_present_or_else(+callable,+callable) - zero_or_more

filter/2

Returns the optional term when it is not empty and the value it holds satisfies a closure. Otherwise returns an empty optional term.

Compilation flags:
static
Template:
filter(Closure,NewOptional)
Meta-predicate template:
filter(1,*)
Mode and number of proofs:
filter(+callable,--nonvar) - one

map/2

When the optional term is not empty and mapping a closure with the value it holds and the new value as additional arguments is successful, returns an optional term with the new value. Otherwise returns an empty optional term.

Compilation flags:
static
Template:
map(Closure,NewOptional)
Meta-predicate template:
map(2,*)
Mode and number of proofs:
map(+callable,--nonvar) - one

flat_map/2

When the optional term is not empty and mapping a closure with the value it holds and the new optional term as additional arguments is successful, returns the new optional term. Otherwise returns an empty optional term.

Compilation flags:
static
Template:
flat_map(Closure,NewOptional)
Meta-predicate template:
flat_map(2,*)
Mode and number of proofs:
flat_map(+callable,--nonvar) - one

or/2

Returns the same optional term if not empty. Otherwise calls closure to generate a new optional term. Fails if optional term is empty and calling the closure fails or throws an error.

Compilation flags:
static
Template:
or(NewOptional,Closure)
Meta-predicate template:
or(*,1)
Mode and number of proofs:
or(--term,@callable) - zero_or_one

get/1

Returns the value hold by the optional term if not empty. Throws an error otherwise.

Compilation flags:
static
Template:
get(Value)
Mode and number of proofs:
get(--term) - one_or_error
Exceptions:
Optional is empty:
existence_error(optional_term,Optional)

or_else/2

Returns the value hold by the optional term if not empty or the given default value if the optional term is empty.

Compilation flags:
static
Template:
or_else(Value,Default)
Mode and number of proofs:
or_else(--term,@term) - one

or_else_get/2

Returns the value hold by the optional term if not empty. Applies a closure to compute the value otherwise. Throws an error when the optional term is empty and the value cannot be computed.

Compilation flags:
static
Template:
or_else_get(Value,Closure)
Meta-predicate template:
or_else_get(*,1)
Mode and number of proofs:
or_else_get(--term,+callable) - one_or_error
Exceptions:
Optional is empty and the term cannot be computed:
existence_error(optional_term,Optional)

or_else_call/2

Returns the value hold by the optional term if not empty or calls a goal deterministically if the optional term is empty.

Compilation flags:
static
Template:
or_else_call(Value,Goal)
Meta-predicate template:
or_else_call(*,0)
Mode and number of proofs:
or_else_call(--term,+callable) - zero_or_one

or_else_fail/1

Returns the value hold by the optional term if not empty. Fails otherwise. Usually called to skip over empty optional terms.

Compilation flags:
static
Template:
or_else_fail(Value)
Mode and number of proofs:
or_else_fail(--term) - zero_or_one

or_else_throw/2

Returns the value hold by the optional term if not empty. Throws the given error otherwise.

Compilation flags:
static
Template:
or_else_throw(Value,Error)
Mode and number of proofs:
or_else_throw(--term,@nonvar) - one_or_error

map_or_else/3

When the optional term is not empty and mapping a closure with the value it holds and the new value as additional arguments is successful, returns the new value. Otherwise returns the given default value.

Compilation flags:
static
Template:
map_or_else(Closure,Default,Value)
Meta-predicate template:
map_or_else(2,*,*)
Mode and number of proofs:
map_or_else(+callable,@term,--term) - one

zip/3

When both this optional and the other optional hold values and applying a closure with both values and the new value as additional arguments is successful, returns an optional term with the new value. Otherwise returns an empty optional term.

Compilation flags:
static
Template:
zip(Closure,OtherOptional,NewOptional)
Meta-predicate template:
zip(3,*,*)
Mode and number of proofs:
zip(+callable,+nonvar,--nonvar) - one

flatten/1

Flattens a nested optional term. When the optional term holds a value that is itself an optional term, returns the inner optional term. When the optional term holds a non-optional value, returns the same optional term. When the optional term is empty, returns an empty optional term.

Compilation flags:
static
Template:
flatten(NewOptional)
Mode and number of proofs:
flatten(--nonvar) - one

to_expected/2

Converts the optional term to an expected term. Returns an expected term holding the value if the optional term is not empty. Returns an expected term with the given error otherwise.

Compilation flags:
static
Template:
to_expected(Error,Expected)
Mode and number of proofs:
to_expected(@term,--nonvar) - one

Protected predicates

(none)

Private predicates

(none)

Operators

(none)

See also

optional