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

store_set(+StoreHandle, ++Key, ?Value)

Make an entry into a store object
StoreHandle
A store handle or store name
Key
A ground term
Value
An arbitrary term

Description

This stores an arbitrary ECLiPSe term under a given key into the given store object. If an entry for this key already exists, it will be replaced by the new entry.

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 store operation is linear in both the size of the key and the value, since both are being copied. 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

Modules

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

Exceptions

(4) instantiation fault
StoreHandle is uninstantiated
(4) instantiation fault
Key is not ground
(5) type error
StoreHandle is neither atom nor compound term nor store handle
(45) named object does not exist
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]),
       stored_keys_and_values(Handle, Data).

    Handle = $&(store,"17h3")
    Data = [(numbers : prime) - [2, 3, 5, 7|_123],
            tom - 12345,
	    name(dick, tracy) - phone(42376, home)]
    Yes (0.00s cpu)


    ?- store_create(Handle),
       store_set(Handle, tom, first),
       store_set(Handle, tom, second),	% overwrite old entry
       store_get(Handle, tom, X).

    Handle = $&(store,"17h3")
    X = second
    Yes (0.00s cpu)
    

See Also

store / 1, store_create / 1, store_inc / 2, store_insert / 3, store_test_and_set / 4, store_update / 4