Did you know ... Search Documentation:
Pack dynworks -- prolog/dynarray_core.pl
PublicShow source

This module provides an implementation of dynamic multi-dimensional arrays. These are some of their noteworthy characteristics:

1. dynarrays are powerful, flexible, high-performance, hash-based
   multi-dimensional arrays;
2. dynarrays have O(1) read/insert/update/delete times, and this holds true
   up to sizes in the order of millions of cells;
3. dynarrays are not immutable objects, or more specifically, they are not
   recreated upon modification;
4. dynarrays have no limitation on the number of dimensions, nor any restriction
   on dimension sizes, apart from the running platform's resource limitations;
5. dynarrays have a maximum number of cells, defined at creation time and
   kept constant thereafter;
6. dynarrays demand no storage space reservation previous to the actual
   cell-by-cell space allocation requests;
7. dynarrays are resource-minded; their cells are not required to have values
   assigned to, in any particular sequence or fashion;
8. in order to avoid resource wastage, dynarrays should be explicitly destroyed,
   upon ceasing to be of any further use;
9. elements may be freely inserted, updated, or deleted, as long as their
   indices are within the dynarray's dimension bounds.
author
- GT Nunes
version
- 1.3.2
license
- BSD-3-Clause License
 dynarray_create(+Id:atom, +DimRanges:list) is semidet
Create a dynarray. Multi-dimensional dynarrays must be constructed with dimension sizes as integers > 0, and in this case their indices are 0-based positive integers, smaller then the corresponding dimension size (0 <= IndexI < DimSizeI).

Alternatively, a range of indices may be specified for any of its dimensions, in the form of an integer pair Ii:If. These pairs may contain negative values, and, within a single pair, the interval markers may be expressed in any order. Internally, offsets compensate for the fact that linear positions of cells start at 0 (zero).

These are examples of valid dynarray creation requests:

  dynarray_create(a, [9,5,8])      - indices ranges: [0 : 8,0 : 4,0 : 7]<br/>
  dynarray_create(a, [3,5,3 : -8]) - indices ranges: [0 : 2,-8 : 3]<br/>
  dynarray_create(a, [3,19 : 4])   - indices ranges: [0 : 2,4 : 19]<br/>
  dynarray_create(a, [-4 : -3,7])  - indices ranges: [-4 : -3,0 : 6]
Arguments:
Id- Atom identifying the dynarray
DimRanges- List of dimension ranges in ascending dimension order
 dynarray_destroy(+Id:atom) is det
Destroy dynarray Id, and release all of its resources. No action if it does not exist.
Arguments:
Id- atom identifying the dynarray
 is_dynarray(+Id:atom) is semidet
Fail if Id does not identify a dynarray.
Arguments:
Id- Atom identifying the dynarray
 dynarray_version(-Version:number) is det
Unify Version with the current version of the dynarray implementation.
Arguments:
Version- Dynarray implementation's current version
 dynarray_dims(+Id:atom, -DimCount:int) is det
Unify DimCount with the number of dimensions in the dynarray.
Arguments:
Id- Atom identifying the dynarray
DimCount- The number of dimensions in the dynarray
 dynarray_top(+Id:atom, +Dim:int, -Top:int) is semidet
Unify Top with the highest inserted index on the dimension Dim. This holds true even if this highest index has subsequently been deleted. Dimensions are 1-based integers, thus if Dim is specified as 0 (zero), unify Top with the list of the highest indices for all dimensions, instead. Upon dynarray's creation, this value is set to -1 for all dimensions.
Arguments:
Id- Atom identifying the dynarray
Dim- 1-based dimension ordinal, or 0 for all top indices
Top- Value of the highest index
 dynarray_position_top(+Id:atom, -Top:int) is det
Unify Top with the highest inserted 0-based linear position. This holds true even if the element at this highest linear position has subsequently been deleted. Unify Top with -1 If no element has been inserted.
Arguments:
Id- Atom identifying the dynarray
Top- Value of the highest linear position
 dynarray_cells(+Id:atom, -CellCount:int) is det
Unify CellCount with the number of cells in the dynarray.
Arguments:
Id- Atom identifying the dynarray
CellCount- The number of cells in the dynarray
 dynarray_cells(+Id:atom, +Dim:int, -CellCount:int) is semidet
Unify CellCount with the number of cells in the dimension Dim. The cell values are stored in the dynamic predicate dynarr_dims(Id, DimI, DimSizeI). For the special instance Dim0, this list of lists is stored:
[[DimSizeI,I],...,[DimSizeK,K]] (in ascending order by DimSizeI).
Arguments:
Id- Atom identifying the dynarray
Dim- The 1-based dynarray dimension
CellCount- The number of cells in the given dimension
 dynarray_elements(+Id:atom, -ElementsCount:int) is det
Unify ElementsCount with the number of elements in the dynarray. This might be a very costly operation, as the elements are counted by fully traversing the dynarray space.
Arguments:
Id- Atom identifying the dynarray
ElementsCount- The number of elements in the dynarray
 dynarray_value(+Id:atom, +Indices:list, ?Value:data) is semidet
Unify Value with the value of the dynarray cell at Indices.

