A.3 library(apply): Apply predicates on a list

See also

- apply_macros.pl provides compile-time expansion for part of this library.
- http://www.cs.otago.ac.nz/staffpriv/ok/pllib.htm
- Unit test code in src/Tests/library/test_apply.pl

To be done

Add include/4, include/5, exclude/4, exclude/5

This module defines meta-predicates that apply a predicate on all members of a list.

All predicates support partial application in the Goal argument. This means that these calls are identical:

?- maplist(=, [foo, foo], [X, Y]).
?- maplist(=(foo), [X, Y]).

[det]include(:Goal, +List1, ?List2)

Filter elements for which Goal succeeds. True if List2 contains those elements Xi of List1 for which call(Goal, Xi) succeeds.

See also

exclude/3, partition/4, convlist/3.

Compatibility

Older versions of SWI-Prolog had sublist/3 with the same arguments and semantics.

[det]exclude(:Goal, +List1, ?List2)

Filter elements for which Goal fails. True if List2 contains those elements Xi of List1 for which call(Goal, Xi) fails.

See also

include/3, partition/4

[det]partition(:Pred, +List, ?Included, ?Excluded)

Filter elements of List according to Pred. True if Included contains all elements for which call(Pred, X) succeeds and Excluded contains the remaining elements.

See also

include/3, exclude/3, partition/5.

[semidet]partition(:Pred, +List, ?Less, ?Equal, ?Greater)

Filter List according to Pred in three sets. For each element Xi of List, its destination is determined by call(Pred, Xi, Place), where Place must be unified to one of <, = or >. Pred must be deterministic.

See also

partition/4

maplist(:Goal, ?List1)

maplist(:Goal, ?List1, ?List2)

maplist(:Goal, ?List1, ?List2, ?List3)

maplist(:Goal, ?List1, ?List2, ?List3, ?List4)

True if Goal is successfully applied on all matching elements of the list. The maplist family of predicates is defined as:

maplist(G, [X_11, ..., X_1n],
           [X_21, ..., X_2n],
           ...,
           [X_m1, ..., X_mn]) :-
   call(G, X_11, ..., X_m1),
   call(G, X_12, ..., X_m2),
   ...
   call(G, X_1n, ..., X_mn).

This family of predicates is deterministic iff Goal is deterministic and List1 is a proper list, i.e., a list that ends in [].

[det]convlist(:Goal, +ListIn, -ListOut)

Similar to maplist/3, but elements for which call(Goal, ElemIn, _) fails are omitted from ListOut. For example (using library(yall)):

?- convlist([X,Y]>>(integer(X), Y is X^2),
            [3, 5, foo, 2], L).
L = [9, 25, 4].

Compatibility

Also appears in YAP library(maplist) and SICStus library(lists).

foldl(:Goal, +List, +V0, -V)

foldl(:Goal, +List1, +List2, +V0, -V)

foldl(:Goal, +List1, +List2, +List3, +V0, -V)

foldl(:Goal, +List1, +List2, +List3, +List4, +V0, -V)

Fold an ensemble of m (0 <= m <= 4) lists of length n head-to-tail ("fold-left"), using columns of m list elements as arguments for Goal. The foldl family of predicates is defined as follows, with V0 an initial value and V the final value of the folding operation:

foldl(G, [X_11, ..., X_1n],
         [X_21, ..., X_2n],
         ...,
         [X_m1, ..., X_mn], V0, V) :-
   call(G, X_11, ..., X_m1, V0, V1),
   call(G, X_12, ..., X_m2, V1, V2),
   ...
   call(G, X_1n, ..., X_mn, V<n-1>, V).

No implementation for a corresponding foldr is given. A foldr implementation would consist in first calling reverse/2 on each of the m input lists, then applying the appropriate foldl. This is actually more efficient than using a properly programmed-out recursive algorithm that cannot be tail-call optimized.

scanl(:Goal, +List, +V0, -Values)

scanl(:Goal, +List1, +List2, +V0, -Values)

scanl(:Goal, +List1, +List2, +List3, +V0, -Values)

scanl(:Goal, +List1, +List2, +List3, +List4, +V0, -Values)

Scan an ensemble of m (0 <= m <= 4) lists of length n head-to-tail ("scan-left"), using columns of m list elements as arguments for Goal. The scanl family of predicates is defined as follows, with V0 an initial value and V the final value of the scanning operation:

scanl(G, [X_11, ..., X_1n],
         [X_21, ..., X_2n],
         ...,
         [X_m1, ..., X_mn], V0, [V0, V1, ..., Vn] ) :-
   call(G, X_11, ..., X_m1, V0, V1),
   call(G, X_12, ..., X_m2, V1, V2),
   ...
   call(G, X_1n, ..., X_mn, V<n-1>, Vn).

scanl behaves like a foldl that collects the sequence of values taken on by the Vx accumulator into a list.