
shelf_test_and_set(+ShelfHandle, +Index, +Expected, ?NewValue)

   Replace a given term in a shelf object

Arguments
   ShelfHandle         A shelf handle or shelf name
   Index               An integer
   Expected            An arbitrary term
   NewValue            An arbitrary term

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

Description
	This is an atomic operation for replacing a given old shelf
	value with a new one.  If the shelf slot does not contain the
	expected old value, the predicate fails without changing anything.
	It is a shorthand for:

	shelf_test_and_set(ShelfHandle, Index, Expected, New) :-
	    with_mutex(ShelfHandle, (
		shelf_get(ShelfHandle, Index, Old),
		Old == Expected,
		shelf_set(ShelfHandle, Index, New)
	    ).

	For details on shelf_get/3 and shelf_set/3, see there.

	Note that this can never succeed if Expected is not ground.
    

Modes and Determinism
   shelf_test_and_set(+, +, +, ?) is semidet

Exceptions
     4 --- ShelfHandle is not instantiated
     5 --- Index is not instantiated
     5 --- ShelfHandle is not a shelf
     5 --- Index is not an integer
     6 --- Index is negative or greater than the number of slots on the shelf
    40 --- ShelfHandle refers to an already destroyed shelf

Examples
   
    	?- shelf_create(s(old),S), shelf_test_and_set(S,1,old,new), shelf_get(S,1,New).

	S = $&(shelf,"36nzz7")
	New = new
	Yes (0.00s cpu)

	?- shelf_create(s(old),S), shelf_test_and_set(S,1,foo,new), shelf_get(S,1,New).

	No (0.00s cpu)
    

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