PLOGHELP SETOF              Jonathan Laventhol, Thursday 22nd March 1984
                                Revised by Kathryn Seifert  October 1986

Produces a set of patterns which will satisfy a given goal

    ?- setof(Pattern, Goal, Set).

Keywords: goal, goal satisfaction, set

CONTENTS - (Use <ENTER> g to access sections)

 -- INTRODUCTION
 -- EXAMPLE
 -- THE EXISTENTIAL QUANTIFIER
 -- FAST_SETOF
 -- BAGOF and FAST_BAGOF
 -- RELATED DOCUMENTATION

-- INTRODUCTION -------------------------------------------------------

This builtin predicate is for finding the Set of all solutions to the
Goal for the given Pattern. The Set will be ordered using the standard
ordering for terms (see PLOGHELP * COMPARE). If you don't need this
ordering, you can use 'bagof' (see PLOGHELP * BAGOF).

-- EXAMPLE ------------------------------------------------------------

In a query of the form:

    ?- setof(Mother, parents(Father, Mother, Child), S).

'setof' will treat the meaning of this query as "S is the set of all
Mothers such that Father and Mother are the father and mother of Child
for some SPECIFIC Father and Child".

For example, given the database of facts:

    parents(frances, richard, kathy).
    parents(elsie, mel, jon).
    parents(joanne, kenny, frank).

we can call 'setof' as above with the following results:

    ?- setof(Ma, parents(Ma, Pa, Child), B).
    Ma = _1
    Pa = kenny
    Child = frank
    B = [joanne]
    ? ;

    Ma = _1
    Pa = mel
    Child = jon
    B = [elsie]
    ? ;

    Ma = _1
    Pa = richard
    Child = kathy
    B = [frances]
    ? ;

    no

Note that we can backtrack on the values of the variables occurring in
the goal which are not part of the Pattern.  If there are no solutions,
then the whole goal will fail:

    ?- setof(Parent, parents(Mother, Father, ben), Parents).
    no

-- THE EXISTENTIAL QUANTIFIER -----------------------------------------

The '^' is an operator which acts as an existential quantifier in calls
of 'setof' and 'bagof' (see PLOGHELP * BAGOF). By putting and
existential quantifier '^' in the question, we can ask "Who are
mothers?":

    ?- setof(Mother,Father^Child^parents(Mother,Father,Child), Mas).
    Mother = _1
    Father = _2
    Child = _3
    Mas = [elsie, frances, joanne]
    ?
    yes

In the above call of 'setof', the query was interpreted as "Mas is the
set of all Mothers such that there exists some Father and some Child for
which the relationship  parents(Mother, Father, Child) holds true." Or
in other words: "Mas is the set of all Mothers such that Mother and
Father are the mother and father of Child for ANY Father and Child."

The symbol ^ is declared as an operator of precedence 10 and fix fxy.
See PLOGHELP * OPERATORS.

-- FAST_SETOF ---------------------------------------------------------

If you want all the variables occurring in the pattern to be
existentially qualified, use 'fast_setof' (see PLOGHELP * FAST_SETOF):

    ?- fast_setof(Father, parents(Mother, Father, Child), Pas).
    Father = _1
    Mother = _2
    Child = _3
    Pas = [kenny, mel, richard]
    ? 
    yes


-- BAGOF and FAST_BAGOF -----------------------------------------------

If you don't need the solution to be an ordered set with no
duplications, you can use 'bagof'.  This is exactly the same as 'setof',
except that the result may contain duplications, and won't be in a
particular order:

    ?- bagof(Mother, Father^Child^parents(Mother, Father, Child), Mas).
    Mother = _1
    Father = _2
    Child = _3
    Mas = [frances, elsie, joanne]
    ? 
    yes

Finally, 'fast_bagof' (see PLOGHELP * FAST_BAGOF) is to 'bagof'  as
'fast_setof' is to 'setof'.

-- RELATED DOCUMENTATION ----------------------------------------------

PLOGHELP * BAGOF
 Produces a bag of patterns which will satisfy a given goal

PLOGHELP * FAST_BAGOF
 Fast version of 'bagof'

PLOGHELP * FAST_SETOF
 Fast version of 'setof'

PLOGHELP * FINDALL
 Library program to find all the terms which satisfy a given predicate

--- C.all/plog/help/setof ----------------------------------------------
--- Copyright University of Sussex 1988. All rights reserved. ----------