.. index:: listp
.. _listp/0:

.. rst-class:: right

**protocol**

``listp``
=========

List protocol.

| **Author:** Paulo Moura
| **Version:** 1:15:1
| **Date:** 2020-05-11

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


| **Dependencies:**
|   (none)


| **Remarks:**
|    (none)

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

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

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

.. raw:: html

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

.. index:: append/2
.. _listp/0::append/2:

``append/2``
^^^^^^^^^^^^

Appends all lists in a list of lists.

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

| **Template:**
|    ``append(Lists,Concatenation)``
| **Mode and number of proofs:**
|    ``append(+list(list),?list)`` - ``zero_or_one``


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

.. raw:: html

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

.. index:: append/3
.. _listp/0::append/3:

``append/3``
^^^^^^^^^^^^

Appends two lists.

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

| **Template:**
|    ``append(List1,List2,List)``
| **Mode and number of proofs:**
|    ``append(?list,?list,?list)`` - ``zero_or_more``


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

.. raw:: html

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

.. index:: delete/3
.. _listp/0::delete/3:

``delete/3``
^^^^^^^^^^^^

Deletes from a list all occurrences of an element returning the list of remaining elements. Uses ``==/2`` for element comparison.

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

| **Template:**
|    ``delete(List,Element,Remaining)``
| **Mode and number of proofs:**
|    ``delete(@list,@term,?list)`` - ``one``


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

.. raw:: html

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

.. index:: delete_matches/3
.. _listp/0::delete_matches/3:

``delete_matches/3``
^^^^^^^^^^^^^^^^^^^^

Deletes all matching elements from a list, returning the list of remaining elements. Uses ``=/2`` for element comparison.

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

| **Template:**
|    ``delete_matches(List,Element,Remaining)``
| **Mode and number of proofs:**
|    ``delete_matches(@list,@term,?list)`` - ``one``


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

.. raw:: html

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

.. index:: empty/1
.. _listp/0::empty/1:

``empty/1``
^^^^^^^^^^^

True if the argument is an empty list.

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

| **Template:**
|    ``empty(List)``
| **Mode and number of proofs:**
|    ``empty(@list)`` - ``zero_or_one``


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

.. raw:: html

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

.. index:: flatten/2
.. _listp/0::flatten/2:

``flatten/2``
^^^^^^^^^^^^^

Flattens a list of lists into a list.

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

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


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

.. raw:: html

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

.. index:: hamming_distance/3
.. _listp/0::hamming_distance/3:

``hamming_distance/3``
^^^^^^^^^^^^^^^^^^^^^^

Calculates the Hamming distance between two lists (using equality to compare list elements). Fails if the two lists are not of the same length.

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

| **Template:**
|    ``hamming_distance(List1,List2,Distance)``
| **Mode and number of proofs:**
|    ``hamming_distance(+list,+list,-integer)`` - ``zero_or_one``


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

.. raw:: html

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

.. index:: keysort/2
.. _listp/0::keysort/2:

``keysort/2``
^^^^^^^^^^^^^

Sorts a list of key-value pairs in ascending order.

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

| **Template:**
|    ``keysort(List,Sorted)``
| **Mode and number of proofs:**
|    ``keysort(+list(pair),-list(pair))`` - ``one``


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

.. raw:: html

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

.. index:: last/2
.. _listp/0::last/2:

``last/2``
^^^^^^^^^^

List last element (if it exists).

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

| **Template:**
|    ``last(List,Last)``
| **Mode and number of proofs:**
|    ``last(?list,?term)`` - ``zero_or_more``


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

.. raw:: html

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

.. index:: length/2
.. _listp/0::length/2:

``length/2``
^^^^^^^^^^^^

List length.

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

| **Template:**
|    ``length(List,Length)``
| **Mode and number of proofs:**
|    ``length(?list,?integer)`` - ``zero_or_more``


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

.. raw:: html

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

.. index:: max/2
.. _listp/0::max/2:

``max/2``
^^^^^^^^^

Determines the list maximum value using standard order. Fails if the list is empty.

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

| **Template:**
|    ``max(List,Maximum)``
| **Mode and number of proofs:**
|    ``max(+list,-term)`` - ``zero_or_one``


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

.. raw:: html

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

