% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\section{library(apply): Apply predicates on a list}

\label{sec:apply}

\begin{tags}
\mtag{See also}- \file{apply_macros.pl} provides compile-time expansion for part of this
library. \\- \url{http://www.cs.otago.ac.nz/staffpriv/ok/pllib.htm}
    \tag{To be done}
Add \predref{include}{4}, \predref{include}{5}, \predref{exclude}{4}, \predref{exclude}{5}
\end{tags}

This module defines meta-predicates that apply a predicate on all
members of a list.\vspace{0.7cm}

\begin{description}
    \predicate[det]{include}{3}{:Goal, +List1, ?List2}
Filter elements for which \arg{Goal} succeeds. True if \arg{List2} contains
those elements Xi of \arg{List1} for which \verb$call(Goal, Xi)$ succeeds.

\begin{tags}
    \tag{See also}
Older versions of SWI-Prolog had \predref{sublist}{3} with the same
arguments and semantics.
\end{tags}

    \predicate[det]{exclude}{3}{:Goal, +List1, ?List2}
Filter elements for which \arg{Goal} fails. True if \arg{List2} contains
those elements Xi of \arg{List1} for which \verb$call(Goal, Xi)$ fails.

    \predicate[det]{partition}{4}{:Pred, +List, ?Included, ?Excluded}
Filter elements of \arg{List} according to \arg{Pred}. True if \arg{Included}
contains all elements for which \verb$call(Pred, X)$ succeeds and
\arg{Excluded} contains the remaining elements.

    \predicate[semidet]{partition}{5}{:Pred, +List, ?Less, ?Equal, ?Greater}
Filter \arg{List} according to \arg{Pred} in three sets. For each element Xi
of \arg{List}, its destination is determined by \verb$call(Pred, Xi, Place)$,
where Place must be unified to one of \verb$<$, \verb$=$ or \verb$>$.
\arg{Pred} must be deterministic.

    \predicate{maplist}{2}{:Goal, ?List}
True if \arg{Goal} can successfully be applied on all elements of
\arg{List}. Arguments are reordered to gain performance as well as to
make the predicate deterministic under normal circumstances.

    \predicate{maplist}{3}{:Goal, ?List1, ?List2}
As \predref{maplist}{2}, operating on pairs of elements from two lists.

    \predicate{maplist}{4}{:Goal, ?List1, ?List2, ?List3}
As \predref{maplist}{2}, operating on triples of elements from three lists.

    \predicate{maplist}{5}{:Goal, ?List1, ?List2, ?List3, ?List4}
As \predref{maplist}{2}, operating on quadruples of elements from four
lists.

    \predicate[det]{convlist}{3}{:Goal, +ListIn, -ListOut}
Similar to \predref{maplist}{3}, but elements for which \verb$call(Goal, ElemIn, _)$
fails are omitted from \arg{ListOut}. For example (using \verb$library(yall)$):

\begin{code}
?- convlist([X,Y]>>(integer(X), Y is X^2),
            [3, 5, 4.4, 2], L).
L = [9, 25, 4].
\end{code}

\begin{tags}
    \tag{Compatibility}
Also appears in YAP \verb$library(maplist)$ and SICStus
\verb$library(lists)$.
\end{tags}

    \predicate{foldl}{4}{:Goal, +List, +V0, -V}
\nodescription
    \predicate{foldl}{5}{:Goal, +List1, +List2, +V0, -V}
\nodescription
    \predicate{foldl}{6}{:Goal, +List1, +List2, +List3, +V0, -V}
\nodescription
    \predicate{foldl}{7}{:Goal, +List1, +List2, +List3, +List4, +V0, -V}
Fold a list, using arguments of the list as left argument. The
foldl family of predicates is defined by:

\begin{code}
foldl(P, [X11,...,X1n], ..., [Xm1,...,Xmn], V0, Vn) :-
      P(X11, ..., Xm1, V0, V1),
      ...
      P(X1n, ..., Xmn, V', Vn).
\end{code}

    \predicate{scanl}{4}{:Goal, +List, +V0, -Values}
\nodescription
    \predicate{scanl}{5}{:Goal, +List1, +List2, +V0, -Values}
\nodescription
    \predicate{scanl}{6}{:Goal, +List1, +List2, +List3, +V0, -Values}
\nodescription
    \predicate{scanl}{7}{:Goal, +List1, +List2, +List3, +List4, +V0, -Values}
Left scan of list. The scanl family of higher order list
operations is defined by:

\begin{code}
scanl(P, [X11,...,X1n], ..., [Xm1,...,Xmn], V0,
      [V0,V1,...,Vn]) :-
      P(X11, ..., Xm1, V0, V1),
      ...
      P(X1n, ..., Xmn, V', Vn).
\end{code}

\end{description}

