lists.pl -- SICStus 3-compatible library(lists).

To be done

- This library is incomplete. As of SICStus 3.12.11, the following predicates are missing:

substitute(+OldElem, +List, +NewElem, -NewList) is det

NewList is List with all values that are identical (==) to OldElem replaced by NewElem.

nth(?Index, ?List, ?Element) is nondet

True if Element is the N-th element in List. Counting starts at 1.

deprecated: - use nth1/3.

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.

deprecated: - use nth1/4.

same_length(?List1, ?List2, ?Length) is nondet

True if List1 and List2 both have length Length.

sublist(?Sub, +List)

True when all members of Sub are members of List in the same order.

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

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.

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

author: - Gertjan van Noord

append(?List1, ?List2, ?List1AndList2)

List1AndList2 is the concatenation of List1 and List2

prefix(?Part, ?Whole)

True iff Part is a leading substring of Whole. This is the same as append(Part, _, Whole).

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.

nextto(?X, ?Y, ?List)

True if Y directly follows X in List.

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

nth0(?Index, ?List, ?Elem)

True when Elem is the Index'th element of List. Counting starts at 0.

Errors: - type_error(integer, Index) if Index is not an integer or unbound.
See also: - nth1/3.

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] ;
false.

?- nth0(1, L, a1, [a,b]).
L = [a, a1, b].

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.

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

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

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.

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

Errors: - type_error(list, Arg) if either argument is not a proper or partial list.

sum_list(+List, -Sum) is det

Sum is the result of adding all numbers in List.

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.

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.

is_list(Arg1)
memberchk(Arg1, Arg2)