.. index:: single: permutations_protocol
.. _permutations_protocol/0:

.. rst-class:: right

**protocol**

``permutations_protocol``
=========================

Protocol for permutations operations over lists.

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

| **Author:** Paulo Moura
| **Version:** 2:0:0
| **Date:** 2026-05-12

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


| **Dependencies:**
|   (none)


| **Remarks:**
|    (none)

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

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

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

.. index:: permutations/2
.. _permutations_protocol/0::permutations/2:

``permutations/2``
^^^^^^^^^^^^^^^^^^

Generates all permutations of a list using default order.

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

| **Template:**
|    ``permutations(List,Permutations)``
| **Mode and number of proofs:**
|    ``permutations(+list,-list)`` - ``one``


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

.. index:: permutation/2
.. _permutations_protocol/0::permutation/2:

``permutation/2``
^^^^^^^^^^^^^^^^^

True iff the second argument is a permutation of the first argument using default order.

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

| **Template:**
|    ``permutation(List,Permutation)``
| **Mode and number of proofs:**
|    ``permutation(+list,-list)`` - ``one_or_more``


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

.. index:: permutations/3
.. _permutations_protocol/0::permutations/3:

``permutations/3``
^^^^^^^^^^^^^^^^^^

Generates all permutations with the given order: ``default``, ``lexicographic``, or ``shortlex``.

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

| **Template:**
|    ``permutations(List,Order,Permutations)``
| **Mode and number of proofs:**
|    ``permutations(+list,+atom,-list)`` - ``one``


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

.. index:: permutation/3
.. _permutations_protocol/0::permutation/3:

``permutation/3``
^^^^^^^^^^^^^^^^^

True iff the third argument is a permutation with the given order: ``default``, ``lexicographic``, or ``shortlex``.

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

| **Template:**
|    ``permutation(List,Order,Permutation)``
| **Mode and number of proofs:**
|    ``permutation(+list,+atom,-list)`` - ``one_or_more``


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

.. index:: distinct_permutations/2
.. _permutations_protocol/0::distinct_permutations/2:

``distinct_permutations/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Generates all distinct permutations of a list (deduplicating repeated values in the input list) using default order.

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

| **Template:**
|    ``distinct_permutations(List,Permutations)``
| **Mode and number of proofs:**
|    ``distinct_permutations(+list,-list)`` - ``one``


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

.. index:: distinct_permutation/2
.. _permutations_protocol/0::distinct_permutation/2:

``distinct_permutation/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^

True iff the second argument is a distinct permutation of the first argument using default order.

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

| **Template:**
|    ``distinct_permutation(List,Permutation)``
| **Mode and number of proofs:**
|    ``distinct_permutation(+list,-list)`` - ``one_or_more``


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

.. index:: distinct_permutations/3
.. _permutations_protocol/0::distinct_permutations/3:

``distinct_permutations/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Generates all distinct permutations with the given order: ``default``, ``lexicographic``, or ``shortlex``.

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

| **Template:**
|    ``distinct_permutations(List,Order,Permutations)``
| **Mode and number of proofs:**
|    ``distinct_permutations(+list,+atom,-list)`` - ``one``


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

.. index:: distinct_permutation/3
.. _permutations_protocol/0::distinct_permutation/3:

``distinct_permutation/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^

True iff the third argument is a distinct permutation with the given order: ``default``, ``lexicographic``, or ``shortlex``.

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

| **Template:**
|    ``distinct_permutation(List,Order,Permutation)``
| **Mode and number of proofs:**
|    ``distinct_permutation(+list,+atom,-list)`` - ``one_or_more``


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

.. index:: k_permutations/3
.. _permutations_protocol/0::k_permutations/3:

``k_permutations/3``
^^^^^^^^^^^^^^^^^^^^

Generates all K-permutations (ordered selections) of a list using default order.

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

| **Template:**
|    ``k_permutations(K,List,Permutations)``
| **Mode and number of proofs:**
|    ``k_permutations(+integer,+list,-list)`` - ``one``


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

.. index:: k_permutation/3
.. _permutations_protocol/0::k_permutation/3:

``k_permutation/3``
^^^^^^^^^^^^^^^^^^^

True iff the third argument is a K-permutation (ordered selection) of a list using default order.

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

| **Template:**
|    ``k_permutation(K,List,Permutation)``
| **Mode and number of proofs:**
|    ``k_permutation(+integer,+list,-list)`` - ``one_or_more``


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

.. index:: k_permutations/4
.. _permutations_protocol/0::k_permutations/4:

``k_permutations/4``
^^^^^^^^^^^^^^^^^^^^

Generates all K-permutations with the given order: ``default``, ``lexicographic``, or ``shortlex``.

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

| **Template:**
|    ``k_permutations(K,List,Order,Permutations)``
| **Mode and number of proofs:**
|    ``k_permutations(+integer,+list,+atom,-list)`` - ``one``


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

.. index:: k_permutation/4
.. _permutations_protocol/0::k_permutation/4:

``k_permutation/4``
^^^^^^^^^^^^^^^^^^^

True iff the fourth argument is a K-permutation with the given order: ``default``, ``lexicographic``, or ``shortlex``.

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

| **Template:**
|    ``k_permutation(K,List,Order,Permutation)``
| **Mode and number of proofs:**
|    ``k_permutation(+integer,+list,+atom,-list)`` - ``one_or_more``


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

.. index:: next_permutation/2
.. _permutations_protocol/0::next_permutation/2:

``next_permutation/2``
^^^^^^^^^^^^^^^^^^^^^^

Returns the next permutation value in lexicographic order.

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

| **Template:**
|    ``next_permutation(Permutation,Next)``
| **Mode and number of proofs:**
|    ``next_permutation(+list,-list)`` - ``zero_or_one``


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

