List processing

### 8.20 List processing

- `append/3`
- `member/2`, `memberchk/2`
- `reverse/2`
- `delete/3`, `select/3`
- `permutation/2`
- `prefix/2`, `suffix/2`
- `sublist/2`
- `last/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 `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.6 `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.7 `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.8 `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.9 `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.10 `nth/3`

Templates

  `nth(?integer, ?list, ?term)`

Description

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

Errors

None.

Portability

GNU Prolog predicate.

#### 8.20.11 `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.12 `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.13 `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-2012 Daniel Diaz Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved. More about the copyright