DimArrays
Dim
| Use | Function | Description |
|---|
Dimensioned Array Construction
| Use | Function | Description |
|---|---|---|
| dim d1; | Create an dimensioned array of vars pending actual dimensions. | |
| dim d1(nrows, ncols = 1); | Create an array of vars with a fixed number of columns and rows. All vars are unassigned. | |
| dim d1 = d2; // Copy | Create a copy of an array. | |
| dim d1 = dim(); // Move | Save an array created elsewhere. | |
| dim d1 = {"a", "b", "c" ...}; // Initializer list | Create an array from a list. All elements must be the same type. var, string, double, int, etc.. | |
| dim d1 = v1; | Initialise all elements of an array to some single value or constant. A var, "", 0 etc. | |
| d1.redim(nrows, ncols = 1) | Resize an array to a different number of rows and columns.
Existing data will be retained as far as possible. Any additional elements are unassigned. Resizing rows to 0 clears all data. Resizing cols to 0 clears all data and changes its status to "undimensioned". | |
| d1.swap(d2) | Swap one array with another.
Either or both may be undimensioned. |
Array Access
| Use | Function | Description |
|---|---|---|
| var v1 = d1[rowno]; d1[rowno] = v1; |
Access and update elements of a one dimensional array using [] brackets | |
| var v1 = d1[rowno, colno]; d1[rowno, colno] = v1; |
Access and update elements of an two dimensional array using [] brackets | |
| var= | d1.rows() | Get the number of rows in the dimensioned array
Returns: A count. Can be zero, indicating an empty array. |
| var= | d1.cols() | Get the number of columns in the dimensioned array
Returns: A count. 0 if the array is undimensioned. |
| var= | d1.join(delimiter = FM) | Joins all elements into a single delimited string
Returns: A string var. |
Array Mutation
| Use | Function | Description |
|---|---|---|
| d1.splitter(str1, delimiter = FM) | Creates or updates the array from a given string.
If the dim array has not been dimensioned (nrows and ncols are 0), it will be dimensioned with the number of elements that the string has fields. If the dim array has already been dimensioned, and has more elements than there are fields in the string, the excess array elements are initialised to "". If the record has more fields than there are elements in the array, the excess fields are all left unsplit in the final element of the array. Predimensioning arrays allows efficient reuse of arrays in loops. In either case, all elements of the array are updated. dim d1;
d1.splitter("f1^f2^f3"_var); // d1.rows() -> 3
//
dim d2(10);
d2.splitter("f1^f2^f3"_var); // d2.rows() -> 10
| |
| d1.sorter(reverse = false) | Sort the elements of the array. In place.
reverse: Defaults to false. If true, then the order is reversed. | |
| d1.reverser() | Reverse the elements of the array. In place. | |
| d1.shuffler() | Randomly shuffle the order of the elements of the array. In place. |
Array Conversion
| Use | Function | Description |
|---|---|---|
| dim= | d1.sort(reverse = false) | Same as sorter() but returns a new array leaving the original untouched. |
| dim= | d1.reverse() | Same as reverser() but returns a new array leaving the original untouched. |
| dim= | d1.shuffle() | Same as shuffler() but returns a new array leaving the original untouched. |
Array DB I/O
| Use | Function | Description |
|---|---|---|
| d1.write(dbfile, key) | Writes a db file record created from an array.
Each element in the array becomes a separate field in the db record. Any redundant trailing FMs are suppressed. dim d1 = "Client GD^G^20855^30000^1001.00^20855.76539"_var.split();
let file = "xo_clients", key = "GD001";
if (not deleterecord("xo_clients", "GD001")) {}; // Cleanup first
d1.write(file, key);
// or
write(d1 on file, key);
| |
| if | d1.read(dbfile, key) | Read a db file record into an array.
Each field in the database record becomes a single element in the array. Returns: True if the record exists or false if not, If the array is predimensioned then any excess array elements are initialised to "" and any excess record fields are left unsplit in the final array element. See dim splitter for more info. If the array is not predimensioned (rows and cols = 0) then it will be dimensioned to have exactly the same number of rows as there are fields in the record being read. dim d1(10);
let file = "xo_clients", key = "GD001";
if (not d1.read(file, key)) ... // d1.join() -> "Client GD^G^20855^30000^1001.00^20855.76539^^^^"_var
// or
if (not read(d1 from file, key)) ...
|
Array OS I/O
| Use | Function | Description |
|---|---|---|
| if | d1.oswrite(osfilename, codepage = "") | Creates an entire os text file from an array
Each element of the array becomes one line in the os file delimited by \n Any existing os file is overwritten and replaced. codepage: Optional: Data is converted from UTF8 to the required codepage/encoding before output. If the conversion cannot be performed then return false. Returns: True if successful or false if not. dim d1 = "aaa=1\nbbb=2\nccc=3\n"_var.split("\n");
if (not osremove("xo_conf.txt")) {}; // Cleanup first
let osfilename = "xo_conf.txt";
if (not d1.oswrite(osfilename)) ...
// or
if (not oswrite(d1 on osfilename)) ...
|
| if | d1.osread(osfilename, codepage = "") | Read an entire os text file into an array.
Each line in the os file, delimited by \n or \r\n, becomes a separate element in the array. codepage: Optional. Data will be converted from the specified codepage/encoding to UTF8 after being read. If the conversion cannot be performed then return false. Returns: True if successful or false if not. If the first \n in the file is \r\n then the whole file will be split using \r\n as delimiter. dim d1;
let osfilename = "xo_conf.txt";
if (not d1.osread(osfilename)) ... // d1.join("\n") -> "aaa=1\nbbb=2\nccc=3\n"_var0
// or
if (not osread(d1 from osfilename)) ...
|
:
