☰

*ON THIS PAGE*# List processing

**Author(s):** The Ciao Development Team.## Usage and interface

## Documentation on exports

**Other properties:** `append(Xs,Ys,Zs)`
`append(Xs,Ys,Zs)`
`append(Xs,Ys,Zs)`
`append(Xs,Ys,Zs)`
`append(Xs,Ys,Zs)`
`append(Xs,Ys,Zs)`
`append(Xs,Ys,Zs)`
`append(Xs,Ys,Zs)`
`append(Xs,Ys,Zs)`
**Other properties:** `reverse(Xs,_Ys)`
**Other properties:** `reverse(Xs,Ys,Zs)`
**Other properties:** `delete(L1,E,L2)`
**Other properties:** `delete_non_ground(L1,E,L2)`
**Other properties:** `select(X,Xs,Ys)`
**Other properties:** `length(A,B)`
`length(L,N)`
`length(L,N)`
`nth(N,List,Elem)`
**Other properties:** `nth(N,L,E)`
`nth(N,L,E)`
`nth(N,L,E)`
*Meta-predicate* with arguments: `list1(?,pred(1))`.

## Documentation on imports

This module has the following direct dependencies:

This module provides a set of predicates for list processing.

**Library usage:**`:- use_module(library(lists)).`**Exports:***Predicates:*`nonsingle/1`,`append/3`,`reverse/2`,`reverse/3`,`delete/3`,`delete_non_ground/3`,`select/3`,`length/2`,`nth/3`,`add_after/4`,`add_before/4`,`dlist/3`,`list_concat/2`,`list_insert/2`,`insert_last/3`,`contains_ro/2`,`contains1/2`,`nocontainsx/2`,`last/2`,`list_lookup/3`,`list_lookup/4`,`intset_insert/3`,`intset_delete/3`,`intset_in/2`,`intset_sequence/3`,`intersection/3`,`union/3`,`difference/3`,`equal_lists/2`,`list_to_list_of_lists/2`,`powerset/2`,`cross_product/2`,`sequence_to_list/2`.*Properties:*`list1/2`,`sublist/2`,`subordlist/2`.*Regular Types:*`list_of_lists/1`.

PREDICATEnonsingle/1

Usage:`nonsingle(X)`

X is not a singleton.

PREDICATEappend/3

Usage:`append(Xs,Ys,Zs)`

*Call and exit should be compatible with:*

(`basic_props:list/1`)Xs is a list.

(`basic_props:list/1`)Ys is a list.

(`basic_props:list/1`)Zs is a list.

Zs is Ys appended to Xs.

*The following properties should hold upon exit:*

(`basic_props:list/1`)Xs is a list.

*If the following properties hold at call time:*

(`basic_props:list/1`)Xs is a list.

(`basic_props:list/1`)Ys is a list.*then the following properties should hold upon exit:*

(`basic_props:list/1`)Zs is a list.

*If the following properties hold at call time:*

(`basic_props:list/1`)Zs is a list.*then the following properties should hold upon exit:*

(`basic_props:list/1`)Xs is a list.

(`basic_props:list/1`)Ys is a list.

*The following properties should hold upon exit:*

(`native_props:mshare/1`)The sharing pattern for the variables in the clause is`[[X,Y,Z],[X,Z],[Y,Z]]`.

*If the following properties hold at call time:*

(`term_typing:ground/1`)Xs is currently ground (it contains no variables).

(`term_typing:ground/1`)Ys is currently ground (it contains no variables).*then the following properties should hold upon exit:*

(`term_typing:ground/1`)Zs is currently ground (it contains no variables).

*If the following properties hold at call time:*

(`term_typing:ground/1`)Zs is currently ground (it contains no variables).*then the following properties should hold upon exit:*

(`term_typing:ground/1`)Xs is currently ground (it contains no variables).

(`term_typing:ground/1`)Ys is currently ground (it contains no variables).

*The following properties hold globally:*

(`basic_props:sideff/2`)append(Xs,Ys,Zs) is side-effect free.

*If the following properties hold at call time:*

(`basic_props:list/1`)Xs is a list.*then the following properties hold globally:*

(`basic_props:eval/1`)append(Xs,Ys,Zs) is evaluable at compile-time.

*If the following properties hold at call time:*

(`basic_props:list/1`)Zs is a list.*then the following properties hold globally:*

(`basic_props:eval/1`)append(Xs,Ys,Zs) is evaluable at compile-time.

PREDICATEreverse/2

Usage:`reverse(Xs,Ys)`

Reverses the order of elements in Xs.

*The following properties should hold at call time:*

(`basic_props:list/1`)Xs is a list.

(`basic_props:term/1`)Ys is any term.*The following properties should hold upon exit:*

(`basic_props:list/1`)Xs is a list.

