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

shelf_get(+ShelfHandle, +Index, -Term)

Retrieve a stored term from a shelf object

ShelfHandle: A shelf handle or shelf name
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.

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

shelf_get(+, +, -) is det

Modules

This predicate is sensitive to its module context (tool predicate, see @/2).

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