Did you know ... Search Documentation:
Pack prolog_library_collection -- prolog/list_ext.pl
PublicShow source

Extends the list support that is provided by the SWI-Prolog standard library.

 common_subsequence(+Subsequences:list(list), -Subsequence:list) is nondet
 empty_list(+L:list) is semidet
empty_list(-L:list) is det
 first(?L, ?Elem) is semidet
 inflist(+Elem, -L:list) is det
Lazy-lists containing an infinitely re-occurring element.

Example of use

?- inflist(0, L), append([A,B,C,D,E,F|_], _, L).
L = [0, 0, 0, 0, 0, 0|_G29924368],
A = B, B = C, C = D, D = E, E = F, F = 0,
freeze(_G29924368, list_ext: (_G29924368=[0|_G29924422], inflist(0, _G29924422)))
See also
- Based on a StackOverflow answer by Michael Hendricks.
 list_truncate(+Whole:list, +MaxLength:or([oneof([∞]),nonneg]), -Part:list) is det
Returns the truncated version of the given list. The maximum length indicates the exact maximum. Truncation will always result in a list which contains at most `MaxLength' elements.
 max_list(+L:list(number), -Max:number, +Zero:number) is det
 member(?X:term, ?Y:term, +L:list(term)) is nondet
 min_list(+L:list(number), -Min:number, +Zero:number) is det
 postfix(?Part:list, ?Whole:list) is nondet
 postfix(?Part:list, ?N:nonneg, ?Whole:list) is nondet
Part is the length-N postfix of Whole.
 prefix(?Part:list, ?Length:nonneg, ?Whole:list) is det
Shorter prefixes are generated first.
 remove_initial_members(+List1:list(term), +Members:list(term), -List2:list(term)) is det
 repeating_list(+L:list) is semidet
repeating_list(-L:list) is multi
 repeating_list(+Elem, +L:list) is semidet
repeating_list(+Elem, -L:list) is multi
repeating_list(-Elem, +L:list) is semidet
repeating_list(-Elem, -L:list) is multi
 repeating_list(+Elem, +N:nonneg, +L:list) is semidet
repeating_list(+Elem, +N:nonneg, -L:list) is det
repeating_list(+Elem, -N:nonneg, +L:list) is semidet
repeating_list(-Elem, +N:nonneg, +L:list) is semidet
repeating_list(+Elem, -N:nonneg, -L:list) is multi
repeating_list(-Elem, +N:nonneg, -L:list) is det
repeating_list(-Elem, -N:nonneg, +L:list) is det
repeating_list(-Elem, -N:nonneg, -L:list) is multi
Succeeds for lists L that repeat term Elem exactly N times.
 singleton_list(+X, +L) is semidet
singleton_list(+X, -L) is det
singleton_list(-X, +L) is det
singleton_list(-X, -L) is det
 substring(?Substring:list, +String:list) is nondet
Returns substrings of the given string. Construction proceeds from smaller to greater substrings.

`[1,3]' is not a substring of `[1,2,3]', but it is a subsequence.

 subsequence(?Subsequence:list, ?Sequence:list) is nondet
Returns substrings of the given string. Construction proceeds from smaller to greater subsequences.

Re-exported predicates

The following predicates are re-exported from other modules

 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(+ListOfLists, ?List)
Concatenate a list of lists. Is true if ListOfLists is a list of lists, and List is the concatenation of these lists.
Arguments:
ListOfLists- must be a list of possibly partial lists
 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.
 selectchk(+Elem, +List, -Rest) is semidet
Semi-deterministic removal of first element in List that unifies with Elem.
 select(?X, ?XList, ?Y, ?YList) is nondet
Select from two lists at the same position. True if XList is unifiable with YList apart a single element at the same position that is unified with X in XList and with Y in YList. A typical use for this predicate is to replace an element, as shown in the example below. All possible substitutions are performed on backtracking.
?- select(b, [a,b,c,b], 2, X).
X = [a, 2, c, b] ;
X = [a, b, c, 2] ;
false.
See also
- selectchk/4 provides a semidet version.
 selectchk(?X, ?XList, ?Y, ?YList) is semidet
