| Did you know ... | Search Documentation: |
 | Pack logtalk -- logtalk-3.98.0/docs/apis/_sources/optional_1.rst.txt |
- HOME
- DOWNLOAD
- DOCUMENTATION
- TUTORIALS
- Beginner▶
- Advanced▶
- Web applications▶
- Semantic web▶
- Graphics▶
- Machine learning▶
- External collections▶
- For packagers▶
- COMMUNITY
- COMMERCIAL
- WIKI
.. index:: single: optional(Optional)
.. _optional/1:
.. rst-class:: right
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)
.. contents:: :local: :backlinks: top
Public predicates
.. index:: is_empty/0 .. _optional/1::is_empty/0:
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
.. index:: is_present/0 .. _optional/1::is_present/0:
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
.. index:: if_empty/1 .. _optional/1::if_empty/1:
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
.. index:: if_present/1 .. _optional/1::if_present/1:
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
.. index:: if_present_or_else/2 .. _optional/1::if_present_or_else/2:
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
.. index:: filter/2 .. _optional/1::filter/2:
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
.. index:: map/2 .. _optional/1::map/2:
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
.. index:: flat_map/2 .. _optional/1::flat_map/2:
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
.. index:: or/2 .. _optional/1::or/2:
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
.. index:: get/1 .. _optional/1::get/1:
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)
.. index:: or_else/2 .. _optional/1::or_else/2:
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
.. index:: or_else_get/2 .. _optional/1::or_else_get/2:
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)
.. index:: or_else_call/2 .. _optional/1::or_else_call/2:
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
.. index:: or_else_fail/1 .. _optional/1::or_else_fail/1:
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
.. index:: or_else_throw/2 .. _optional/1::or_else_throw/2:
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
.. index:: map_or_else/3 .. _optional/1::map_or_else/3:
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
.. index:: zip/3 .. _optional/1::zip/3:
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
.. index:: flatten/1 .. _optional/1::flatten/1:
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
.. index:: to_expected/2 .. _optional/1::to_expected/2:
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)
.. seealso::
:ref:`optional <optional/0>`