[ Non-logical Variables, Arrays, Bags, Shelves and Stores | The ECLiPSe Built-In Predicates | Reference Manual | Alphabetic Index ]
shelf_set(+ShelfHandle, +Index, ?Term)
Store a term in a shelf object
- ShelfHandle
- A shelf handle
- Index
- An integer
- Term
- An arbitrary term
Description
This stores an arbitrary term in the Index'th slot of the
shelf object denoted by ShelfHandle. All other slots of the
shelf remain untouched. The setting will persist until it is
replaced with a new setting, or until the shelf is destroyed.
In particular, the setting will survive backtracking across
the call to shelf_set/3.
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).
Calling shelf_set/3 with an Index of 0 can be used to set all
slots at once. In this case, Term must be a compound term whose
functor corresponds to the one that was given during shelf creation.
Every shelf slot is set from the corresponding term argument.
Storing and retrieving terms from a shelf involves copying the
term each time, similar to what happens in setval/getval and
record/recorded. In particular, if the term contains variables,
they lose their identity and are replaced with fresh ones.
Also, the different slots of a shelf are separate entities,
in particular, they cannot share variables between each other.
Fail Conditions
None
Resatisfiable
No
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 negative or greater than the number of slots on the shelf
- (40) stale object handle
- ShelfHandle refers to an already destroyed shelf
Examples
For examples see shelf_create/2,3.
See Also
shelf_create / 2, shelf_create / 3, shelf_get / 3, shelf_abolish / 1, struct / 1