.. index:: member/2
.. _listp/0::member/2:

``member/2``
^^^^^^^^^^^^

Element is a list member.

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

| **Template:**
|    ``member(Element,List)``
| **Mode and number of proofs:**
|    ``member(?term,?list)`` - ``zero_or_more``


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

.. raw:: html

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

.. index:: memberchk/2
.. _listp/0::memberchk/2:

``memberchk/2``
^^^^^^^^^^^^^^^

Checks if a term is a member of a list.

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

| **Template:**
|    ``memberchk(Element,List)``
| **Mode and number of proofs:**
|    ``memberchk(?term,?list)`` - ``zero_or_one``


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

.. raw:: html

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

.. index:: min/2
.. _listp/0::min/2:

``min/2``
^^^^^^^^^

Determines the minimum value in a list using standard order. Fails if the list is empty.

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

| **Template:**
|    ``min(List,Minimum)``
| **Mode and number of proofs:**
|    ``min(+list,-term)`` - ``zero_or_one``


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

.. raw:: html

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

.. index:: msort/2
.. _listp/0::msort/2:

``msort/2``
^^^^^^^^^^^

Sorts a list in ascending order (duplicated elements are not removed).

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

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


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

.. raw:: html

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

.. index:: msort/3
.. _listp/0::msort/3:

``msort/3``
^^^^^^^^^^^

Sorts a list using a user-specified comparison predicate modeled on the standard ``compare/3`` predicate (duplicated elements are not removed).

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

| **Template:**
|    ``msort(Closure,List,Sorted)``
| **Meta-predicate template:**
|    ``msort(3,*,*)``
| **Mode and number of proofs:**
|    ``msort(+callable,+list,-list)`` - ``one``


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

.. raw:: html

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

.. index:: nextto/3
.. _listp/0::nextto/3:

``nextto/3``
^^^^^^^^^^^^

``X`` and ``Y`` are consecutive elements in List.

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

| **Template:**
|    ``nextto(X,Y,List)``
| **Mode and number of proofs:**
|    ``nextto(?term,?term,?list)`` - ``zero_or_more``


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

.. raw:: html

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

.. index:: nth0/3
.. _listp/0::nth0/3:

``nth0/3``
^^^^^^^^^^

Nth element of a list (counting from zero).

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

| **Template:**
|    ``nth0(Nth,List,Element)``
| **Mode and number of proofs:**
|    ``nth0(?integer,?list,?term)`` - ``zero_or_more``


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

.. raw:: html

   <div id="nth0/4"> </div>

.. index:: nth0/4
.. _listp/0::nth0/4:

``nth0/4``
^^^^^^^^^^

Nth element of a list (counting from zero). Can be used to either select the nth element of ``List`` or to insert an element before the nth element in ``Rest``.

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

| **Template:**
|    ``nth0(Nth,List,Element,Rest)``
| **Mode and number of proofs:**
|    ``nth0(?integer,?list,?term,?list)`` - ``zero_or_more``


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

.. raw:: html

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

.. index:: nth1/3
.. _listp/0::nth1/3:

``nth1/3``
^^^^^^^^^^

Nth element of a list (counting from one).

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

| **Template:**
|    ``nth1(Nth,List,Element)``
| **Mode and number of proofs:**
|    ``nth1(?integer,?list,?term)`` - ``zero_or_more``


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

.. raw:: html

   <div id="nth1/4"> </div>

.. index:: nth1/4
.. _listp/0::nth1/4:

``nth1/4``
^^^^^^^^^^

Nth element of a list (counting from one). Can be used to either select the nth element of ``List`` or to insert an element before the nth element in ``Rest``.

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

| **Template:**
|    ``nth1(Nth,List,Element,Rest)``
| **Mode and number of proofs:**
|    ``nth1(?integer,?list,?term,?list)`` - ``zero_or_more``


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

.. raw:: html

   <div id="partition/5"> </div>

.. index:: partition/5
.. _listp/0::partition/5:

``partition/5``
^^^^^^^^^^^^^^^

Partitions a list in lists with values less, equal, and greater than a given value (using standard order).

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

| **Template:**
|    ``partition(List,Value,Less,Equal,Greater)``
| **Mode and number of proofs:**
|    ``partition(+list,+number,-list,-list,-list)`` - ``one``


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

