.. index:: arbitrary
.. _arbitrary/0:

.. rst-class:: right

**category**

``arbitrary``
=============

Adds predicates for generating and shrinking random values for selected types to the library ``type`` object. User extensible.

| **Author:** Paulo Moura
| **Version:** 2:15:0
| **Date:** 2020-04-19

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


| **Complements:**
|    :ref:`type <type/0>`
| **Uses:**
|    :ref:`fast_random <fast_random/0>`
|    :ref:`integer <integer/0>`
|    :ref:`list <list/0>`
|    :ref:`type <type/0>`

| **Remarks:**

   - Logtalk specific types: ``entity``, ``object``, ``protocol``, ``category``, ``entity_identifier``, ``object_identifier``, ``protocol_identifier``, ``category_identifier``, ``event``, ``predicate``
   - Prolog module related types (when the backend compiler supports modules): ``module``, ``module_identifier``, ``qualified_callable``
   - Prolog base types: ``term``, ``var``, ``nonvar``, ``atomic``, ``atom``, ``number``, ``integer``, ``float``, ``compound``, ``callable``, ``ground``
   - Atom derived types: ``atom(CharSet)``, ``atom(CharSet,Length)``, ``non_empty_atom``, ``non_empty_atom(CharSet)``, ``boolean``, ``character``, ``character(CharSet)``, ``char``, ``char(CharSet)``, ``operator_specifier``
   - Number derived types: ``positive_number``, ``negative_number``, ``non_positive_number``, ``non_negative_number``
   - Float derived types: ``positive_float``, ``negative_float``, ``non_positive_float``, ``non_negative_float``, ``probability``
   - Integer derived types: ``positive_integer``, ``negative_integer``, ``non_positive_integer``, ``non_negative_integer``, ``byte``, ``character_code``, ``character_code(CharSet)``, ``code``, ``code(CharSet)``, ``operator_priority``
   - List types (compound derived types): ``list``, ``non_empty_list``, ``partial_list``, ``list_or_partial_list``, ``list(Type)``, ``list(Type,Length)``, ``list(Type,Min,Max)``, ``list(Type,Length,Min,Max)``, ``non_empty_list(Type)``, ``codes``, ``chars``
   - Difference list types (compound derived types): ``difference_list``, ``difference_list(Type)``
   - Other compound derived types: ``predicate_indicator``, ``non_terminal_indicator``, ``predicate_or_non_terminal_indicator``, ``clause``, ``clause_or_partial_clause``, ``grammar_rule``, ``pair``, ``pair(KeyType,ValueType)``
   - Other types: ``between(Type,Lower,Upper)``, ``property(Type,LambdaExpression)``, ``one_of(Type,Set)``, ``var_or(Type)``, ``ground(Type)``, ``types(Types)``
   - Registering new types: Add clauses for the ``arbitrary/1-2`` multifile predicates and optionally for the ``shrinker/1`` and ``shrink/3`` multifile predicates. The clauses must have a bound first argument to avoid introducing spurious choice-points.
   - Character sets: ``ascii_identifier``, ``ascii_printable``, ``ascii_full``, ``byte``, ``unicode_bmp``, ``unicode_full``
   - Default character sets: The default character set when using a parameterizable type that takes a character set parameter depends on the type.
   - Default character sets: Entity, predicate, and non-terminal identifier types plus compound and callable types default to an ``ascii_identifier`` functor. Character and character code types default to ``ascii_full``. Other types default to ``ascii_printable``.
   - Caveats: The type argument (and any type parameterization) to the predicates is not type-checked (or checked for consistency) for performance reasons.

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

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

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

.. raw:: html

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

.. index:: arbitrary/1
.. _arbitrary/0::arbitrary/1:

``arbitrary/1``
^^^^^^^^^^^^^^^

Table of defined types for which an arbitrary value can be generated. A new type can be registered by defining a clause for this predicate and adding a clause for the ``arbitrary/2`` multifile predicate.

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

| **Template:**
|    ``arbitrary(Type)``
| **Mode and number of proofs:**
|    ``arbitrary(?callable)`` - ``zero_or_more``


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

.. raw:: html

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

.. index:: arbitrary/2
.. _arbitrary/0::arbitrary/2:

``arbitrary/2``
^^^^^^^^^^^^^^^

Generates an arbitrary term of the specified type. Fails if the type is not supported. A new generator can be defined by adding a clause for this predicate and registering it via the ``arbitrary/1`` predicate.

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

| **Template:**
|    ``arbitrary(Type,Term)``
| **Mode and number of proofs:**
|    ``arbitrary(@callable,-term)`` - ``zero_or_one``


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

.. raw:: html

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

.. index:: shrinker/1
.. _arbitrary/0::shrinker/1:

``shrinker/1``
^^^^^^^^^^^^^^

Table of defined types for which a shrinker is provided. A new shrinker can be registered by defining a clause for this predicate and adding a definition for the ``shrink/3`` multifile predicate.

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

| **Template:**
|    ``shrinker(Type)``
| **Mode and number of proofs:**
|    ``shrinker(?callable)`` - ``zero_or_more``


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

.. raw:: html

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

.. index:: shrink/3
.. _arbitrary/0::shrink/3:

``shrink/3``
^^^^^^^^^^^^

Shrinks a value to a smaller value if possible. Must generate a finite number of solutions. Fails if the type is not supported. A new shrinker can be defined by adding a clause for this predicate and registering it via the ``shrinker/1`` predicate.

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

| **Template:**
|    ``shrink(Type,Large,Small)``
| **Mode and number of proofs:**
|    ``shrink(@callable,@term,-term)`` - ``zero_or_more``


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

.. raw:: html

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

.. index:: edge_case/2
.. _arbitrary/0::edge_case/2:

``edge_case/2``
^^^^^^^^^^^^^^^

Table of type edge cases. Fails if the given type have no defined edge cases. New edge cases for existing or new types can be added by defining a clause for this multifile predicate.

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

| **Template:**
|    ``edge_case(Type,Term)``
| **Mode and number of proofs:**
|    ``edge_case(?callable,?term)`` - ``zero_or_more``


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

.. raw:: html

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

.. index:: get_seed/1
.. _arbitrary/0::get_seed/1:

``get_seed/1``
^^^^^^^^^^^^^^

Gets the current random generator seed. Seed should be regarded as an opaque ground term.

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

| **Template:**
|    ``get_seed(Seed)``
| **Mode and number of proofs:**
|    ``get_seed(-ground)`` - ``one``


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

.. raw:: html

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

.. index:: set_seed/1
.. _arbitrary/0::set_seed/1:

``set_seed/1``
^^^^^^^^^^^^^^

Sets the random generator seed to a given value returned by calling the ``get_seed/1`` predicate.

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

| **Template:**
|    ``set_seed(Seed)``
| **Mode and number of proofs:**
|    ``set_seed(+ground)`` - ``one``


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

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

(no local declarations; see entity ancestors if any)

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

(no local declarations; see entity ancestors if any)

Operators
---------

(none)

.. seealso::

   :ref:`type <type/0>`

