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

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

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

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

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

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

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

The two lists have the same length.

| Compilation flags: | static

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

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

The two lists have the same length.

| Compilation flags: | static

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

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

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

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