Semi-deterministic version of select/4.
 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.
 nth1(?Index, ?List, ?Elem)
Is true when Elem is the Index'th element of List. Counting starts at 1.
See also
- nth0/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].
 nth1(?N, ?List, ?Elem, ?Rest) is det
As nth0/4, but counting starts at 1.
 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.
 proper_length(@List, -Length) is semidet
True when Length is the number of elements in the proper list List. This is equivalent to
proper_length(List, Length) :-
      is_list(List),
      length(List, Length).
 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.
 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.
 flatten(+NestedList, -FlatList) is det
Is true if FlatList is a non-nested version of NestedList. Note that empty lists are removed. In standard Prolog, this implies that the atom '[]' is removed too. In SWI7, [] is distinct from '[]'.

Ending up needing flatten/2 often indicates, like append/3 for appending two lists, a bad design. Efficient code that generates lists from generated small lists must use difference lists, often possible through grammar rules for optimal readability.

See also
- append/2
 clumped(+Items, -Pairs)
Pairs is a list of Item-Count pairs that represents the run length encoding of Items. For example:
?- clumped([a,a,b,a,a,a,a,c,c,c], R).
R = [a-2, b-1, a-4, c-3].
Compatibility
- SICStus
 max_member(-Max, +List) is semidet
True when Max is the largest member in the standard order of terms. Fails if List is empty.
See also
- compare/3
- max_list/2 for the maximum of a list of numbers.
 min_member(-Min, +List) is semidet
True when Min is the smallest member in the standard order of terms. Fails if List is empty.
See also
- compare/3
- min_list/2 for the minimum of a list of numbers.
 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.
 numlist(+Low, +High, -List) is semidet
List is a list [Low, Low+1, ... High]. Fails if High < Low.
Errors
- type_error(integer, Low)
- type_error(integer, High)
 is_set(@Set) is semidet
True if Set is a proper list without duplicates. Equivalence is based on ==/2. The implementation uses sort/2, which implies that the complexity is N*log(N) and the predicate may cause a resource-error. There are no other error conditions.
 list_to_set(+List, ?Set) is det
True when Set has the same elements as List in the same order. The left-most copy of duplicate elements is retained. List may contain variables. Elements E1 and E2 are considered duplicates iff E1 == E2 holds. The complexity of the implementation is N*log(N).
Errors
- List is type-checked.
See also
- sort/2 can be used to create an ordered set. Many set operations on ordered sets are order N rather than order N**2. The list_to_set/2 predicate is more expensive than sort/2 because it involves, two sorts and a linear scan.
Compatibility
- Up to version 6.3.11, list_to_set/2 had complexity N**2 and equality was tested using =/2.
 intersection(+Set1, +Set2, -Set3) is det
True if Set3 unifies with the intersection of Set1 and Set2. The complexity of this predicate is |Set1|*|Set2|. A set is defined to be an unordered list without duplicates. Elements are considered duplicates if they can be unified.
See also
- ord_intersection/3.
 union(+Set1, +Set2, -Set3) is det
True if Set3 unifies with the union of the lists Set1 and Set2. The complexity of this predicate is |Set1|*|Set2|. A set is defined to be an unordered list without duplicates. Elements are considered duplicates if they can be unified.
See also
- ord_union/3
 subset(+SubSet, +Set) is semidet
True if all elements of SubSet belong to Set as well. Membership test is based on memberchk/2. The complexity is |SubSet|*|Set|. A set is defined to be an unordered list without duplicates. Elements are considered duplicates if they can be unified.
See also
- ord_subset/2.
 subtract(+Set, +Delete, -Result) is det
Delete all elements in Delete from Set. Deletion is based on unification using memberchk/2. The complexity is |Delete|*|Set|. A set is defined to be an unordered list without duplicates. Elements are considered duplicates if they can be unified.
See also
- ord_subtract/3.

Undocumented predicates

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

 list_intersperse(Arg1, Arg2, Arg3)
 postfix(Arg1, Arg2, Arg3)
 remove_trailing_members(Arg1, Arg2, Arg3)
 memberchk(Arg1, Arg2)