This module provides persistence for dynarray objects, using the Berkeley DB utility package. Please, refer to bdb_wrapper.pl for details on the SWI-Prolog interface to Berkeley DB.

Additionally, persisting and restoring from `.csv` files is also implemented. Please, refer to the csv_wrapper.pl for details.

The following considerations apply for CSV operations:

1. the dynarray involved must be 2-dimensional, and will be handled as having
   rows (dimension 1) and columns (dimension 2);
2. the stream involved must be of type 'text', and will be read or written from
   its current position;
3. persisting to, or restoring from, the given stream will be attempted,
   depending on whether or not the dynarray exists;
4. input and output are performed through the Prolog platform's built-in CSV
   library;
5. when persisting, the atoms associated with the dynarray's columns, if they
   exist, will be used as field names in the CSV file's header record;
6. when persisting, the data registered as labels, apart from the column names,
   will not be included;
7. when persisting, missing cells will be recorded on the CSV file as empty fields
   (containing the null char '\000\');
8. when restoring, an attempt will be made to extract field names from the CSV
   file's first record and use them as labels; if not possible, the record will be
   treated as regular data.

author

- GT Nunes

version

- 1.3.2

copyright

- (c) TheWiseCoder 2020-2021

license

- BSD-3-Clause License

 dynarray_clone(+Id:atomSource:atom, +Id:atomTarget:atom) is semidet

Clone a dynarray.

Arguments:

IdSource	- Atom identifying the source dynarray
IdTarget	- Atom identifying the target dynarray

 dynarray_csv(+Id:atom, +Stream:ref) is det

Persist or restore a dynarray into/from a CSV file.

Arguments:

Id	- Atom identifying the dynarray
Stream	- Stream to read from/write to

 dynarray_serialize(+Id:atom, ?Serialized:data) is det

A serialization mechanism, for backup/restore purposes. For a given dynarray containing Nv values and Nb labels, its serialization structure will be:

  [<dims-ranges>],<Nb>,
  [<key-label-1>,<value-label-1>],...,[<key-label-Nb>,<value-label-Nb>],
  [<pos-value-1>,<value-1>],...,[<pos-value-Nv>,<value-Nv>]

The serialized list will thus contain Np + Nv + 2 elements:
<dims-ranges> - the dimensions ranges used for the dynarray creation
<num-labels> - the total number of key-value label pairs
<key-label-j> - the key in the key-value label pair j
<value-label-j> - the value in the key-value label pair j
<pos-value-j> - the linear position of value j within the dynarray
<value-j> - the value j within the dynarray

Arguments:

Id	- Atom identifying the dynarray
Serialized	- Serialization list containing the dynarray data

 dynarray_persist(+Id:atom, +DataSet:atom) is det

Persist the dynarray data to a Berkeley DB external storage.

Arguments:

Id	- Atom identifying the dynarray
DataSet	- Atom identifyingt the data set

 dynarray_restore(+Id:atom, +DataSet:atom) is det

Restore the dynarray data from a Berkeley DB external storage.

Arguments:

Id	- Atom identifying the dynarray
DataSet	- Atom identifyingt the data set

 dynarray_erase(+Id:atom, +DataSet:atom) is det

Erase the dynarray's persisted data.

Arguments:

Id	- Atom identifying the dynarray
DataSet	- Atom identifyingt the data set