[ 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 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

    For examples see shelf_create/2,3.

## See Also

shelf_create / 2, shelf_create / 3, shelf_set / 3, shelf_abolish / 1, struct / 1