
shelf_create(++ShelfSpec, ?SlotInit, -ShelfHandle)

   Create a shelf object which can store data across failures

Arguments
   ShelfSpec           A term of the form Name/Arity
   SlotInit            The value used to initialize the slots (any term)
   ShelfHandle         A free variable

Type
   Non-logical Variables, Arrays, Bags, Shelves and Stores

Description
    	This creates a 'shelf' object which can be used to store
	information across failures.  A typical application is counting
	of solutions, keeping track of the best solution, aggregating
	information across multiple solutions etc.

	A shelf is an object with multiple slots whose contents survive
	backtracking. The content of each slot can be set and retrieved
	individually, or the whole shelf can be retrieved as a term.

	Shelves are referred to by handle, not by name, so they make
	it easy to write robust, reentrant code. A shelf disappears when
	the system backtracks over its creation, when the shelf handle
	gets garbage collected, or when it is explicitly destroyed.

	When using shelf_create/3, ShelfSpec determines the number of
	slots on the shelf, and all slots get initialized identically
	with the value SlotInit.
    

Modes and Determinism
   shelf_create(++, ?, -) is det

Exceptions
     4 --- ShelfSpec is not fully instantiated
     5 --- ShelfSpec is fully instantiated but not to a term of the form Atom/Integer
     5 --- ShelfHandle is not a variable

Examples
   
% finding the sum and maximum of data/1 facts:

    data(2).
    data(9).
    data(3).
    data(5).
    data(7).

    sum_and_max(Sum, Max) :-
    	shelf_create(agg/2, 0, Shelf),
	(
	    data(X),
	    shelf_get(Shelf, 1, OldMax),
	    ( X > OldMax -> shelf_set(Shelf, 1, X) ; true ),
	    shelf_get(Shelf, 2, OldSum),
	    NewSum is OldSum + X,
	    shelf_set(Shelf, 2, NewSum),
	    fail
	;
	    shelf_get(Shelf, 0, agg(Max, Sum))
	),
	shelf_abolish(Shelf).
    

See Also
   shelf_create / 2, shelf_set / 3, shelf_get / 3, shelf_abolish / 1
