.. 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.

| **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 <optional/0>`

