
store_get(+StoreHandle, ++Key, -Value)

   Look up an entry in a store object

Arguments
   StoreHandle         A store handle or store name
   Key                 A ground term
   Value               A variable or arbitrary term

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

Description
	This looks up an entry under a given key in a given store object.
	If an entry for this key exists, the corresponding value is returned,
	otherwise the predicate fails.

	The key can be arbitrarily complex, but must be a ground term.
	The value can be an arbitrary term, and may contain uninstantiated
	variables. Note that values are copied when being stored or
	retrieved, therefore a retrieved nonground value will contain
	fresh variables rather than the original ones (this is similar
	to the behaviour of bags, shelves and global variables).

	The complexity of the retrieval operation is linear in both the size
	of the key and the value, since the value is being copied and the key
	needs to be compared. For indexing purposes, a hash value is computed
	from the key, and the full depth of the key is taken into account.

	Note: If StoreHandle is not a handle, then it must be an atom or a
	compound term, and the store is identified by this term's toplevel
	functor together with the context module.

    

Modes and Determinism
   store_get(+, ++, -) is semidet

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

Fail Conditions
   The store does not contain an entry for Key

Exceptions
     4 --- StoreHandle is uninstantiated
     4 --- Key is not ground
     5 --- StoreHandle is neither atom nor compound term nor store handle
    45 --- StoreHandle is not the name of a store

Examples
   

    ?- store_create(Handle),
       store_set(Handle, tom, 12345),
       store_set(Handle, name(dick,tracy), phone(42376,home)),
       store_set(Handle, numbers:prime, [2,3,5,7|_More]),
       store_get(Handle, tom, Value1),
       store_get(Handle, name(dick,tracy), Value2),
       store_get(Handle, numbers:prime, Value3).

    Handle = 'STORE'(16'001b3c50)
    Value1 = 12345
    Value2 = phone(42376, home)
    Value3 = [2, 3, 5, 7|_More]
    Yes (0.00s cpu)


    ?- store_create(Handle),
       store_set(Handle, tom, 12345),
       store_get(Handle, harry, Value).

    No (0.00s cpu)
    

See Also
   store / 1, local / 1, store_erase / 1, store_set / 3, store_delete / 2, store_contains / 2, stored_keys / 2, stored_keys_and_values / 2, store_create / 1, store_count / 2, store_inc / 2
