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

.. rst-class:: right

**protocol**

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

List protocol.

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

| **Author:** Paulo Moura
| **Version:** 1:18:0
| **Date:** 2024-05-24

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


| **Dependencies:**
|   (none)


| **Remarks:**
|    (none)

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

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

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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

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

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

Nth element of a list (counting from zero). ``Rest`` is a list of all the other elements. 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``


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

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


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

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

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

Nth element of a list (counting from one). ``Rest`` is a list of all the other elements. 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``


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

.. index:: sequential_occurrences/2
.. _listp/0::sequential_occurrences/2:

``sequential_occurrences/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Counts the number of sequential occurrences of each ``List`` element, unifying ``Occurrences`` with a list of ``Element-Count`` pairs. Uses term equality for element comparison.

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

| **Template:**
|    ``sequential_occurrences(List,Occurrences)``
| **Mode and number of proofs:**
|    ``sequential_occurrences(@list,-list(pair(term,positive_integer)))`` - ``one``


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

.. index:: sequential_occurrences/3
.. _listp/0::sequential_occurrences/3:

``sequential_occurrences/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Counts the number of sequential occurrences of each ``List`` element, unifying ``Occurrences`` with a list of ``Element-Count`` pairs. Uses ``Closure`` for element comparison.

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

| **Template:**
|    ``sequential_occurrences(List,Closure,Occurrences)``
| **Mode and number of proofs:**
|    ``sequential_occurrences(@list,@callable,-list(pair(term,positive_integer)))`` - ``one``


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

.. index:: occurrences/2
.. _listp/0::occurrences/2:

``occurrences/2``
^^^^^^^^^^^^^^^^^

Counts the number of occurrences of each ``List`` element, unifying ``Occurrences`` with a sorted list of ``Element-Count`` pairs. Uses term equality for element comparison.

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

| **Template:**
|    ``occurrences(List,Occurrences)``
| **Mode and number of proofs:**
|    ``occurrences(@list,-list(pair(term,positive_integer)))`` - ``one``


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

.. index:: occurrences/3
.. _listp/0::occurrences/3:

``occurrences/3``
^^^^^^^^^^^^^^^^^

Counts the number of occurrences of each ``List`` element, unifying ``Occurrences`` with a sorted list of ``Element-Count`` pairs. Uses ``Closure`` for element comparison.

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

| **Template:**
|    ``occurrences(List,Closure,Occurrences)``
| **Meta-predicate template:**
|    ``occurrences(*,2,*)``
| **Mode and number of proofs:**
|    ``occurrences(@list,@callable,-list(pair(term,positive_integer)))`` - ``one``


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

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


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

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


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

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


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

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


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

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


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

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


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

.. 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)``
| **Mode and number of proofs:**
|    ``remove_duplicates(+list,-list)`` - ``one``


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

.. 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)`` - ``zero_or_one``
|    ``reverse(?list,+list)`` - ``zero_or_one``
|    ``reverse(-list,-list)`` - ``one_or_more``


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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

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

