[ Reference Manual | Alphabetic Index ]

# Non-logical Variables, Arrays, Bags, Shelves and Stores

Built-ins to store data across backtracking [more]

## Predicates

> local array(++Array)
>   Creates the untyped non-logical array Array.
> local array(+Array, +Type)
>   Creates a non-logical array Array with given Type.
> bag_abolish(+BagHandle)
>   Destroy a bag explicitly
> bag_count(+BagHandle, -Count)
>   Get the number of entries in a bag
> bag_create(-BagHandle)
>   Create a bag object which can store data across failures
> bag_dissolve(+BagHandle, -List)
>   Retrieve a bag's contents and destroy the bag
> bag_enter(+BagHandle, +Term)
>   Enter a term into an existing bag object
> bag_erase(+BagHandle)
>   Erase the contents of a bag
> bag_retrieve(+BagHandle, -List)
>   Retrieve a bag's contents
> current_array(?Array, -Options)
>   Succeeds if there exists an array as denoted by Array and with type and visibility as given in the list Options.
> current_store(?StoreName)
>   StoreName is a visible store name
> decval(++ElemSpec)
>   Decrements the contents of the visible non-logical variable or array element ElemSpec by one.
> erase_array(++ArraySpec)
>   Erases existing visible array or non-logical variable.
> getref(+Name, -Value)
>   Gets the value of the named reference.
> getval(++ElemSpec, -Value)
>   Retrieves the value of the visible array element or non-logical variable ElemSpec
> incval(++ElemSpec)
>   Increments the contents of the visible non-logical variable or array element ElemSpec by one.
> name_to_handle(+Type, +Name, -Handle)
>   Obtain a handle for a named object
> local reference(+Name, ?Init)
>   Creates a named reference called Name with intial value Init.
> setref(+Name, ?Value)
>   Sets the value of the named reference to Value.
> setval(++ElemSpec, ?Value)
>   Sets the value of a non-logical variable or array element to the value Value.
> local shelf(++Name, +Init)
>   Create a named shelf object which can store data across failures
> shelf_abolish(+ShelfHandle)
>   Destroy a shelf explicitly
> shelf_create(+InitTerm, -ShelfHandle)
>   Create a shelf object which can store data across failures
> shelf_create(++ShelfSpec, ?SlotInit, -ShelfHandle)
>   Create a shelf object which can store data across failures
> shelf_dec(+ShelfHandle, +Index)
>   Decrement an integer slot within a shelf object but fail if is zero
> shelf_get(+ShelfHandle, +Index, -Term)
>   Retrieve a stored term from a shelf object
> 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
> shelf_inc(+ShelfHandle, +Index)
>   Increment an integer slot within a shelf object
> shelf_inc_and_get(+ShelfHandle, +Index, -NewValue)
>   Increment an integer slot within a shelf object and get the new value
> shelf_set(+ShelfHandle, +Index, ?Term)
>   Store a term in a shelf object
> shelf_size(+ShelfHandle, -Size)
>   Get the number of slots of a shelf object
> shelf_test_and_set(+ShelfHandle, +Index, +Expected, ?NewValue)
>   Replace a given term in a shelf object
> local store(++Name)
>   Create a named store object which can store indexed data across failures
> store_contains(+StoreHandle, ++Key)
>   Check for an entry in a store object
> store_count(+StoreHandle, -Count)
>   Retrieve the number of entries in a store object
> store_create(-StoreHandle)
>   Create an anonymous store object which can store indexed data across failures
> store_delete(+StoreHandle, ++Key)
>   Delete an entry in a store object
> store_erase(+StoreHandle)
>   Erase the contents of the specified store object
> store_get(+StoreHandle, ++Key, -Value)
>   Look up an entry in a store object
> store_inc(+StoreHandle, ++Key)
>   Increment an integral entry within a store object
> store_insert(+StoreHandle, ++Key, ?Value)
>   Make an entry into a store object, provided none exists yet
> store_remove(+StoreHandle, ++Key, -Value)
>   Get and delete an entry from a store object
> store_set(+StoreHandle, ++Key, ?Value)
>   Make an entry into a store object
> store_test_and_set(+StoreHandle, ++Key, ++OldValue, ?NewValue)
>   Update an existing entry in a store object
> store_update(+StoreHandle, ++Key, -OldValue, ?NewValue)
>   Update an existing entry in a store object
> stored_keys(+StoreHandle, -Keys)
>   Retrieve all keys stored in a store object
> stored_keys_and_values(+StoreHandle, -KeysValues)
>   Retrieve all data stored in a store object
> swapref(+Name, -OldValue, ?NewValue)
>   Get and set the value of the named reference.
> test_and_setval(+VarName, ?Old, ?New)
>   Test whether a non-logical variable has value Old and if so, set it to New.
> local variable(+Name)
>   Creates the untyped non-logical variable Name.
> local variable(+Name, ?Init)
>   Creates the untyped non-logical variable Name.

## Description

ECLiPSe provides several facilities to store information across backtracking. The following table gives an overview. If at all possible, the handle-based facilities (bags, records, shelves, stores) should be preferred because they lead to cleaner, reentrant code (without global state) and reduce the risk of memory leaks.

        Facility        Type            Reference       See
        ================================================================
        bags            unordered bag   by handle       bag_create/1
        ----------------------------------------------------------------
        anon.records    ordered list    by handle       record_create/1
        ----------------------------------------------------------------
        shelves         array           by handle       shelf_create/2,3
        ----------------------------------------------------------------
        stores          hash table      by handle       store_create/1
        ----------------------------------------------------------------
        named shelves   array           by name         shelf/2
        ----------------------------------------------------------------
        named stores    hash table      by name         store/1
        ----------------------------------------------------------------
        non-logical     single cell     by name         variable/1,2
        variables
        ----------------------------------------------------------------
        non-logical     array           by name         array/1,2
        arrays
        ----------------------------------------------------------------
        named records   ordered list    by name         record/1,2
        ----------------------------------------------------------------
        dynamic         ordered list    by name         dynamic/1,assert/1
        predicates
        ----------------------------------------------------------------

Generated from storage.eci on 2022-09-03 14:26