.. index:: single: expected(Expected)
.. _expected/1:

.. rst-class:: right

**object**

``expected(Expected)``
======================

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

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

| **Author:** Paulo Moura
| **Version:** 1:6:0
| **Date:** 2026-02-21

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


| **Dependencies:**
|   (none)


| **Remarks:**
|    (none)

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

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

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

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

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

True if the expected term holds a value. See also the ``if_expected/1`` predicate.

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

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


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

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

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

True if the expected term holds an error. See also the ``if_unexpected/1`` predicate.

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

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


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

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

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

Applies a closure when the expected term holds a value using the value 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``


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

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

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

Applies a closure when the expected term holds an error using the error as argument. Succeeds otherwise. Can be used to throw the exception hold by the expected term 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``


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

.. index:: if_expected_or_else/2
.. _expected/1::if_expected_or_else/2:

``if_expected_or_else/2``
^^^^^^^^^^^^^^^^^^^^^^^^^

Applies either ``ExpectedClosure`` or ``UnexpectedClosure`` depending on the expected term holding a value or an error.

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

| **Template:**
|    ``if_expected_or_else(ExpectedClosure,UnexpectedClosure)``
| **Meta-predicate template:**
|    ``if_expected_or_else(1,1)``
| **Mode and number of proofs:**
|    ``if_expected_or_else(+callable,+callable)`` - ``zero_or_more``


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

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

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

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

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

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

| **Exceptions:**
|    Expected term holds a value:
|        ``existence_error(unexpected_error,Expected)``


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

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

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

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

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

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

| **Exceptions:**
|    Expected term holds an error:
|        ``existence_error(expected_value,Expected)``


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

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

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

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

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

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


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

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

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

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

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

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


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

.. index:: either/3
.. _expected/1::either/3:

``either/3``
^^^^^^^^^^^^

Applies either ``ExpectedClosure`` if the expected term holds a value or ``UnexpectedClosure`` if the expected term holds an error. Returns a new expected term if the applied closure is successful. Otherwise returns the same expected term.

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

| **Template:**
|    ``either(ExpectedClosure,UnexpectedClosure,NewExpected)``
| **Meta-predicate template:**
|    ``either(2,2,*)``
| **Mode and number of proofs:**
|    ``either(+callable,+callable,--nonvar)`` - ``one``


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

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

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

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

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

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


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

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

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

Returns the value hold by the expected term if it does not hold an error. Otherwise applies a closure to compute the expected value. Throws an error when the expected term holds an error and a 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:**
|    Expected term holds an unexpected error and an expected value cannot be computed:
|        ``existence_error(expected_value,Expected)``


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

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

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

Returns the value hold by the expected term if it does not hold an error. Calls a goal deterministically otherwise.

| **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_throw/1
.. _expected/1::or_else_throw/1:

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

Returns the value hold by the expected term if present. Throws the error hold by the expected term as an exception otherwise.

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

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


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

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

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

Returns the value hold by the expected term if it does not hold an error. Fails otherwise. Usually called to skip over expected terms holding errors.

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

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


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

.. index:: filter/3
.. _expected/1::filter/3:

``filter/3``
^^^^^^^^^^^^

When the expected term holds a value and the value satisfies the closure, returns the same expected term. When the expected term holds a value that does not satisfy the closure, returns an expected term with the given error. When the expected term holds an error, returns the same expected term.

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

| **Template:**
|    ``filter(Closure,Error,NewExpected)``
| **Meta-predicate template:**
|    ``filter(1,*,*)``
| **Mode and number of proofs:**
|    ``filter(+callable,@term,--nonvar)`` - ``one``


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

.. index:: map_unexpected/2
.. _expected/1::map_unexpected/2:

``map_unexpected/2``
^^^^^^^^^^^^^^^^^^^^

When the expected term holds an error and mapping a closure with the error and the new error as additional arguments is successful, returns an expected term with the new error. Otherwise returns the same expected term.

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

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


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

.. index:: map_catching/2
.. _expected/1::map_catching/2:

``map_catching/2``
^^^^^^^^^^^^^^^^^^

