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:7:0

Date: 2019-11-26

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

---

Protected predicates

(none)

Private predicates

(none)

Operators

(none)

See also

optional