Did you know ... Search Documentation:
lists.pl -- SICStus 3-compatible library(lists).
PublicShow source
See also
- https://sicstus.sics.se/sicstus/docs/3.12.11/html/sicstus/Lists.html
To be done
- This library is incomplete. As of SICStus 3.12.11, the following predicates are missing:
Source substitute(+OldElem, +List, +NewElem, -NewList) is det
NewList is List with all values that are identical (==) to OldElem replaced by NewElem.
Source nth(?Index, ?List, ?Element) is nondet
True if Element is the N-th element in List. Counting starts at 1.
- use nth1/3.
Source nth(?Index, ?List, ?Element, ?Rest) is nondet
True if Element is the N-th element in List and Rest is the remainder (as if by select/3) of List. Counting starts at 1.
- use nth1/4.
Source same_length(?List1, ?List2, ?Length) is nondet
True if List1 and List2 both have length Length.
Source sublist(?Sub, +List)
True when all members of Sub are members of List in the same order.
- sicstus. The order of generating sublists differs.
- This predicate is known in many Prolog implementations, but the semantics differ. E.g. In YAP it is a continuous sub-list.
Source suffix(?Suffix, ?List) is nondet
True if Suffix is a suffix of List. Not the same as suffix/2 in SICStus 4 - the arguments are reversed!

Re-exported predicates

The following predicates are exported from this file while their implementation is defined in imported modules or non-module files loaded by this module.

Source member(?Elem, ?List)
True if Elem is a member of List. The SWI-Prolog definition differs from the classical one. Our definition avoids unpacking each list element twice and provides determinism on the last element. E.g. this is deterministic:
    member(X, [One]).
- Gertjan van Noord
Source append(?List1, ?List2, ?List1AndList2)
List1AndList2 is the concatenation of List1 and List2
Source prefix(?Part, ?Whole)
True iff Part is a leading substring of Whole. This is the same as append(Part, _, Whole).
Source select(?Elem, ?List1, ?List2)
Is true when List1, with Elem removed, results in List2. This implementation is determinsitic if the last element of List1 has been selected.
Source nextto(?X, ?Y, ?List)
True if Y directly follows X in List.
Source delete(+List1, @Elem, -List2) is det
Delete matching elements from a list. True when List2 is a list with all elements from List1 except for those that unify with Elem. Matching Elem with elements of List1 is uses \+ Elem \= H, which implies that Elem is not changed.
See also
- select/3, subtract/3.
- There are too many ways in which one might want to delete elements from a list to justify the name. Think of matching (= vs. ==), delete first/all, be deterministic or not.
Source nth0(?Index, ?List, ?Elem)
True when Elem is the Index'th element of List. Counting starts at 0.
- type_error(integer, Index) if Index is not an integer or unbound.
See also
- nth1/3.
Source nth0(?N, ?List, ?Elem, ?Rest) is det
Select/insert element at index. True when Elem is the N'th (0-based) element of List and Rest is the remainder (as in by select/3) of List. For example:
?- nth0(I, [a,b,c], E, R).
I = 0, E = a, R = [b, c] ;
I = 1, E = b, R = [a, c] ;
I = 2, E = c, R = [a, b] ;
?- nth0(1, L, a1, [a,b]).
L = [a, a1, b].
Source last(?List, ?Last)
Succeeds when Last is the last element of List. This predicate is semidet if List is a list and multi if List is a partial list.
- There is no de-facto standard for the argument order of last/2. Be careful when porting code or use append(_, [Last], List) as a portable alternative.
Source same_length(?List1, ?List2)
Is true when List1 and List2 are lists with the same number of elements. The predicate is deterministic if at least one of the arguments is a proper list. It is non-deterministic if both arguments are partial lists.
See also
- length/2
Source reverse(?List1, ?List2)
Is true when the elements of List2 are in reverse order compared to List1. This predicate is deterministic if either list is a proper list. If both lists are partial lists backtracking generates increasingly long lists.
Source permutation(?Xs, ?Ys) is nondet
True when Xs is a permutation of Ys. This can solve for Ys given Xs or Xs given Ys, or even enumerate Xs and Ys together. The predicate permutation/2 is primarily intended to generate permutations. Note that a list of length N has N! permutations, and unbounded permutation generation becomes prohibitively expensive, even for rather short lists (10! = 3,628,800).

If both Xs and Ys are provided and both lists have equal length the order is |Xs|^2. Simply testing whether Xs is a permutation of Ys can be achieved in order log(|Xs|) using msort/2 as illustrated below with the semidet predicate is_permutation/2:

is_permutation(Xs, Ys) :-
  msort(Xs, Sorted),
  msort(Ys, Sorted).

The example below illustrates that Xs and Ys being proper lists is not a sufficient condition to use the above replacement.

?- permutation([1,2], [X,Y]).
X = 1, Y = 2 ;
X = 2, Y = 1 ;
- type_error(list, Arg) if either argument is not a proper or partial list.
Source sum_list(+List, -Sum) is det
Sum is the result of adding all numbers in List.
Source max_list(+List:list(number), -Max:number) is semidet
True if Max is the largest number in List. Fails if List is empty.
See also
- max_member/2.
Source min_list(+List:list(number), -Min:number) is semidet
True if Min is the smallest number in List. Fails if List is empty.
See also
- min_member/2.

Undocumented predicates

The following predicates are exported, but not or incorrectly documented.

 memberchk(Arg1, Arg2)