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

**category**

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

Adds predicates for generating random values for selected types to the library "type" object.

| **Author:** Paulo Moura
| **Version:** 2.3
| **Date:** 2019/3/27

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



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

.. 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 given type is not supported. A new generator can be added by defining a clause for this predicate and registering it by adding a clause for the arbitrary/1 multifile 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. Fails if the given type is not supported or if shrinking the value is not possible. Support for a new type can be added by defining a clause for this predicate. Must always generate a finite number of solutions.

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


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

(see related entities)

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

(see related entities)

Operators
---------

(none)

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}

* **Base types from Prolog**: {term, var, nonvar, atomic, atom, number, integer, float, compound, callable, ground}

* **Atom derived types**: {atom(CharSet), non_empty_atom, non_empty_atom(CharSet), boolean, character, character(CharSet), char (same as character), char(CharSet) (same as character(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 (same as character_code), code(CharSet) (same as character_code(CharSet)), operator_priority}

* **List types (compound derived types)**: {list, non_empty_list, partial_list, list_or_partial_list, list(Type), list(Type, Min, Max), non_empty_list(Type), difference_list, difference_list(Type), codes (same as list(character_code)), chars (same as list(character))}

* **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**: New types can be registered by defining clauses for the arbitrary/1-2 multifile predicates and optionally for the shrinker/1 and shrink/3 multifile predicates. Clauses for the predicates must have a bound first argument to avoid introducing spurious choice-points.

* **Character sets**: When generating character or character codes, or terms that contain them (e.g. atom), it is possible to choose a character set (ascii_identifier, ascii_printable, ascii_full, byte, unicode_bmp, or unicode_full) using the parameterizable types. Default 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 to the predicates is not type-checked for performance reasons.

.. seealso::

   :ref:`type <type/0>`

