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
- copyright
- - (c) TheWiseCoder 2020-2021
- 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) |