
hash_update(+Table, ++Key, -OldValue, +NewValue, +InitValue)

   Lookup and replace the value stored under Key, or initialise it

Arguments
   Table               A hash table
   Key                 a ground term
   OldValue            Any term
   NewValue            Any term
   InitValue           Any term

Type
   library(hash)

Description

    Lookup the old value stored under Key (defaulting to InitValue if none),
    and store NewValue in its place.  Behaves like

        hash_update(Table, Key, Old, New, Init) :-
                ( hash_get(Table, Key, Old) ->
                    hash_set(Table, Key, New)
                 ;
                    Old = Init,
                    hash_set(Table, Key, New)
                ).

    Note that OldValue can be used to construct NewValue, see examples.

Modes and Determinism
   hash_update(+, ++, -, +, +) is det

Examples
   
	?- hash_create(H),
	   hash_update(H, k, A, hello, first),
	   hash_update(H, k, B, world, first),
	   hash_get(H, k, C).

        A = first
        B = hello
        C = world
	Yes (0.00s cpu)

	% Example: increment a numerical table entry, initialising with 0
    	hash_inc(H, Key) :-
	    hash_update(H, Key, N0, N1, 0),
	    N1 is N0+1.

	% Example: add element to a list entry, starting with []
    	hash_prepend(H, Key, Value) :-
	    hash_update(H, Key, Values, [Value|Values], []).
    

See Also
   hash_get / 3, hash_set / 3, hash_update / 4, hash_map / 3
