.. index:: single: optional
.. _optional/0:

.. rst-class:: right

**object**

``optional``
============

Constructors for optional terms. An optional term is either empty or holds a value. Optional terms should be regarded as opaque terms and always used with the ``optional/1`` object by passing the optional term as a parameter.

| **Availability:** 
|    ``logtalk_load(optionals(loader))``

| **Author:** Paulo Moura
| **Version:** 2:1:0
| **Date:** 2021-01-03

| **Compilation flags:**
|    ``static, context_switching_calls``


| **Provides:**
|    :ref:`type::type/1 <type/0::type/1>`
|    :ref:`type::check/2 <type/0::check/2>`

| **Remarks:**

   - Type-checking support: This object also defines a type ``optional`` for use with the ``type`` library object.

| **Inherited public predicates:**
|    (none)

.. contents::
   :local:
   :backlinks: top

Public predicates
-----------------

.. index:: empty/1
.. _optional/0::empty/1:

``empty/1``
^^^^^^^^^^^

Constructs an empty optional term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``empty(Optional)``
| **Mode and number of proofs:**
|    ``empty(--nonvar)`` - ``one``


------------

.. index:: of/2
.. _optional/0::of/2:

``of/2``
^^^^^^^^

Constructs an optional term holding the given value.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``of(Value,Optional)``
| **Mode and number of proofs:**
|    ``of(@term,--nonvar)`` - ``one``


------------

.. index:: from_goal/3
.. _optional/0::from_goal/3:

``from_goal/3``
^^^^^^^^^^^^^^^

Constructs an optional term holding a value bound by calling the given goal. Returns an empty optional term if the goal fails or throws an error.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``from_goal(Goal,Value,Optional)``
| **Meta-predicate template:**
|    ``from_goal(0,*,*)``
| **Mode and number of proofs:**
|    ``from_goal(+callable,--term,--nonvar)`` - ``one``


------------

.. index:: from_goal/2
.. _optional/0::from_goal/2:

``from_goal/2``
^^^^^^^^^^^^^^^

Constructs an optional term holding a value bound by calling the given closure. Returns an empty optional term if the closure fails or throws an error.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``from_goal(Closure,Optional)``
| **Meta-predicate template:**
|    ``from_goal(1,*)``
| **Mode and number of proofs:**
|    ``from_goal(+callable,--nonvar)`` - ``one``


------------

.. index:: from_generator/3
.. _optional/0::from_generator/3:

``from_generator/3``
^^^^^^^^^^^^^^^^^^^^

Constructs optional terms with the values generated by calling the given goal. On goal error or failure, returns an empty optional.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``from_generator(Goal,Value,Optional)``
| **Meta-predicate template:**
|    ``from_generator(0,*,*)``
| **Mode and number of proofs:**
|    ``from_generator(+callable,--term,--nonvar)`` - ``one_or_more``


------------

.. index:: from_generator/2
.. _optional/0::from_generator/2:

``from_generator/2``
^^^^^^^^^^^^^^^^^^^^

Constructs optional terms with the values generated by calling the given closure. On closure error or failure, returns an empty optional.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``from_generator(Closure,Optional)``
| **Meta-predicate template:**
|    ``from_generator(1,*)``
| **Mode and number of proofs:**
|    ``from_generator(+from_generator,--nonvar)`` - ``one_or_more``


------------

Protected predicates
--------------------

(no local declarations; see entity ancestors if any)

Private predicates
------------------

(no local declarations; see entity ancestors if any)

Operators
---------

(none)

.. seealso::

   :ref:`optional(Optional) <optional/1>`, :ref:`type <type/0>`