(`basic_props:list/1`)Ys is a list.

*The following properties hold globally:*

(`basic_props:sideff/2`)reverse(Arg1,Arg2) is side-effect free.

*If the following properties hold at call time:*

(`basic_props:list/1`)Xs is a list.*then the following properties hold globally:*

(`basic_props:eval/1`)reverse(Xs,_Ys) is evaluable at compile-time.

PREDICATEreverse/3

Usage:`reverse(A,B,C)`

Reverse the order of elements in A, and append it with B.

*The following properties hold globally:*

(`basic_props:sideff/2`)reverse(Arg1,Arg2,Arg3) is side-effect free.

*If the following properties hold at call time:*

(`basic_props:list/1`)Xs is a list.

(`basic_props:list/1`)Ys is a list.*then the following properties hold globally:*

(`basic_props:eval/1`)reverse(Xs,Ys,Zs) is evaluable at compile-time.

PREDICATEdelete/3

Usage:`delete(L1,E,L2)`

L2 is L1 without the ocurrences of E.

*The following properties should hold upon exit:*

(`basic_props:list/1`)L1 is a list.

(`basic_props:list/1`)L2 is a list.

*The following properties hold globally:*

(`basic_props:sideff/2`)delete(Arg1,Arg2,Arg3) is side-effect free.

*If the following properties hold at call time:*

(`term_typing:ground/1`)L1 is currently ground (it contains no variables).

(`term_typing:ground/1`)L2 is currently ground (it contains no variables).*then the following properties hold globally:*

(`basic_props:eval/1`)delete(L1,E,L2) is evaluable at compile-time.

PREDICATEdelete_non_ground/3

Usage:`delete_non_ground(L1,E,L2)`

L2 is L1 without the ocurrences of E. E can be a nonground term so that all the elements in L1 it unifies with will be deleted

*The following properties should hold upon exit:*

(`basic_props:list/1`)L1 is a list.

(`basic_props:list/1`)L2 is a list.

*The following properties hold globally:*

(`basic_props:sideff/2`)delete_non_ground(Arg1,Arg2,Arg3) is side-effect true.

*If the following properties hold at call time:*

(`term_typing:ground/1`)L1 is currently ground (it contains no variables).

(`term_typing:ground/1`)L2 is currently ground (it contains no variables).*then the following properties hold globally:*

(`basic_props:eval/1`)delete_non_ground(L1,E,L2) is evaluable at compile-time.

PREDICATEselect/3

Usage:`select(X,Xs,Ys)`

Xs and Ys have the same elements except for one occurrence of X.

*The following properties hold globally:*

(`basic_props:sideff/2`)select(Arg1,Arg2,Arg3) is side-effect free.

*If the following properties hold at call time:*

(`term_typing:ground/1`)X is currently ground (it contains no variables).

(`term_typing:ground/1`)Xs is currently ground (it contains no variables).*then the following properties hold globally:*

(`basic_props:eval/1`)select(X,Xs,Ys) is evaluable at compile-time.

PREDICATElength/2

Usage 1:`length(L,N)`

Computes the length of L.

*The following properties should hold at call time:*

(`basic_props:list/1`)L is a list.

(`term_typing:var/1`)N is a free variable.*The following properties should hold upon exit:*

(`basic_props:list/1`)L is a list.

(`basic_props:int/1`)N is an integer.

Usage 2:`length(L,N)`

Outputs L of length N.

*The following properties should hold at call time:*

(`term_typing:var/1`)L is a free variable.

(`basic_props:int/1`)N is an integer.*The following properties should hold upon exit:*

(`basic_props:list/1`)L is a list.

(`basic_props:int/1`)N is an integer.

Usage 3:`length(L,N)`

Checks that L is of length N.

*The following properties should hold at call time:*

(`basic_props:list/1`)L is a list.

(`basic_props:int/1`)N is an integer.*The following properties should hold upon exit:*

(`basic_props:list/1`)L is a list.

(`basic_props:int/1`)N is an integer.

*The following properties hold globally:*

(`basic_props:native/1`)This predicate is understood natively by CiaoPP.

*The following properties hold globally:*

(`basic_props:sideff/2`)length(Arg1,Arg2) is side-effect free.

*If the following properties hold at call time:*

(`basic_props:list/1`)L is a list.*then the following properties hold globally:*

(`basic_props:eval/1`)length(L,N) is evaluable at compile-time.

*If the following properties hold at call time:*

(`term_typing:integer/1`)N is currently instantiated to an integer.*then the following properties hold globally:*

(`basic_props:eval/1`)length(L,N) is evaluable at compile-time.

PREDICATEnth/3

N is the position in List of Elem. N counts from one.

Usage 1:

Unifies Elem and the Nth element of List.

*Call and exit should be compatible with:*

