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

**object**

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

Constructors for optional term references. A reference is either empty or holds a term. References should be regarded as opaque terms and always used with the "optional(_)" object by passing the reference as a parameter.

| **Author:** Paulo Moura
| **Version:** 1.4
| **Date:** 2019/1/23

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


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

Public interface
----------------

.. raw:: html

   <div id="empty/1"> </div>

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

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

Constructs an empty reference.

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

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


.. raw:: html

   <div id="of/2"> </div>

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

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

Constructs a reference holding a term.

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

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


.. raw:: html

   <div id="from_goal/3"> </div>

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

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

Constructs a reference by calling Goal that binds and holds Term on success. Returns an empty reference if the goal fails or throws an error.

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

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


Protected interface
-------------------

(see related entities)

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

(see related entities)

Operators
---------

(none)

Remarks
-------

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

.. seealso::

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