.. index:: previous_permutation/2
.. _permutations_protocol/0::previous_permutation/2:

``previous_permutation/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^

Returns the previous permutation value in lexicographic order.

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

| **Template:**
|    ``previous_permutation(Permutation,Previous)``
| **Mode and number of proofs:**
|    ``previous_permutation(+list,-list)`` - ``zero_or_one``


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

.. index:: nth_permutation/3
.. _permutations_protocol/0::nth_permutation/3:

``nth_permutation/3``
^^^^^^^^^^^^^^^^^^^^^

Returns the permutation at a given zero-based index using default order.

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

| **Template:**
|    ``nth_permutation(List,Index,Permutation)``
| **Mode and number of proofs:**
|    ``nth_permutation(+list,+integer,-list)`` - ``zero_or_one``


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

.. index:: nth_permutation/4
.. _permutations_protocol/0::nth_permutation/4:

``nth_permutation/4``
^^^^^^^^^^^^^^^^^^^^^

Returns the permutation at a given zero-based index in the given order: ``default``, ``lexicographic``, or ``shortlex``.

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

| **Template:**
|    ``nth_permutation(List,Order,Index,Permutation)``
| **Mode and number of proofs:**
|    ``nth_permutation(+list,+atom,+integer,-list)`` - ``zero_or_one``


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

.. index:: permutation_index/3
.. _permutations_protocol/0::permutation_index/3:

``permutation_index/3``
^^^^^^^^^^^^^^^^^^^^^^^

Returns the zero-based index of a permutation using default order.

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

| **Template:**
|    ``permutation_index(List,Permutation,Index)``
| **Mode and number of proofs:**
|    ``permutation_index(+list,+list,-integer)`` - ``zero_or_one``


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

.. index:: permutation_index/4
.. _permutations_protocol/0::permutation_index/4:

``permutation_index/4``
^^^^^^^^^^^^^^^^^^^^^^^

Returns the zero-based index of a permutation in the given order: ``default``, ``lexicographic``, or ``shortlex``.

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

| **Template:**
|    ``permutation_index(List,Order,Permutation,Index)``
| **Mode and number of proofs:**
|    ``permutation_index(+list,+atom,+list,-integer)`` - ``zero_or_one``


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

.. index:: count_permutations/2
.. _permutations_protocol/0::count_permutations/2:

``count_permutations/2``
^^^^^^^^^^^^^^^^^^^^^^^^

Counts the number of permutations of a list.

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

| **Template:**
|    ``count_permutations(List,Count)``
| **Mode and number of proofs:**
|    ``count_permutations(+list,-integer)`` - ``one``


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

.. index:: count_distinct_permutations/2
.. _permutations_protocol/0::count_distinct_permutations/2:

``count_distinct_permutations/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Counts the number of distinct permutations of a list (deduplicating equal-valued permutations).

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

| **Template:**
|    ``count_distinct_permutations(List,Count)``
| **Mode and number of proofs:**
|    ``count_distinct_permutations(+list,-integer)`` - ``one``


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

.. index:: nth_distinct_permutation/3
.. _permutations_protocol/0::nth_distinct_permutation/3:

``nth_distinct_permutation/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Returns the distinct permutation at a given zero-based index in default generation order.

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

| **Template:**
|    ``nth_distinct_permutation(List,Index,Permutation)``
| **Mode and number of proofs:**
|    ``nth_distinct_permutation(+list,+integer,-list)`` - ``zero_or_one``


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

.. index:: distinct_permutation_index/3
.. _permutations_protocol/0::distinct_permutation_index/3:

``distinct_permutation_index/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Returns the zero-based index of a distinct permutation in default generation order.

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

| **Template:**
|    ``distinct_permutation_index(List,Permutation,Index)``
| **Mode and number of proofs:**
|    ``distinct_permutation_index(+list,+list,-integer)`` - ``zero_or_one``


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

.. index:: random_permutation/2
.. _permutations_protocol/0::random_permutation/2:

``random_permutation/2``
^^^^^^^^^^^^^^^^^^^^^^^^

Returns a random permutation of a list.

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

| **Template:**
|    ``random_permutation(List,Permutation)``
| **Mode and number of proofs:**
|    ``random_permutation(+list,-list)`` - ``one``


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

.. index:: sample_permutations/3
.. _permutations_protocol/0::sample_permutations/3:

``sample_permutations/3``
^^^^^^^^^^^^^^^^^^^^^^^^^

Returns SampleCount random permutations of a list, sampled with replacement.

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

| **Template:**
|    ``sample_permutations(List,SampleCount,Samples)``
| **Mode and number of proofs:**
|    ``sample_permutations(+list,+integer,-list)`` - ``zero_or_one``


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

.. index:: random_distinct_permutation/2
.. _permutations_protocol/0::random_distinct_permutation/2:

``random_distinct_permutation/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Returns a random distinct permutation of a list (deduplicating equal-valued permutations).

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

| **Template:**
|    ``random_distinct_permutation(List,Permutation)``
| **Mode and number of proofs:**
|    ``random_distinct_permutation(+list,-list)`` - ``one``


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

.. index:: sample_distinct_permutations/3
.. _permutations_protocol/0::sample_distinct_permutations/3:

``sample_distinct_permutations/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Returns SampleCount random distinct permutations of a list, sampled with replacement after deduplicating equal-valued permutations.

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

| **Template:**
|    ``sample_distinct_permutations(List,SampleCount,Samples)``
| **Mode and number of proofs:**
|    ``sample_distinct_permutations(+list,+integer,-list)`` - ``zero_or_one``


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

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

(none)

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

(none)

Operators
---------

(none)

