[ All Solutions | Reference Manual | Alphabetic Index ]

# bagof(?Term, +Goal, -List)

Succeeds if List is the (non-empty) list of all instances of Term such that Goal is provable.

Term
  Prolog term, usually a variable, a compound term or list containing variables.
Goal
  Callable term.
List
  List or variable.

## Description

Unifies List with the list (not ordered, duplicates retained) of all instances of Term such that Goal is satisfied. The variables appearing in Term should not appear anywhere else in the clause except within Goal.

The following table illustrates the difference between the all solutions predicates:

        built-in  choice pts  duplicates  sorted pruned *
        bagof/3   yes         yes         no     no
        coverof/3 yes         no          no     yes
        findall/3 no          yes         no     no
        setof/3   yes         no          yes    no
       * prune_instances/2 used on list of solutions.

If Goal is not a callable term, exceptions are raised in call/2.

Note If there are uninstantiated variables in Goal which do not appear in Term, then bagof/3 can be resatisfied. It generates alternative values for List corresponding to different instantiations of the free variables of Goal not in Term. Such variables occurring in Goal will not be treated as free if they are explicitly bound within Goal through an existential quantification written as, for example,

       bagof(X, Y^(X likes Y), S).

Then bagof/3 will not backtrack over Y when getting a bag of solutions of X.

### Modes and Determinism

- bagof(?, +, -) is nondet

### Modules

This predicate is sensitive to its module context (tool predicate, see @/2).

### Fail Conditions

Fails if Goal has no solution

### Exceptions

(4) instantiation fault
  Goal is not instantiated.
(5) type error
  Goal is instantiated, but not to a compound term.
(68) calling an undefined procedure
  Goal is an undefined procedure.

## Examples

    Success:

       % example using existential quantification:
      [eclipse]: bagof(Name,Num^current_stream(Name,Mode,Num),L),
      > writeq((Name,Mode,Num,L)), nl, fail.
      _g72 , read , _g84 , [user, debug_input]  % does not
      _g72 , string , _g84 , [""]               % backtrack over
      _g72 , update , _g84 , [null]             % Num.
      _g72 , write , _g84 , [user, error]

      no (more) solution.
      [eclipse]: bagof(Name,current_stream(Name,Mode,Num),L),
      > writeq((Name,Mode,Num,L)), nl, fail.
      _g72 , read , 0 , [user]           % backtracks over Num.
      _g72 , read , 3 , [debug_input]
      _g72 , string , 5 , [""]
      _g72 , update , 4 , [null]
      _g72 , write , 1 , [user]
      _g72 , write , 2 , [error]

      no (more) solution.
      [eclipse]: bagof(Name,(Mode,Num)^current_stream(Name,Mode,Num),L),
      > writeq((Name,Mode,Num,L)), nl, fail.
      _g72 , _g78 , _g84 , [user, user, error, debug_input, null, ""]

      no (more) solution. % retains duplicates; not sorted.

      [eclipse]: [user].
       h(f(1,2)).
       h(f(1,2)).
       h(f(1,X)).
       h(f(X,Y)).   % instances of this element...
       user compiled 476 bytes in 0.00 seconds
      yes.
      [eclipse]: bagof(X,h(X),L).
      X = _g58
      L = [f(1, 2), f(1,2), f(1, _g116), f(_g100, _g102)]
      yes.  % ...all bagged; includes duplicates.

    Fail:
      bagof(Y,current_stream(X,Y,Z),[strin]).

    Error:
      bagof(X,G,L).         (Error 4).
      bagof(X,"G",L).       (Error 5).
      bagof(X,a,L).         (Error 68).
      bagof(X,a(X),L).      (Error 68).

## See Also

coverof / 3, findall / 3, setof / 3