.. raw:: html

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

.. index:: permutation/2
.. _listp/0::permutation/2:

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

The two lists are a permutation of the same list.

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

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


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

.. raw:: html

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

.. index:: prefix/2
.. _listp/0::prefix/2:

``prefix/2``
^^^^^^^^^^^^

``Prefix`` is a prefix of ``List``.

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

| **Template:**
|    ``prefix(Prefix,List)``
| **Mode and number of proofs:**
|    ``prefix(?list,+list)`` - ``zero_or_more``


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

.. raw:: html

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

.. index:: prefix/3
.. _listp/0::prefix/3:

``prefix/3``
^^^^^^^^^^^^

``Prefix`` is a prefix of length ``Length`` of ``List``.

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

| **Template:**
|    ``prefix(Prefix,Length,List)``
| **Mode and number of proofs:**
|    ``prefix(?list,+integer,+list)`` - ``zero_or_one``
|    ``prefix(?list,-integer,+list)`` - ``zero_or_more``


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

.. raw:: html

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

.. index:: proper_prefix/2
.. _listp/0::proper_prefix/2:

``proper_prefix/2``
^^^^^^^^^^^^^^^^^^^

``Prefix`` is a proper prefix of ``List``.

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

| **Template:**
|    ``proper_prefix(Prefix,List)``
| **Mode and number of proofs:**
|    ``proper_prefix(?list,+list)`` - ``zero_or_more``


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

.. raw:: html

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

.. index:: proper_prefix/3
.. _listp/0::proper_prefix/3:

``proper_prefix/3``
^^^^^^^^^^^^^^^^^^^

``Prefix`` is a proper prefix of length ``Length`` of ``List``.

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

| **Template:**
|    ``proper_prefix(Prefix,Length,List)``
| **Mode and number of proofs:**
|    ``proper_prefix(?list,+integer,+list)`` - ``zero_or_one``
|    ``proper_prefix(?list,-integer,+list)`` - ``zero_or_more``


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

.. raw:: html

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

.. index:: remove_duplicates/2
.. _listp/0::remove_duplicates/2:

``remove_duplicates/2``
^^^^^^^^^^^^^^^^^^^^^^^

Removes duplicated list elements using equality (``==/2``) for comparison and keeping the left-most element when repeated.

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

| **Template:**
|    ``remove_duplicates(List,Set)``

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

.. raw:: html

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

.. index:: reverse/2
.. _listp/0::reverse/2:

``reverse/2``
^^^^^^^^^^^^^

Reverses a list.

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

| **Template:**
|    ``reverse(List,Reversed)``
| **Mode and number of proofs:**
|    ``reverse(+list,-list)`` - ``one``
|    ``reverse(+list,?list)`` - ``zero_or_one``
|    ``reverse(?list,+list)`` - ``zero_or_one``
|    ``reverse(-list,-list)`` - ``one_or_more``


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

.. raw:: html

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

.. index:: same_length/2
.. _listp/0::same_length/2:

``same_length/2``
^^^^^^^^^^^^^^^^^

The two lists have the same length.

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

| **Template:**
|    ``same_length(List1,List2)``
| **Mode and number of proofs:**
|    ``same_length(+list,?list)`` - ``zero_or_one``
|    ``same_length(?list,+list)`` - ``zero_or_one``
|    ``same_length(-list,-list)`` - ``one_or_more``


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

.. raw:: html

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

.. index:: same_length/3
.. _listp/0::same_length/3:

``same_length/3``
^^^^^^^^^^^^^^^^^

The two lists have the same length.

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

| **Template:**
|    ``same_length(List1,List2,Length)``
| **Mode and number of proofs:**
|    ``same_length(+list,?list,?integer)`` - ``zero_or_one``
|    ``same_length(?list,+list,?integer)`` - ``zero_or_one``
|    ``same_length(-list,-list,-integer)`` - ``one_or_more``


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

.. raw:: html

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

.. index:: select/3
.. _listp/0::select/3:

``select/3``
^^^^^^^^^^^^

Selects an element from a list, returning the list of remaining elements.

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

| **Template:**
|    ``select(Element,List,Remaining)``
| **Mode and number of proofs:**
|    ``select(?term,?list,?list)`` - ``zero_or_more``


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