Dynarrays may be sparsed, i.e., they may have cells not holding values, but attempts to retrieve the value of an empty cell will fail. Dynarray values are stored in the dynamic predicate dynarr_vaLues(Position, Id, Value).

Arguments:
Id- Atom identifying the dynarray
Indices- Indices identifying the element
Value- The dynarray cell value
 dynarray_position_value(+Id:atom, +Position:int, ?Value:data) is semidet
Unify Value with the value of the cell at Position.

The dynarray may be sparsed, i.e., it may have cell not holding values, but attempts to retrieve value of an empty cell will fail.

Arguments:
Id- Atom identifying the dynarray
Position- Linear position identifying the cell
Value- The dynarray cell value
 dynarray_label(+Id:atom, +Label:atom, ?Value:data) is semidet
Unify Value with the value associated with Label. This allows atoms to stand for indices. Label values are stored in the dynamic predicate dynarr_labels(Id, Label, Value).

The following are the read-only private labels in use:

  da_cells  - number of cells in the dynarray
  da_dims   - number of dimensions in the dynarray
  da_ranges - dimension ranges data used at the dynarray's creation
Arguments:
Id- Atom identifying the dynarray
Label- Atom standing for the named attribute
Value- Value associated with the named attribute
 dynarray_find(+Id:atom, +Indices:list, -Value:data) is semidet
dynarray_find(+Id:atom, -Indices:list, +Value:data) is semidet
Unify Indices or Value with an occurrence of Indices or Value in the dynarray, respectively. Fail if no such value or indices exist.
Arguments:
Id- Atom identifying the dynarray
Indices- The reference indices
Value- The reference value
 dynarray_position_find(+Id:atom, +Position:int, -Value:data) is semidet
dynarray_position_find(+Id:atom, -Position:int, +Value:data) is semidet
Unify Position or Value with an occurrence of Position or Value in the dynarray, respectively. Fail if no such value or position exists.
Arguments:
Id- atom identifying the dynarray
Position- the reference linear position
Value- the reference value
 dynarray_delete(+Id:atom, +Indices:list) is semidet
Erase the dynarray cell at Indices, releasing the storage space taken. Fail if no such cell exists.
Arguments:
Id- Atom identifying the dynarray
Indices- Indices identifying the cell
 dynarray_position_delete(+Id:atom, +Position:int) is semidet
Erase the dynarray cell at the given Position, releasing the storage space taken. Fail if no such cell exists.
Arguments:
Id- Atom identifying the dynarray
Position- Linear position identifying the cell
 dynarray_list(+Id:atom, ?List:list) is det
Unify List with the contents of the dynarray, or the cells of the dynarray with the values in List. The dynarray may be empty. If List is grounded, the dynarray is created or erased prior to the load operation.
A 1-dimension dynarray sized to hold all the list elements may be created. Note that this is not a serialization mechanism, and as such it should not be used for backup/restore purposes.
Arguments:
Id- Atom identifying the dynarray
List- List of values to unify the dynarray cells with
 dynarray_sort(+Id:atom) is det
Numerically sort the contents of the dynarray, in ascending order. It must be possible to numerically compare any two elements stored in the dynarray. The dynarray indices are retrieved in dimension order, from the first dimension (left-most) to the last (right-most).
In the case of a sparse dynarray, the empty cells are ignored. Nothing is done if the dynarray contains less than two elements. Depending on the volume and nature of the data stored, this may be a very expensive operation, in terms of memory and/or time consumed.<br/>
Arguments:
Id- Atom identifying the dynarray
 dynarray_sort(+Id:atom, :Comparator:pred) is det
Sort the contents of the dynarray according to the given comparison predicate. The dynarray indices are retrieved in dimension order, from the first dimension (left-most) to the last (right-most).
The comparison predicate must accept two parameters, ValueX and ValueY, and have the following behavior:
<Comparator>(+ValueX, +ValueY, -Result:number) is det
where Result is unified with
  a) 0 (zero)          - ValueX is equal to ValueY
  b) a negative number - ValueX is less than ValueY
  c) a positive number - ValueX is greater than ValueY

The criteria that will determine the results of the comparisons are entirely up to Comparator, and as such it must be able to handle all the values it receives.
In the case of a sparse dynarray, the empty cells are ignored. Nothing is done if the dynarray contains less than two elements. Depending on the volume and nature of the data stored, this may be a very expensive operation, in terms of memory and/or time consumed.<br/>

Arguments:
Id- Atom identifying the dynarray
Comparator- Predicate to perform comparisons between two values
 dynarray_fill(+Id:atom, +Value:data) is det
Unify all the cells of the dynarray with Value.
Arguments:
Id- Atom identifying the dynarray
Value- Value to unify the dynarray cells with
 dynarray_position_indices(+Id:atom, +Position:int, -Indices:list) is semidet
dynarray_position_indices(+Id:atom, -Position:int, +Indices:list) is semidet
Unify Position or Indices with the corresponding Position or Indices, respectively.
Arguments:
Id- Atom identifying the dynarray
Position- The final 0-based linear position of the element
Indices- The element's indices (offset-corrected, if applicable)