When the expected term holds a value, applies a closure to it. Returns an expected term with the new value if the closure succeeds. Returns an expected term with the error if the closure throws an error. Returns an expected term with the atom ``fail`` as error if the closure fails. When the expected term holds an error, returns the same expected term.

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

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


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

.. index:: map_both/3
.. _expected/1::map_both/3:

``map_both/3``
^^^^^^^^^^^^^^

When the expected term holds a value and mapping ``ExpectedClosure`` with the value is successful, returns an expected term with the new value. When the expected term holds an error and mapping ``UnexpectedClosure`` with the error is successful, returns an expected term with the new error. Otherwise returns the same expected term.

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

| **Template:**
|    ``map_both(ExpectedClosure,UnexpectedClosure,NewExpected)``
| **Meta-predicate template:**
|    ``map_both(2,2,*)``
| **Mode and number of proofs:**
|    ``map_both(+callable,+callable,--nonvar)`` - ``one``


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

.. index:: swap/1
.. _expected/1::swap/1:

``swap/1``
^^^^^^^^^^

Swaps the expected and unexpected terms. If the expected term holds a value, returns an unexpected term with that value. If the expected term holds an error, returns an expected term with that error.

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

| **Template:**
|    ``swap(NewExpected)``
| **Mode and number of proofs:**
|    ``swap(--nonvar)`` - ``one``


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

.. index:: map_or_else/3
.. _expected/1::map_or_else/3:

``map_or_else/3``
^^^^^^^^^^^^^^^^^

When the expected term holds a value and mapping a closure with the value and the new value as additional arguments is successful, returns the new value. Otherwise returns the given default value.

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

| **Template:**
|    ``map_or_else(Closure,Default,Value)``
| **Meta-predicate template:**
|    ``map_or_else(2,*,*)``
| **Mode and number of proofs:**
|    ``map_or_else(+callable,@term,--term)`` - ``one``


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

.. index:: or/2
.. _expected/1::or/2:

``or/2``
^^^^^^^^

Returns the same expected term if it holds a value. Otherwise calls closure to generate a new expected term. Fails if the expected term holds an error and calling the closure fails or throws an error.

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

| **Template:**
|    ``or(NewExpected,Closure)``
| **Meta-predicate template:**
|    ``or(*,1)``
| **Mode and number of proofs:**
|    ``or(--term,@callable)`` - ``zero_or_one``


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

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

``or_else_throw/2``
^^^^^^^^^^^^^^^^^^^

Returns the value hold by the expected term if present. Throws the given error otherwise, ignoring any error hold by the expected term.

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

| **Template:**
|    ``or_else_throw(Value,Error)``
| **Mode and number of proofs:**
|    ``or_else_throw(--term,@nonvar)`` - ``one_or_error``


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

.. index:: zip/3
.. _expected/1::zip/3:

``zip/3``
^^^^^^^^^

When both this expected and the other expected hold values and applying a closure with both values and the new value as additional arguments is successful, returns an expected term with the new value. Otherwise returns the first expected term that holds an error.

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

| **Template:**
|    ``zip(Closure,OtherExpected,NewExpected)``
| **Meta-predicate template:**
|    ``zip(3,*,*)``
| **Mode and number of proofs:**
|    ``zip(+callable,+nonvar,--nonvar)`` - ``one``


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

.. index:: to_optional/1
.. _expected/1::to_optional/1:

``to_optional/1``
^^^^^^^^^^^^^^^^^

Converts the expected term to an optional term. Returns a non-empty optional term holding the value if the expected term holds a value. Returns an empty optional term if the expected term holds an error.

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

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


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

.. index:: flatten/1
.. _expected/1::flatten/1:

``flatten/1``
^^^^^^^^^^^^^

Flattens a nested expected term. When the expected term holds a value that is itself an expected term, returns the inner expected term. When the expected term holds a non-expected value, returns the same expected term. When the expected term holds an error, returns the same expected term.

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

| **Template:**
|    ``flatten(NewExpected)``
| **Mode and number of proofs:**
|    ``flatten(--nonvar)`` - ``one``


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

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

(none)

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

(none)

Operators
---------

(none)

.. seealso::

   :ref:`expected <expected/0>`

