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

.. rst-class:: right

**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/1`` 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>`

| **Remarks:**


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

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

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

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

(see entity ancestors)

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

(see entity ancestors)

Operators
---------

(none)

.. seealso::

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

