
store_create(-StoreHandle)

   Create an anonymous store object which can store indexed data across failures

Arguments
   StoreHandle         A free variable

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

Description
    	This creates a 'store' object which provides indexed access to
	key-value pairs, and whose contents are unaffected by backtracking.

	A store is a persistent (w.r.t. backtracking) hash table. It can
	store arbitrary ECLiPSe terms under arbitrary ground keys.

	Stores can be referred to either by handle or by name. Whenever
	possible, handles should be used, because this naturally leads to
	robust, reentrant code, and avoids the danger of memory leaks.
	A store disappears when the system backtracks over its creation,
	when the store handle gets garbage collected, or when it is
	explicitly destroyed.

	When named stores are used, the visibility of the store name is
	local to the module where it was created. A named store never
	disappears, therefore, in order to free the associated memory,
	its contents should be erased when no longer needed.
    

Modes and Determinism
   store_create(-) is det

Exceptions
     5 --- StoreHandle is not a variable

Examples
   

% Creating and using an 'anonymous store'

    main2 :-
	store_create(Handle),
	store_set(Handle, name(peter,panther), data(1234,mobile)),
	store_set(Handle, name(tom,tiger), data(4567,home)),
	stored_keys_and_values(Handle, Contents),
	writeln(Contents).


% Creating and using a 'named store'

    :- local store(phone_numbers).

    main1 :-
	store_set(phone_numbers, name(peter,panther), data(1234,mobile)),
	store_set(phone_numbers, name(tom,tiger), data(4567,home)),
	stored_keys_and_values(phone_numbers, Contents),
	writeln(Contents).
    

See Also
   store / 1, store_contains / 2, store_count / 2, store_delete / 2, store_erase / 1, store_get / 3, store_inc / 2, store_insert / 3, store_remove / 3, store_set / 3, store_test_and_set / 4, store_update / 4, stored_keys / 2, stored_keys_and_values / 2, library(hash)
