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

shelf_get_and_dec(+ShelfHandle, +Index, -OldValue)

Decrement an integer slot within a shelf object and return the old value, but fail if is zero
ShelfHandle
A shelf handle or shelf name
Index
An integer
OldValue
A variable or integer

Description

This looks up the entry in the Index'th slot of the shelf object denoted by ShelfHandle, and if such an entry exists, and is of integer type, it is decremented by one. If the old value is already zero (or less), the predicate fails and the shelf remains unchanged. Otherwise the predicate succeeds and returns the old value as OldValue. This predicate is a shorthand for:
	shelf_get_and_dec(ShelfHandle, Index, C0) :-
	    with_mutex(ShelfHandle, (
		shelf_get(ShelfHandle, Index, C0),
		C0 > 0,
		C1 is C0 - 1,
		shelf_set(ShelfHandle, Index, C1)
	    ).
The slots are numbered from 1 to the maximum which was determined during shelf creation (but note that ECLiPSe's struct-syntax can be used to give the slots symbolic names, see struct/1).

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

Modes and Determinism

Fail Conditions

Fails if decrementing the value would result in a negative number

Exceptions

(4) instantiation fault
ShelfHandle is not instantiated
(5) type error
Index is not instantiated
(5) type error
ShelfHandle is not a shelf
(5) type error
Index is not an integer
(6) out of range
Index is less than 1 or greater than the number of slots on the shelf
(6) out of range
The old counter value exceeds an implementation-defined limit (at least 2^31)
(40) stale object handle
ShelfHandle refers to an already destroyed shelf

Examples

    ?- shelf_create(s(5),S), shelf_get_and_dec(S,1,Old).

    S = $&(shelf,"36nzz7")
    Old = 5
    Yes (0.00s cpu)
    

See Also

shelf_create / 2, shelf_create / 3, shelf_dec / 2, shelf_get / 3, shelf_inc_and_get / 3, struct / 1