.. index:: 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:7:0 | **Date:** 2019-11-26 | **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`` ------------ Protected predicates -------------------- (none) Private predicates ------------------ (none) Operators --------- (none) .. seealso:: :ref:`optional `