.. raw:: html

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

.. index:: selectchk/3
.. _listp/0::selectchk/3:

``selectchk/3``
^^^^^^^^^^^^^^^

Checks that an element can be selected from a list, returning the list of remaining elements.

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

| **Template:**
|    ``selectchk(Element,List,Remaining)``
| **Mode and number of proofs:**
|    ``selectchk(?term,?list,?list)`` - ``zero_or_one``


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

.. raw:: html

   <div id="select/4"> </div>

.. index:: select/4
.. _listp/0::select/4:

``select/4``
^^^^^^^^^^^^

Selects an element from a list, replacing it by a new element and returning the resulting list.

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

| **Template:**
|    ``select(Old,OldList,New,NewList)``
| **Mode and number of proofs:**
|    ``select(?term,?list,?term,?list)`` - ``zero_or_more``


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

.. raw:: html

   <div id="selectchk/4"> </div>

.. index:: selectchk/4
.. _listp/0::selectchk/4:

``selectchk/4``
^^^^^^^^^^^^^^^

Checks that an element from a list can be replaced by a new element, returning the resulting list.

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

| **Template:**
|    ``selectchk(Old,OldList,New,NewList)``
| **Mode and number of proofs:**
|    ``selectchk(?term,?list,?term,?list)`` - ``zero_or_one``


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

.. raw:: html

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

.. index:: sort/2
.. _listp/0::sort/2:

``sort/2``
^^^^^^^^^^

Sorts a list in ascending order (duplicated elements are removed).

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

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


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

.. raw:: html

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

.. index:: sort/3
.. _listp/0::sort/3:

``sort/3``
^^^^^^^^^^

Sorts a list using a user-specified comparison predicate modeled on the standard ``compare/3`` predicate (duplicated elements are removed).

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

| **Template:**
|    ``sort(Closure,List,Sorted)``
| **Meta-predicate template:**
|    ``sort(3,*,*)``
| **Mode and number of proofs:**
|    ``sort(+callable,+list,-list)`` - ``one``


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

.. raw:: html

   <div id="sort/4"> </div>

.. index:: sort/4
.. _listp/0::sort/4:

``sort/4``
^^^^^^^^^^

Sorts a list using the given key and order. Uses the standard term comparison operators for the order. The key selects the argument in each element in the list to use for comparisons. A key value of zero uses the whole element for comparisons.

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

| **Template:**
|    ``sort(Key,Order,List,Sorted)``
| **Mode and number of proofs:**
|    ``sort(+non_negative_integer,+atom,+list,-list)`` - ``one``

| **Remarks:**

    - Removing duplicates: Use one of the ``@<`` or ``@>`` orders.
    - Keeping duplicates: Use one of the ``@=<`` or ``@>=`` orders.
    - Sorting in ascending order: Use one of the ``@<`` or ``@=<`` orders.
    - Sorting in descending order: Use one of the ``@>`` or ``@>=`` orders.


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

.. raw:: html

   <div id="split/4"> </div>

.. index:: split/4
.. _listp/0::split/4:

``split/4``
^^^^^^^^^^^

Splits a list into sublists of a given length. Also returns a list with the remaining elements. Fails if the length is zero or negative.

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

| **Template:**
|    ``split(List,Length,Sublists,Remaining)``
| **Mode and number of proofs:**
|    ``split(+list,+integer,-list(list),-list)`` - ``zero_or_one``


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

.. raw:: html

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

.. index:: sublist/2
.. _listp/0::sublist/2:

``sublist/2``
^^^^^^^^^^^^^

The first list is a sublist of the second.

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

| **Template:**
|    ``sublist(Sublist,List)``
| **Mode and number of proofs:**
|    ``sublist(?list,+list)`` - ``zero_or_more``


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

.. raw:: html

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

.. index:: subsequence/3
.. _listp/0::subsequence/3:

``subsequence/3``
^^^^^^^^^^^^^^^^^

``List`` is an interleaving of ``Subsequence`` and ``Remaining``. Element order is preserved.

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

| **Template:**
|    ``subsequence(List,Subsequence,Remaining)``
| **Mode and number of proofs:**
|    ``subsequence(?list,?list,?list)`` - ``zero_or_more``


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

