.. index:: expected(Reference)
.. _expected/1:

.. rst-class:: right

**object**

``expected(Reference)``
=======================

Expected term reference predicates. Requires passing a reference (constructed using the ``expected`` object) as a parameter.

| **Author:** Paulo Moura
| **Version:** 1.2
| **Date:** 2019/1/24

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


| **Dependencies:**
|   (none)


| **Remarks:**
|    (none)

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

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

.. raw:: html

   <div id="is_unexpected/0"> </div>

.. index:: is_unexpected/0
.. _expected/1::is_unexpected/0:

``is_unexpected/0``
^^^^^^^^^^^^^^^^^^^

True if the reference holds an unexpected term. Avoid whenever possible by using instead the ``if_unexpected/1`` predicate.

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

| **Mode and number of proofs:**
|    ``is_unexpected`` - ``zero_or_one``


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

.. raw:: html

   <div id="is_expected/0"> </div>

.. index:: is_expected/0
.. _expected/1::is_expected/0:

``is_expected/0``
^^^^^^^^^^^^^^^^^

True if the reference holds an expected term. Avoid whenever possible by using instead the ``if_expected/1`` predicate.

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

| **Mode and number of proofs:**
|    ``is_expected`` - ``zero_or_one``


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

.. raw:: html

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

.. index:: if_unexpected/1
.. _expected/1::if_unexpected/1:

``if_unexpected/1``
^^^^^^^^^^^^^^^^^^^

Applies a closure when the reference holds an unexpected term using the term as argument. Succeeds otherwise. Can be used to throw the exception hold by the reference by calling it the atom ``throw``.

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

| **Template:**
|    ``if_unexpected(Closure)``
| **Meta-predicate template:**
|    ``if_unexpected(1)``
| **Mode and number of proofs:**
|    ``if_unexpected(+callable)`` - ``zero_or_more``


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

.. raw:: html

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

.. index:: if_expected/1
.. _expected/1::if_expected/1:

``if_expected/1``
^^^^^^^^^^^^^^^^^

Applies a closure when the reference holds an expected term using the term as argument. Succeeds otherwise.

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

| **Template:**
|    ``if_expected(Closure)``
| **Meta-predicate template:**
|    ``if_expected(1)``
| **Mode and number of proofs:**
|    ``if_expected(+callable)`` - ``zero_or_more``


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

.. raw:: html

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

.. index:: unexpected/1
.. _expected/1::unexpected/1:

``unexpected/1``
^^^^^^^^^^^^^^^^

Returns the unexpected term hold by the reference. Throws an error otherwise.

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

| **Template:**
|    ``unexpected(Unexpected)``
| **Mode and number of proofs:**
|    ``unexpected(--term)`` - ``one_or_error``

| **Exceptions:**
|    Reference holds an expected term:
|        ``existence_error(unexpected_term,Reference)``


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

.. raw:: html

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

.. index:: expected/1
.. _expected/1::expected/1:

``expected/1``
^^^^^^^^^^^^^^

Returns the expected term hold by the reference. Throws an error otherwise.

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

| **Template:**
|    ``expected(Expected)``
| **Mode and number of proofs:**
|    ``expected(--term)`` - ``one_or_error``

| **Exceptions:**
|    Reference holds an unexpected term:
|        ``existence_error(expected_term,Reference)``


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

.. raw:: html

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

.. index:: map/2
.. _expected/1::map/2:

``map/2``
^^^^^^^^^

When the reference does not hold an unexpected term and mapping a closure with the expected term and the new expected term as additional arguments is successful, returns a reference with the new expected term. Otherwise returns the same reference.

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

| **Template:**
|    ``map(Closure,NewReference)``
| **Meta-predicate template:**
|    ``map(2,*)``
| **Mode and number of proofs:**
|    ``map(+callable,--nonvar)`` - ``one``


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

.. raw:: html

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

.. index:: flat_map/2
.. _expected/1::flat_map/2:

``flat_map/2``
^^^^^^^^^^^^^^

When the reference does not hold an unexpected term and mapping a closure with the expected term and the new reference as additional arguments is successful, returns the new reference. Otherwise returns the same reference.

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

| **Template:**
|    ``flat_map(Closure,NewReference)``
| **Meta-predicate template:**
|    ``flat_map(2,*)``
| **Mode and number of proofs:**
|    ``flat_map(+callable,--nonvar)`` - ``one``


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

.. raw:: html

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

.. index:: or_else/2
.. _expected/1::or_else/2:

``or_else/2``
^^^^^^^^^^^^^

Returns the expected term hold by the reference if it does not hold an unexpected term or the given default term if the reference holds an unexpected term.

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

| **Template:**
|    ``or_else(Expected,Default)``
| **Mode and number of proofs:**
|    ``or_else(--term,@term)`` - ``one``


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

.. raw:: html

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

.. index:: or_else_get/2
.. _expected/1::or_else_get/2:

``or_else_get/2``
^^^^^^^^^^^^^^^^^

Returns the expected term hold by the reference if it does not hold an unexpected term. Otherwise applies a closure to compute the expected term. Throws an error when the reference holds an unexpected term and an expected term cannot be computed.

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

| **Template:**
|    ``or_else_get(Expected,Closure)``
| **Meta-predicate template:**
|    ``or_else_get(*,1)``
| **Mode and number of proofs:**
|    ``or_else_get(--term,+callable)`` - ``one_or_error``

| **Exceptions:**
|    Reference holds an unexpected term and an expected term cannot be computed:
|        ``existence_error(expected_term,Reference)``


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

.. raw:: html

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

.. index:: or_else_call/2
.. _expected/1::or_else_call/2:

``or_else_call/2``
^^^^^^^^^^^^^^^^^^

Returns the expected term if the reference does not hold an unexpected term. Calls a goal deterministically otherwise.

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

| **Template:**
|    ``or_else_call(Expected,Goal)``
| **Meta-predicate template:**
|    ``or_else_call(*,0)``
| **Mode and number of proofs:**
|    ``or_else_call(--term,+callable)`` - ``zero_or_one``


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

.. raw:: html

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

.. index:: or_else_throw/1
.. _expected/1::or_else_throw/1:

``or_else_throw/1``
^^^^^^^^^^^^^^^^^^^

Returns the expected term hold by the reference if present. Throws the unexpected term as an error otherwise.

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

| **Template:**
|    ``or_else_throw(Expected)``
| **Mode and number of proofs:**
|    ``or_else_throw(--term)`` - ``one_or_error``


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

.. raw:: html

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

.. index:: or_else_fail/1
.. _expected/1::or_else_fail/1:

``or_else_fail/1``
^^^^^^^^^^^^^^^^^^

Returns the expected term hold by the reference if it does not hold an unexpected term. Fails otherwise. Usually called to skip over references holding unexpected terms.

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

| **Template:**
|    ``or_else_fail(Expected)``
| **Mode and number of proofs:**
|    ``or_else_fail(--term)`` - ``zero_or_one``


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

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

(none)

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

(none)

Operators
---------

(none)

.. seealso::

   :ref:`expected <expected/0>`

