[ Non-logical Variables, Arrays, Bags, Shelves and Stores | The ECLiPSe Built-In Predicates | Reference Manual | Alphabetic Index ]

shelf_get(+ShelfHandle, +Index, -Term)

Retrieve a stored term from a shelf object

ShelfHandle: A shelf handle
Index: An integer
Term: An arbitrary term or a variable

Description

This retrieves a copy of the stored term from the Index'th slot of the shelf object denoted by ShelfHandle.

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_get/3 with an Index of 0 retrieves the whole shelf with all its slots as a single compound term whose functor corresponds to the one that was given during shelf creation.

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.

Fail Conditions

None

Resatisfiable

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