| Did you know ... | Search Documentation: |
 | Pack dynworks -- prolog/dynarray_core.pl |
- HOME
- DOWNLOAD
- DOCUMENTATION
- TUTORIALS
- Beginner▶
- Advanced▶
- Web applications▶
- Semantic web▶
- Graphics▶
- Machine learning▶
- External collections▶
- For packagers▶
- COMMUNITY
- COMMERCIAL
- WIKI
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.
- 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]
- dynarray_destroy(+Id:atom) is det
- Destroy dynarray Id, and release all of its resources. No action if it does not exist.
- is_dynarray(+Id:atom) is semidet
- Fail if Id does not identify a dynarray.
- dynarray_version(-Version:number) is det
- Unify Version with the current version of the dynarray implementation.
- dynarray_dims(+Id:atom, -DimCount:int) is det
- Unify DimCount with 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.
- 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.
- dynarray_cells(+Id:atom, -CellCount:int) is det
- Unify CellCount with 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). - 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.
- 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). - 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.
- 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
- 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.
- 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.
- 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.
- 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.
- 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. - 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/> - 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/> - dynarray_fill(+Id:atom, +Value:data) is det
- Unify all the cells of the dynarray with Value.
- 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.