object

optional(Reference)

Optional reference predicates. Requires passing a reference constructed using the “optional” object as a parameter.

Author: Paulo Moura
Version: 1.5
Date: 2019/1/24
Compilation flags:
static, context_switching_calls

(no dependencies on other entities)

Public interface

is_empty/0

True if the reference is empty. Avoid whenever possible by using instead the if_empty/1 predicate.

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

is_present/0

True if the reference holds a term. Avoid whenever possible by using instead 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 reference 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 if the reference holds a term using the term as additional argument. 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

filter/2

Returns the reference when it is non-empty and the term it holds satisfies a closure. Otherwise returns an empty reference.

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

map/2

When the reference is non-empty and mapping a closure with the term it holds and the new term as additional arguments is successful, returns a reference with the new term. Otherwise returns an empty reference.

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

flat_map/2

When the reference is non-empty and mapping a closure with the optional tern and the new reference as additional arguments is successful, returns the new reference. Otherwise returns an empty reference.

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

get/1

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

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

or_else/2

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

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

or_else_get/2

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

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

or_else_call/2

Returns the term hold by the reference if not empty or calls a goal deterministically if the reference is empty. Can be used e.g. to generate an exception for empty optionals.

Compilation flags:
static
Template:
or_else_call(Term,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 term hold by the reference if not empty. Fails otherwise. Usually called to skip over empty references.

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

Protected interface

(none)

Private predicates

(none)

Operators

(none)

Remarks

(none)

See also

optional