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`
Dependencies:
(none)
Remarks:
(none)

- Public predicates

  - `is_empty/0`

  - `is_present/0`

  - `if_empty/1`

  - `if_present/1`

  - `filter/2`

  - `map/2`

  - `flat_map/2`

  - `get/1`

  - `or_else/2`

  - `or_else_get/2`

  - `or_else_call/2`

  - `or_else_fail/1`

- Protected predicates

- Private predicates

- Operators

## Public predicates

### `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 predicates

(none)

## Private predicates

(none)

## Operators

(none)

See also

optional