11.3.209 setof/3   ISO

Synopsis

setof(+Template, +Generator, -Set)

Returns the non-empty set Set of all instances of Template such that Generator is provable.

Arguments

Template

term

:Generator

callable, must be nonvar

A goal to be proved as if by call/1.

Set

list of term

Description

Set is a non-empty set of terms represented as a list of those terms, without duplicates, in the standard order for terms (see ref-lte-cte). If there are no instances of Template such that Generator is satisfied, then setof/3 simply fails.

Obviously, the set to be enumerated should be finite, and should be enumerable by Prolog in finite time. It is possible for the provable instances to contain variables, but in this case Set will only provide an imperfect representation of what is in reality an infinite set.

If Generator is instantiated, but contains uninstantiated variables that do not also appear in Template, then setof/3 can succeed nondeterminately, generating alternative values for Set corresponding to different instantiations of the free variables of Generator. (It is to allow for such usage that Set is constrained to be non-empty.)

If Generator is of the form A^B, then all the variables in A are treated as being existentially quantified.

Please note: If the instances being gathered contain attributed variables (see lib-atts) or suspended goals (see ref-sem-sec), then those variables are replaced by brand new variables, without attributes, in the Set. To retain the attributes, you can use copy_term/3 (see ref-lte-cpt).

Backtracking

setof/3 can succeed nondeterminately, generating alternative values for Set corresponding to different instantiations of the free variables of Generator.

Exceptions

Call errors (see ref-sem-exc).

Examples

See findall/3 for examples that illustrate the differences among findall/3, setof/3, and bagof/3.

See Also

findall/3, bagof/3, ^/2, ref-all.