.. raw:: html

   <div id="subsequence/4"> </div>

.. index:: subsequence/4
.. _listp/0::subsequence/4:

``subsequence/4``
^^^^^^^^^^^^^^^^^

Generates subsequences of a given length from a list. Also returns the remaining elements. Element order is preserved.

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

| **Template:**
|    ``subsequence(List,Length,Subsequence,Remaining)``
| **Mode and number of proofs:**
|    ``subsequence(+list,+integer,?list,?list)`` - ``zero_or_more``


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

.. raw:: html

   <div id="substitute/4"> </div>

.. index:: substitute/4
.. _listp/0::substitute/4:

``substitute/4``
^^^^^^^^^^^^^^^^

Substitutes all occurrences of ``Old`` in ``List`` by ``New``, returning ``NewList``. Uses term equality for element comparison.

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

| **Template:**
|    ``substitute(Old,List,New,NewList)``
| **Mode and number of proofs:**
|    ``substitute(@term,@list,@term,-list)`` - ``one``


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

.. raw:: html

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

.. index:: subtract/3
.. _listp/0::subtract/3:

``subtract/3``
^^^^^^^^^^^^^^

Removes all elements in the second list from the first list, returning the list of remaining elements.

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

| **Template:**
|    ``subtract(List,Elements,Remaining)``
| **Mode and number of proofs:**
|    ``subtract(+list,+list,-list)`` - ``one``


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

.. raw:: html

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

.. index:: suffix/2
.. _listp/0::suffix/2:

``suffix/2``
^^^^^^^^^^^^

Suffix is a suffix of List.

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

| **Template:**
|    ``suffix(Suffix,List)``
| **Mode and number of proofs:**
|    ``suffix(?list,+list)`` - ``zero_or_more``


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

.. raw:: html

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

.. index:: suffix/3
.. _listp/0::suffix/3:

``suffix/3``
^^^^^^^^^^^^

``Suffix`` is a suffix of length ``Length`` of ``List``.

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

| **Template:**
|    ``suffix(Suffix,Length,List)``
| **Mode and number of proofs:**
|    ``suffix(?list,+integer,+list)`` - ``zero_or_one``
|    ``suffix(?list,-integer,+list)`` - ``zero_or_more``


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

.. raw:: html

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

.. index:: proper_suffix/2
.. _listp/0::proper_suffix/2:

``proper_suffix/2``
^^^^^^^^^^^^^^^^^^^

``Suffix`` is a proper suffix of ``List``.

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

| **Template:**
|    ``proper_suffix(Suffix,List)``
| **Mode and number of proofs:**
|    ``proper_suffix(?list,+list)`` - ``zero_or_more``


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

.. raw:: html

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

.. index:: proper_suffix/3
.. _listp/0::proper_suffix/3:

``proper_suffix/3``
^^^^^^^^^^^^^^^^^^^

``Suffix`` is a proper suffix of length ``Length`` of ``List``.

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

| **Template:**
|    ``proper_suffix(Suffix,Length,List)``
| **Mode and number of proofs:**
|    ``proper_suffix(?list,+integer,+list)`` - ``zero_or_one``
|    ``proper_suffix(?list,-integer,+list)`` - ``zero_or_more``


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

.. raw:: html

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

.. index:: take/3
.. _listp/0::take/3:

``take/3``
^^^^^^^^^^

Takes the first ``N`` elements of a list. Fails if the list have fewer than ``N`` elements.

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

| **Template:**
|    ``take(N,List,Elements)``
| **Mode and number of proofs:**
|    ``take(+integer,+list,-list)`` - ``zero_or_one``


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

.. raw:: html

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

.. index:: drop/3
.. _listp/0::drop/3:

``drop/3``
^^^^^^^^^^

Drops the first ``N`` elements of a list. Fails if the list have fewer than ``N`` elements.

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

| **Template:**
|    ``drop(N,List,Remaining)``
| **Mode and number of proofs:**
|    ``drop(+integer,+list,-list)`` - ``zero_or_one``


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

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

(none)

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

(none)

Operators
---------

(none)

.. seealso::

   :ref:`list <list/0>`, :ref:`list(Type) <list/1>`, :ref:`numberlistp <numberlistp/0>`, :ref:`varlistp <varlistp/0>`

