List processing
Author: Daniel Diaz
Keywords: GNU Prolog, manual, Prolog, compiler, constraints, finite domains

### 8.20 List processing

- append/3
- member/2, memberchk/2
- reverse/2
- delete/3, select/3
- subtract/3
- permutation/2
- prefix/2, suffix/2
- sublist/2
- last/2
- flatten/2
- length/2
- nth/3
- max_list/2, min_list/2, sum_list/2
- maplist/2-8
- sort/2, msort/2, keysort/2 sort/1, msort/1, keysort/1

These predicates manipulate lists. They are bootstrapped predicates (i.e. written in Prolog) and no error cases are tested (for the moment). However, since they are written in Prolog using other built-in predicates, some errors can occur due to those built-in predicates.

#### 8.20.1 append/3

Templates

  append(?list, ?list, ?list)

Description

append(List1, List2, List12) succeeds if the concatenation of the list List1 and the list List2 is the list List12. This predicate is re-executable on backtracking (e.g. if List12 is instantiated and both List1 and List2 are variable).

Errors

None.

Portability

GNU Prolog predicate.

#### 8.20.2 member/2, memberchk/2

Templates

  member(?term, ?list)
  memberchk(?term, ?list)

Description

member(Element, List) succeeds if Element belongs to the List. This predicate is re-executable on backtracking and can be thus used to enumerate the elements of List.

memberchk/2 is similar to member/2 but only succeeds once.

Errors

None.

Portability

GNU Prolog predicate.

#### 8.20.3 reverse/2

Templates

  reverse(?list, ?list)

Description

reverse(List1, List2) succeeds if List2 unifies with the list List1 in reverse order.

Errors

None.

Portability

GNU Prolog predicate.

#### 8.20.4 delete/3, select/3

Templates

  delete(?list, ?term, ?list)
  select(?term, ?list, ?list)

Description

delete(List1, Element, List2) removes all occurrences of Element in List1 to provide List2. A strict term equality is required, cf. (==)/2 (section 8.3.2).

select(Element, List1, List2) removes one occurrence of Element in List1 to provide List2. This predicate is re-executable on backtracking.

Errors

None.

Portability

GNU Prolog predicate.

#### 8.20.5 subtract/3

Templates

  subtract(+list, +list, ?list)

Description

subtract(List1, List2, List3) removes all elements in List2 from List1 to provide List3. Membership is tested using memberchk/2 (section 8.20.2). The predicate runs in O(|List2| × |List1|).

Errors

None.

Portability

GNU Prolog predicate.

#### 8.20.6 permutation/2

Templates

  permutation(?list, ?list)

Description

permutation(List1, List2) succeeds if List2 is a permutation of the elements of List1. This predicate is re-executable on backtracking.

Errors

None.

Portability

GNU Prolog predicate.

#### 8.20.7 prefix/2, suffix/2

Templates

  prefix(?list, ?list)
  suffix(?list, ?list)

Description

prefix(Prefix, List) succeeds if Prefix is a prefix of List. This predicate is re-executable on backtracking.

suffix(Suffix, List) succeeds if Suffix is a suffix of List. This predicate is re-executable on backtracking.

Errors

None.

Portability

GNU Prolog predicate.

#### 8.20.8 sublist/2

Templates

  sublist(?list, ?list)

Description

sublist(List1, List2) succeeds if all elements of List1 appear in List2 in the same order. This predicate is re-executable on backtracking.

Errors

None.

Portability

GNU Prolog predicate.

#### 8.20.9 last/2

Templates

  last(?list, ?term)

Description

last(List, Element) succeeds if Element is the last element of List.

Errors

None.

Portability

GNU Prolog predicate.

#### 8.20.10 flatten/2

Templates

  flatten(?term, ?list)

Description

flat(List1, List2) succeeds if List2 is the flatten version of List1.

Errors

None.

Portability

GNU Prolog predicate.

#### 8.20.11 length/2

Templates

  length(?list, ?integer)

Description

length(List, Length) succeeds if Length is the length of List.

Errors

Length is an integer < 0 |  | domain_error(not_less_than_zero, Length)

GNU Prolog predicate.

#### 8.20.12 nth/3

Templates

  nth(?integer, ?list, ?term)

Description

nth(N, List, Element) succeeds if the Nth argument of List is Element.

Errors

None.

Portability

GNU Prolog predicate.

#### 8.20.13 max_list/2, min_list/2, sum_list/2

Templates

  min_list(+list, ?number)
  max_list(+list, ?number)
  sum_list(+list, ?number)

Description

min_list(List, Min) succeeds if Min is the smallest number in List.

max_list(List, Max) succeeds if Max is the largest number in List.

sum_list(List, Sum) succeeds if Sum is the sum of all the elements in List.

List must be a list of arithmetic evaluable terms (section 8.6.1).

Errors

None.

Portability

GNU Prolog predicate.

#### 8.20.14 maplist/2-8

Templates

  maplist(+callable_term, +list, …, +list)

Description

maplist(Goal, List) succeeds if Goal can succesfully be applied on all elements of List.

maplist(Goal, List1, List2) succeeds if Goal can succesfully be applied to all pairs of elements of List1 and List2.

maplist(Goal, List1, List2, List3) succeeds if Goal can succesfully be applied to all triples of elements of List1..List3.

maplist(Goal, List1, List2, …, ListN) succeeds if Goal can succesfully be applied to all N-uples (N ≤ 8) of elements of List1..ListN.

Errors

an error occurs executing a directive |  | see call/1 errors (section 7.2.3)

Portability

GNU Prolog predicate.

#### 8.20.15 sort/2, msort/2, keysort/2 sort/1, msort/1, keysort/1

Templates

  sort(+list, ?list)
  msort(+list, ?list)
  keysort(+list, ?list)
  sort(+list)
  msort(+list)
  keysort(+list)

Description

sort(List1, List2) succeeds if List2 is the sorted list corresponding to List1 where duplicate elements are merged.

msort/2 is similar to sort/2 except that duplicate elements are not merged.

keysort(List1, List2) succeeds if List2 is the sorted list of List1 according to the keys. The list List1 consists of pairs (items of the form Key-Value). These items are sorted according to the value of Key yielding the List2. Duplicate keys are not merged. This predicate is stable, i.e. if K-A occurs before K-B in the input, then K-A will occur before K-B in the output.

sort/1, msort/1 and keysort/1 are similar to sort/2, msort/2 and keysort/2 but achieve a sort in-place destructing the original List1 (this in-place assignment is not undone at backtracking). The sorted list occupies the same memory space as the original list (saving thus memory consumption).

The time complexity of these sorts is O(N log N), N being the length of the list to sort.

These predicates refer to the standard ordering of terms (section 8.3.1).

Errors

List1 is a partial list |  | instantiation_error
List1 is neither a partial list nor a list |  | type_error(list, List1)
List2 is neither a partial list nor a list |  | type_error(list, List2)
for keysort/2: an element of List1 is a variable |  | instantiation_error
for keysort/2: an element E of List1 is neither a variable nor a pair |  | type_error(pair, E)
for keysort/2: an element E of List2 is neither a variable nor a pair |  | type_error(pair, E)

Portability

sort/2 and keysort/2 are ISO predicates.

sort/1, keysort/1 and msort/1-2 are GNU Prolog predicates.

Copyright (C) 1999-2021 Daniel Diaz Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved. More about the copyright