[ Non-logical Variables, Arrays, Bags, Shelves and Stores | Reference Manual | Alphabetic Index ]

bag_dissolve(+BagHandle, -List)

Retrieve a bag's contents and destroy the bag
BagHandle
A bag
List
A variable or list of terms

Description

This returns a list containing a copy of every term that has been entered into the bag since it was created. The bag is also destoyed. It should not be assumed that the list order reflects the order in which the terms were entered into the bag. Entering and retrieving terms from a bag involves copying the term each time, similar to what happens in setval/getval and record/recorded. In particular, if the term contains variables, they lose their identity and are replaced with fresh ones.

bag_dissolve/2 is equivalent to bag_retrieve/2, followed by bag_abolish/1. Using the BagHandle after it has been dissolved will lead to an error message.

Modes and Determinism

Exceptions

(4) instantiation fault
BagHandle is not instantiated
(5) type error
BagHandle is not a bag
(5) type error
List is instantiated but not to a list
(40) stale object handle
BagHandle refers to an already destroyed bag

Examples

    simple_findall(Goal, Solutions) :-
    	bag_create(Bag),
	(
	    call(Goal),
	    bag_enter(Bag, Goal),
	    fail
	;
	    true
	),
	bag_dissolve(Bag, Solutions).
    

See Also

bag_create / 1, bag_enter / 2, bag_count / 2, bag_erase / 1, bag_retrieve / 2, bag_abolish / 1