DimArrays - Revision history

Steve at 06:32, 23 March 2025

2025-03-23T06:32:39Z

← Older revision		Revision as of 06:32, 23 March 2025
Line 21:		Line 21:
	<syntaxhighlight lang="c++">		<syntaxhighlight lang="c++">
	dim d1(10);		dim d1(10);
	dim d2(10,3);</syntaxhighlight>		dim d2(10, 3);</syntaxhighlight>

	\|-		\|-
	\|\|\|dim d1 = d2; // Copy\|\|Create a copy of an array.		\|\|\|dim d1 = d2; // Copy\|\|Create a copy of an array.
	<syntaxhighlight lang="c++">		<syntaxhighlight lang="c++">
	dim d1 = {1,2,3,4,5};		dim d1 = {2, 4, 6, 8};
	dim d2 = d1;</syntaxhighlight>		dim d2 = d1;</syntaxhighlight>

	\|-		\|-
	\|\|\|dim d1 = dim(); // Move\|\|Save an array created elsewhere.		\|\|\|dim d1 = dim(); // Move\|\|Save an array created elsewhere.

			Uses C++ "move" semantics.
	<syntaxhighlight lang="c++">		<syntaxhighlight lang="c++">
	dim d1 = "f1^f2^f3"_var.split();</syntaxhighlight>		dim d1 = "f1^f2^f3"_var.split();</syntaxhighlight>

	\|-		\|-
	\|\|\|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 = {"a", "b", "c" ...}; // Initializer list\|\|Create an array from a list. All elements must be the same type, var, string, double, int, etc.. but all end up as vars which are a flexible type.
	<syntaxhighlight lang="c++">		<syntaxhighlight lang="c++">
	dim d1 = {1, 2, 3, 4, 5};		dim d1 = {1, 2, 3, 4, 5};
Line 56:		Line 58:
	<syntaxhighlight lang="c++">		<syntaxhighlight lang="c++">
	dim d1;		dim d1;
	d1.redim(10);</syntaxhighlight>		d1.redim(10, 3);</syntaxhighlight>

	\|-		\|-
Line 121:		Line 123:
	\|\|\|d1.splitter(str1, delimiter = FM)\|\|Creates or updates the array from a given string.		\|\|\|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 is undimensioned 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.		If the dim array is 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.		Predimensioning arrays allows the efficient reuse of arrays in loops and ensures that all elements are assigned values, useful when reading records from db files.

	~~In either case, all~~ elements ~~of the array are updated~~.		Using undimensioned arrays allows the efficient handling of arrays with a very variable number of elements. e.g. os text files.
	<syntaxhighlight lang="c++">		<syntaxhighlight lang="c++">
	dim d1;		dim d1;
	d1.splitter("f1^f2^f3"_var); // d1.rows() -> 3		d1.splitter("f1^f2^f3"_var); // d1.rows() -> 3 // Automatically dimensioned.
	//		//
	dim d2(10);		dim d2(10);
	d2.splitter("f1^f2^f3"_var); // d2.rows() -> 10</syntaxhighlight>		d2.splitter("f1^f2^f3"_var); // d2.rows() -> 10 // Predimensioned. Excess elements become ""</syntaxhighlight>

	\|-		\|-
	\|\|\|d1.sorter(reverse = false)\|\|Sort the elements of the array~~. In~~ place.		\|\|\|d1.sorter(reverse = false)\|\|Sort the elements of the array in place.

	<em>reverse:</em> Defaults to false. If true, then the order is reversed.		<em>reverse:</em> Defaults to false. If true, then the order is reversed.
Line 145:		Line 147:

	\|-		\|-
	\|\|\|d1.reverser()\|\|Reverse the elements of the array~~. In~~ place.		\|\|\|d1.reverser()\|\|Reverse the elements of the array in place.
	<syntaxhighlight lang="c++">		<syntaxhighlight lang="c++">
	dim d1 = "2,20,10,1"_var.split(",");		dim d1 = "2,20,10,1"_var.split(",");
Line 152:		Line 154:

	\|-		\|-
	\|\|\|d1.shuffler()\|\|Randomly shuffle the order of the elements of the array~~. In~~ place.		\|\|\|d1.shuffler()\|\|Randomly shuffle the order of the elements of the array in place.
	<syntaxhighlight lang="c++">		<syntaxhighlight lang="c++">
	dim d1 = "2,20,10,1"_var.split(",");		dim d1 = "2,20,10,1"_var.split(",");
Line 230:		Line 232:

	Each line in the os file, delimited by \n or \r\n, becomes a separate element in the array.		Each line in the os file, delimited by \n or \r\n, becomes a separate element in the array.

			Existing data in the array is lost and the array is redimensioned to the number of lines in the input data.

	<em>codepage:</em> Optional. Data will be converted from the specified codepage/encoding to UTF8 after being read. If the conversion cannot be performed then return false.		<em>codepage:</em> Optional. Data will be converted from the specified codepage/encoding to UTF8 after being read. If the conversion cannot be performed then return false.

Steve at 20:45, 22 March 2025

2025-03-22T20:45:53Z

Show changes

Steve: Created page with " ==== Dim ==== {|class="wikitable" !Use!!Function!!Description |} ===== Dimensioned Array Construction ===== {|class="wikitable" !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 el..."

2025-03-22T13:46:12Z

Created page with " ==== Dim ==== {|class="wikitable" !Use!!Function!!Description |} ===== Dimensioned Array Construction ===== {|class="wikitable" !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 el..."

New page

==== Dim ====

{|class="wikitable"
!Use!!Function!!Description
|}
===== Dimensioned Array Construction =====

{|class="wikitable"
!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 =====

{|class="wikitable"
!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 =====

{|class="wikitable"
!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.
<syntaxhighlight lang="c++">
dim d1;
d1.splitter("f1^f2^f3"_var); // d1.rows() -> 3
//
dim d2(10);
d2.splitter("f1^f2^f3"_var); // d2.rows() -> 10</syntaxhighlight>
|-
|||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 =====

{|class="wikitable"
!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 =====

{|class="wikitable"
!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.
<syntaxhighlight lang="c++">
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);</syntaxhighlight>
|-
|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.
<syntaxhighlight lang="c++">
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)) ...</syntaxhighlight>
|}
===== Array OS I/O =====

{|class="wikitable"
!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.
<syntaxhighlight lang="c++">
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)) ...</syntaxhighlight>
|-
|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.
<syntaxhighlight lang="c++">
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)) ...</syntaxhighlight>
|}: