[ Non-logical Variables, Arrays, Bags, Shelves and Stores | The ECLiPSe Built-In Predicates | 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

- bag_dissolve(+, -) is det

### 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