(`basic_props:list/1`)List is a list.

(`basic_props:term/1`)Elem is any term.*The following properties should hold at call time:*

(`basic_props:int/1`)N is an integer.*The following properties should hold upon exit:*

(`basic_props:list/1`)List is a list.

(`basic_props:term/1`)Elem is any term.

Usage 2:

Finds the positions where Elem is in List. Positions are found in ascending order.

*Call and exit should be compatible with:*

(`basic_props:list/1`)List is a list.

(`basic_props:term/1`)Elem is any term.*The following properties should hold at call time:*

(`term_typing:var/1`)N is a free variable.*The following properties should hold upon exit:*

(`basic_props:int/1`)N is an integer.

(`basic_props:list/1`)List is a list.

(`basic_props:term/1`)Elem is any term.

*The following properties hold globally:*

(`basic_props:sideff/2`)nth(N,List,Elem) is side-effect free.

*If the following properties hold at call time:*

(`term_typing:integer/1`)N is currently instantiated to an integer.*then the following properties hold globally:*

(`basic_props:eval/1`)nth(N,L,E) is evaluable at compile-time.

*If the following properties hold at call time:*

(`basic_props:list/1`)L is a list.*then the following properties hold globally:*

(`basic_props:eval/1`)nth(N,L,E) is evaluable at compile-time.

*If the following properties hold at call time:*

(`basic_props:int/1`)N is an integer.

(`basic_props:list/1`)L is a list.*then the following properties hold globally:*

(`native_props:is_det/1`)All calls of the form nth(N,L,E) are deterministic.

PREDICATEadd_after/4

Usage:`add_after(L0,E0,E,L)`

Adds element E after element E0 (or at end) to list L0 returning in L the new list (uses term comparison).

*The following properties should hold at call time:*

(`term_typing:nonvar/1`)L0 is currently a term which is not a free variable.

(`term_typing:nonvar/1`)E0 is currently a term which is not a free variable.

(`term_typing:nonvar/1`)E is currently a term which is not a free variable.

(`term_typing:var/1`)L is a free variable.

PREDICATEadd_before/4

Usage:`add_before(L0,E0,E,L)`

Adds element E before element E0 (or at start) to list L0 returning in L the new list (uses term comparison).

*The following properties should hold at call time:*

(`term_typing:nonvar/1`)L0 is currently a term which is not a free variable.

(`term_typing:nonvar/1`)E0 is currently a term which is not a free variable.

(`term_typing:nonvar/1`)E is currently a term which is not a free variable.

(`term_typing:var/1`)L is a free variable.

PROPERTYlist1/2

Usage:`list1(X,Y)`

X is a list of Ys of at least one element.

PREDICATEdlist/3

Usage:`dlist(List,DList,Tail)`

List is the result of removing Tail from the end of DList (makes a difference list from a list).

PREDICATElist_concat/2

Usage:`list_concat(LL,L)`

L is the concatenation of all the lists in LL.

*The following properties should hold at call time:*

(`basic_props:list/2`)LL is a list of lists.*The following properties should hold upon exit:*

(`basic_props:list/1`)L is a list.

PREDICATElist_insert/2

Usage:`list_insert(List,Term)`

Adds Term to the end of List if there is no element in List identical to Term.

*The following properties should hold at call time:*

(`term_typing:nonvar/1`)Term is currently a term which is not a free variable.

PREDICATEinsert_last/3

Usage:`insert_last(L0,E,L)`

Adds element E at end of list L0 returning L.

*The following properties should hold at call time:*

(`term_typing:nonvar/1`)L0 is currently a term which is not a free variable.

(`term_typing:nonvar/1`)E is currently a term which is not a free variable.

PREDICATEcontains_ro/2

Usage:

