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

**protocol**

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

List protocol.

| **Author:** Paulo Moura
| **Version:** 1.15
| **Date:** 2019/1/3

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


(no dependencies on other entities)


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

.. 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).

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

| **Template:**
|    ``nth0(Nth,List,Element,Residue)``
| **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).

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

| **Template:**
|    ``nth1(Nth,List,Element,Residue)``
| **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 keepying 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. @< and @> orders remove duplicates while @=< and @>= orders keep them. @< and @=< specify ascending order while @> and @>= specify descending order. When the key is zero, the whole term is used for comparisons.

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

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


.. 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 interface
-------------------

(none)

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

(none)

Operators
---------

(none)

Remarks
-------

(none)

.. seealso::

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