Impure membership (does not instantiate a variable in its first argument.

PREDICATEcontains1/2

Usage:

First membership.

PREDICATEnocontainsx/2

Usage:`nocontainsx(L,X)`

X is not identical to any element of L.

PREDICATElast/2

Usage:`last(L,X)`

X is the last element of list L.

PREDICATElist_lookup/3

PREDICATElist_lookup/4

Usage:`list_lookup(List,Functor,Key,Value)`

Look up Functor(Key,Value) pair in variable ended key-value pair list L or else add it at the end.

PREDICATEintset_insert/3

Usage:`intset_insert(A,B,Set)`

Insert the element B in the ordered set of numbers A.

PREDICATEintset_delete/3

Usage:`intset_delete(A,B,Set)`

Delete from the ordered set A the element B.

PREDICATEintset_in/2

Usage:`intset_in(E,Set)`

Succeds iff E is element of Set

PREDICATEintset_sequence/3

Usage:`intset_sequence(N,L1,L2)`

Generates an ordered set of numbers from 0 to N-1, and append it to L1.

PREDICATEintersection/3

Usage:`intersection(List1,List2,List)`

List has the elements which are both in List1 and List2.

*The following properties should hold at call time:*

(`term_typing:nonvar/1`)List1 is currently a term which is not a free variable.

(`term_typing:nonvar/1`)List2 is currently a term which is not a free variable.

(`basic_props:list/1`)List1 is a list.

(`basic_props:list/1`)List2 is a list.*The following properties should hold upon exit:*

(`basic_props:list/1`)List is a list.

PREDICATEunion/3

Usage:`union(List1,List2,List)`

List has the elements which are in List1 followed by the elements which are in List2 but not in List1.

*The following properties should hold at call time:*

(`term_typing:nonvar/1`)List1 is currently a term which is not a free variable.

(`term_typing:nonvar/1`)List2 is currently a term which is not a free variable.

(`term_typing:var/1`)List is a free variable.

(`basic_props:list/1`)List1 is a list.

(`basic_props:list/1`)List2 is a list.*The following properties should hold upon exit:*

(`basic_props:list/1`)List is a list.

PREDICATEdifference/3

Usage:`difference(List1,List2,List)`

List has the elements which are in List1 but not in List2.

*The following properties should hold at call time:*

(`term_typing:nonvar/1`)List1 is currently a term which is not a free variable.

(`term_typing:nonvar/1`)List2 is currently a term which is not a free variable.

(`term_typing:var/1`)List is a free variable.

(`basic_props:list/1`)List1 is a list.

(`basic_props:list/1`)List2 is a list.*The following properties should hold upon exit:*

(`basic_props:list/1`)List is a list.

PROPERTYsublist/2

Usage:`sublist(List1,List2)`

List2 contains all the elements of List1.

*If the following properties should hold at call time:*

(`term_typing:nonvar/1`)List2 is currently a term which is not a free variable.

PROPERTYsubordlist/2

Usage:`subordlist(List1,List2)`

List2 contains all the elements of List1 in the same order.

*If the following properties should hold at call time:*

(`term_typing:nonvar/1`)List2 is currently a term which is not a free variable.

PREDICATEequal_lists/2

Usage:`equal_lists(List1,List2)`

List1 has all the elements of List2, and vice versa.

*The following properties should hold at call time:*

(`basic_props:list/1`)List1 is a list.

(`basic_props:list/1`)List2 is a list.

PREDICATElist_to_list_of_lists/2

Usage 1:`list_to_list_of_lists(List,LList)`

*The following properties should hold at call time:*

(`basic_props:list/1`)List is a list.*The following properties should hold upon exit:*

(`lists:list_of_lists/1`)`lists:list_of_lists(LList)`

Usage 2:`list_to_list_of_lists(List,LList)`

LList is the list of one element lists with elements of List.

*The following properties should hold at call time:*

(`lists:list_of_lists/1`)`lists:list_of_lists(LList)`*The following properties should hold upon exit:*

(`basic_props:list/1`)List is a list.

PREDICATEpowerset/2

Usage:`powerset(List,LList)`

LList is the powerset of List, i.e., the list of all lists which have elements of List. If List is ordered, LList and all its elements are ordered.

*The following properties should hold at call time:*

(`term_typing:nonvar/1`)List is currently a term which is not a free variable.

(`basic_props:list/1`)List is a list.*The following properties should hold upon exit:*

(`lists:list_of_lists/1`)`lists:list_of_lists(LList)`

PREDICATEcross_product/2

Usage:`cross_product(LList,List)`

List is the cartesian product of the lists in LList, that is, the list of lists formed with one element of each list in LList, in the same order.

*The following properties should hold at call time:*

(`term_typing:nonvar/1`)LList is currently a term which is not a free variable.

(`lists:list_of_lists/1`)`lists:list_of_lists(LList)`*The following properties should hold upon exit:*

(`lists:list_of_lists/1`)`lists:list_of_lists(List)`

PREDICATEsequence_to_list/2

Usage:`sequence_to_list(Sequence,List)`

List is the list of all elements in the (comma-separated) sequence Sequence. The use of this predicate is reversible.

REGTYPElist_of_lists/1

A regular type, defined as follows:

list_of_lists([]). list_of_lists([L|Xs]) :- list(L), list_of_lists(Xs).

(UNDOC_REEXPORT)member/2

Imported from `basic_props` (see the corresponding documentation for details).

(UNDOC_REEXPORT)member/2

Imported from `basic_props` (see the corresponding documentation for details).

*System library modules:*`native_props`.*Packages:*`prelude`,`initial`,`condcomp`,`assertions`,`assertions/assertions_basic`,`isomodes`,`metatypes`,`hiord`,`nativeprops`.

Generated with LPdoc using Ciao