Manual: Difference between revisions

From NEOSYS Dev Wiki
Jump to navigationJump to search
(Replaced content with "=== ICONV/OCONV PATTERNS === ==== Decimal (MD/MC) ==== {|class="wikitable" !input!!conversion (string)!!output |- |1234||MD2||12.34 |- |1234||MD20||1234.00 |- |1234||MD20,||1,234.00 |- |1234.5678||MD2||12.35 |- |1234.5678||MD20||1234.57 |- |1234.5678||MD20,||1,234.57 |- |1234||MC2||12,34 |- |1234||MC20||1234,00 |- |1234||MC20,||1.234,00 |- |1234||MD20-||1234.00 |- |-1234||MD20-||1234.00- |} ==== Date (D) ==== {|class="wikitable" !input!!conversion (string)!!ou...")
Tag: Replaced
Line 330: Line 330:


==== Complete List of Functions ====
==== Complete List of Functions ====
=== Var Creation  ===
{|class="wikitable"
!Usage!!Function!!Description
|-
|var()||var v1;||Create an unassigned var.
Whereever possible, variables should be assigned an initial value immediately at their point of definition, and marked as const if appropriate. However variables often have no real single initial value and are commonly defined in advance of being assigned a particular value. For example, a variable may be assigned differently on different branches of a conditional statement, or be provided as an outbound argument of a function call.
Even when not assigned, "use before initialisation" bugs do not occur because a runtime error VarUnassigned is thrown if a var is used before it has been assigned a value.
Use "let" instead of "var" as a shorthand way of writing "const var" whereever possible.
<syntaxhighlight lang="c++">
let clients = "xo_clients", key = "SB001"; // const vars
var client;                                // Unassigned var
if (not read(client from clients, key)) ...</syntaxhighlight>
|-
|cmd||var v1 = expression;||Assign a var using a literal or an expression. Alternatively, use "let" instead of "var" as a shorthand way of writing "const var" where appropriate.
<syntaxhighlight lang="c++">
var v1 = 42;                // Integer
var v2 = 42.3;              // Double
var v3 = "abc";              // String
var v4 = 'x';                // char
var v5 = true;              // bool
var v6 = v1 + 100;          // Arithmetic
var v7 = v3 ^ "xyz";        // Concatenation
var v8 = oslist(".").sort(); // Built in functions
let v9 = 12345;              // A const var
var v10 = 12'345_var;        // A literal var integer
var v11 = 123.45_var;        // A literal var double
var v12 = "f1^v1]v2^f3"_var; // A literal var string
var x = 0.1, y = "0.2", z = x + y; // z -> 0.3</syntaxhighlight>
|-
|if||v1.assigned()||Returns: True if the var is assigned, otherwise false
|-
|if||v1.unassigned()||Returns: True if the var is unassigned, otherwise false
|-
|var=||v2.or_default(defaultvalue)||Returns: A copy of the var if it is assigned or the default value if it is not.
Can be used to handle optional arguments in functions.
<em>defaultvalue:</em> Cannot be unassigned.
<syntaxhighlight lang="c++">
var v1; // Unassigned
var v2 = v1.or_default("abc"); // v2 -> "abc"
// or
var v3 = or_default(v1, "abc");</syntaxhighlight>
|-
|cmd||v1.defaulter(defaultvalue)||If the var is unassigned then assign the default value to it, otherwise do nothing.
<em>defaultvalue:</em> Cannot be unassigned.
<syntaxhighlight lang="c++">
var v1; // Unassigned
v1.defaulter("abc"); // v1 -> "abc"
// or
defaulter(v1, "abc");</syntaxhighlight>
|-
|cmd||v1.swap(io v2)||Swap the contents of one var with another.
Useful for stashing large strings quickly. They are moved using pointers without making copies or allocating memory.
Eiher or both variables may be unassigned.
<syntaxhighlight lang="c++">
var v1 = space(65'536);
var v2 = "";
v1.swap(v2); // v1 -> "" // v2.len() -> 65'536
// or
swap(v1, v2);</syntaxhighlight>
|-
|var=||v2.move()||Force the contents of a var to be moved instead of copied. The moved var becomes an empty string.
This allows large strings to be handled efficiently. They are moved using pointers without making copies or allocating memory.
The moved var must be assigned otherwise a VarUnassigned error is thrown.
<syntaxhighlight lang="c++">
var v1 = space(65'536);
var v2 = v1.move(); // v2.len() -> 65'536 // v1 -> ""
// or
var v3 = move(v2);</syntaxhighlight>
|-
|var=||v2.clone()||Returns a copy of the var.
The cloned var may be unassigned, in which case the copy will be unassigned too.
<syntaxhighlight lang="c++">
var v1 = "abc";
var v2 = v1.clone(); // "abc"
// or
var v3 = clone(v2);</syntaxhighlight>
|-
|var=||v1.dump()||Return a string describing internal data of a var.
If the str is located on the heap then its address is given.
<em>typ:</em>
0x01 str is available.
0x02 int is available.
0x04 dbl is available.
0x08 nan: str is not a number.
0x16 osfile: str, int and dbl have special meaning.
<syntaxhighlight lang="c++">
var v1 = str("x", 32);
v1.dump().outputl(); // e.g. var:0x7ffea7462cd0 typ:1 str:0x584d9e9f6e70 "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
// or
outputl(dump(v1));</syntaxhighlight>
|}
=== Arithmetical Operators  ===
{|class="wikitable"
!Usage!!Function!!Description
|-
|if||v1.isnum()||Checks if a var is numeric.
<em>Returns:</em> True if a var holds a double, an integer, or a string that is defined as numeric.
A string is defined as numeric only if it consists of one or more digits 0-9, with an optional decimal point "." placed anywhere, with an optional + or - sign prefix, or it is the empty string "", which is defined to be zero.
<syntaxhighlight lang="c++">
if ("+123.45"_var.isnum()) ... ok
if (      ""_var.isnum()) ... ok
if (not  "."_var.isnum()) ... ok
// or
if (isnum("123.")) ... ok</syntaxhighlight>
|-
|var=||v1.num()||Returns a copy of the var if it is numeric or 0 otherwise.
<em>Returns:</em> A guaranteed numeric var
Allows working numerically with data that may be non-numeric.
<syntaxhighlight lang="c++">
var v1 = "123.45"_var.num();    // 123.45
var v2 = "abc"_var.num() + 100; // 100</syntaxhighlight>
|-
|var=||v2 + v3||Addition
Attempts to perform mumeric operations on non-numeric strings will throw a runtime error VarNonNumeric.
Floating point numbers are implicitly converted to strings with no more than 12 significant digits of precision. This practically eliminates all floatng point rounding errors.
Internally, 0.1 + 0.2 looks like this using doubles.
0.10000000000000003 + 0.20000000000000004 -> 0.30000000000000004
<syntaxhighlight lang="c++">
var v1 = 0.1;
var v2 = v1 + 0.2; // 0.3</syntaxhighlight>
|-
|var=||v2 - v3||Subtraction
|-
|var=||v2 * v3||Multiplication
|-
|var=||v2 / v3||Division
|-
|var=||v2 % v3||Modulus
|-
|||v1 += v2||Self addition
<syntaxhighlight lang="c++">
var v1 = 0.1;
v1 += 0.2; // 0.3</syntaxhighlight>
|-
|||v1 -= v2||Self subtraction
|-
|||v1 *= v2||Self multiplication
|-
|||v1 /= v2||Self division
|-
|||v1 %= v2||Self modulus
|-
|||v1 ++||Post increment
<syntaxhighlight lang="c++">
var v1 = 3;
var v2 = v1 ++; // v2 -> 3 // v1 -> 4</syntaxhighlight>
|-
|||v1 --||Post decrement
<syntaxhighlight lang="c++">
var v1 = 3;
var v2 = v1 --; // v2 -> 3 // v1 -> 2</syntaxhighlight>
|-
|||++ v1||Pre increment
<syntaxhighlight lang="c++">
var v1 = 3;
var v2 = ++ v1; // v2 -> 4 // v1 -> 4</syntaxhighlight>
|-
|||-- v1||Pre decrement
<syntaxhighlight lang="c++">
var v1 = 3;
var v2 = -- v1; // v2 -> 2 // v1 -> 2</syntaxhighlight>
|}
=== Dynamic Array Creation, Access And Update ===
{|class="wikitable"
!Usage!!Function!!Description
|-
|var=||""_var||The literal suffix "_var" allows dynamic arrays to be seamlessly embedded in code using the visible equivalents of unprintable field mark characters.
RM ` Record mark
FM ^ Field mark
VM ] Value mark
SM } Subvalue mark
TM | Text mark
ST ~ Subtext mark
<syntaxhighlight lang="c++">
var v1 = "f1^f2^v1]v2^f4"_var; // "f1" _FM "f2" _FM "v1" _VM "v2" _FM "f4"</syntaxhighlight>
|-
|var(std::initializer_list<T>||var v1 = {"a", "b", "c" ...}; // Initializer list||Create an dynamic array var from a list. C++ constrains list elements to be all the same type. var, string, double, int, etc.
<syntaxhighlight lang="c++">
var v1 = {11, 22, 33}; // "11^22^33"_var</syntaxhighlight>
|-
|var=||v2(fieldno);      v1(fieldno) = v2||Dynamic array - field update and append:
See also inserter() and remover().
<syntaxhighlight lang="c++">
var v1 = "aa^bb"_var;
v1(4) = 44; // v1 -> "aa^bb^^44"_var
// Field number -1 causes appending a field when updating.
v1(-1) = "55"; // v1 -> "aa^bb^^44^55"_var</syntaxhighlight>
Field access:
It is recommended to use "v1.f(fieldno)" syntax using a ".f(" prefix to access fields in expressions instead of plain "v1(fieldno)". The former syntax (using .f()) will always compile whereas the latter does not compile in all contexts. It will compile only if being called on a constant var or in a location which requires a var. This is due to C++ not making a clear distinction between usage on the left and right side of assignment operator =.
Furthermore using plain round brackets without the leading .f can be confused with function call syntax.
<syntaxhighlight lang="c++">
var v1 = "aa^bb^cc"_var;
var v2 = v1.f(2); // "bb" /// .f() style access. Recommended.
var v3 =  v1(2); // "bb" ///  () style access. Not recommended.</syntaxhighlight>
|-
|var=||v2(fieldno, valueno);      v1(fieldno, valueno) = v2||Dynamic array - value update and append
See also inserter() and remover().
<syntaxhighlight lang="c++">
var v1 = "aa^b1]b2^cc"_var;
v1(2, 4) = "44"; // v1 -> "aa^b1]b2]]44^cc"_var
// value number -1 causes appending a value when updating.
v1(2, -1) = 55; // v1 -> "aa^b1]b2]]44]55^cc"_var</syntaxhighlight>
Value access:
<syntaxhighlight lang="c++">
var v1 = "aa^b1]b2^cc"_var;
var v2 = v1.f(2,2); // "b2" /// .f() style access. Recommended.
var v3 =  v1(2,2); // "b2" ///  () style access. Not recommended.</syntaxhighlight>
|-
|var=||v2(fieldno, valueno, subvalueno);      v1(fieldno, valueno, subvalueno) = v2||Dynamic array - subvalue update and append
See also inserter() and remover().
<syntaxhighlight lang="c++">
var v1 = "aa^bb^cc"_var;
v1(2, 2, 2) = "22"; // v1 -> "aa^bb]}22^cc"_var
// subvalue number -1 causes appending a subvalue when updating.
v1(2, 2, -1) = 33; // v1 -> "aa^bb]}22}33^cc"_var</syntaxhighlight>
Subvalue access:
<syntaxhighlight lang="c++">
var v1 = "aa^b1]b2}s2^cc"_var;
var v2 = v1.f(2, 2, 2); // "s2" /// .f() style access. Recommended.
var v3 =  v1(2, 2, 2); // "s2" ///  () style access. Not recommended.</syntaxhighlight>
|}
=== String Creation  ===
{|class="wikitable"
!Usage!!Function!!Description
|-
|var=||v2 ^ v3||String concatention operator ^
At least one side must be a var.
"aa" ^ "22" will not compile but "aa" "22".
Floating point numbers are implicitly converted to strings with no more than 12 significant digits of precision. This practically eliminates all floatng point rounding errors.
<syntaxhighlight lang="c++">
var v2 = "aa";
var v1 = v2 ^ 22; // "aa22"</syntaxhighlight>
|-
|||v1 ^= v2||String self concatention ^= (append)
<syntaxhighlight lang="c++">
var v1 = "aa";
v1 ^= 22; // v1 -> "aa22"</syntaxhighlight>
|-
|var=||varnum.round(ndecimals = 0)||Convert a number into a string after rounding it to a given number of decimal places.
<em>var:</em> The number to be converted.
<em>ndecimals:</em> Determines how many decimal places are shown to the right of the decimal point or, if ndecimals is negative, how many 0's to the left of it.
<em>Returns:</em> A var containing an ASCII string of digits with a leading "-" if negative, and a decimal point "." if ndecimals is > 0.
Trailing zeros are not omitted. A leading "0." is shown where appropriate.
0.5 always rounds away from zero. i.e. 1.5 -> 2 and -1.5 -> -2
<syntaxhighlight lang="c++">
let v1 = var(0.295).round(2);  //  "0.30"
// or
let v2 = round(1.295, 2);      //  "1.30"
var v3 = var(-0.295).round(2); // "-0.30"
// or
var v4 = round(-1.295, 2);    // "-1.30"</syntaxhighlight>
var v4 = round(0, 1);          // "0.0";
var v5 = round(0, 0);          // "0";
var v6 = round(0, -1);          // "0";
Negative number of decimals rounds to the left of the decimal point
<syntaxhighlight lang="c++">
let v1 = round(123456.789,  0); // "123457"
let v2 = round(123456.789, -1); // "123460"
let v3 = round(123456.789, -2); // "123500"</syntaxhighlight>
|-
|var=||var().chr(num)||Get a char given an integer 0-255.
<em>Returns:</em> A string containing a single char
0-127 -> ASCII, 128-255 -> invalid UTF-8 which cannot be written to the database or used in many exodus string operations
<syntaxhighlight lang="c++">
let v1 = var().chr(0x61); // "a"
// or
let v2 = chr(0x61);</syntaxhighlight>
|-
|var=||var().textchr(num)||Get a Unicode character given a Unicode Code Point (Number)
<em>Returns:</em> A single Unicode character in UTF8 encoding.
To get UTF code points > 2^63 you must provide negative ints because var doesnt provide an implicit constructor to unsigned int due to getting ambigious conversions because int and unsigned int are parallel priority in c++ implicit conversions.
<syntaxhighlight lang="c++">
let v1 = var().textchr(171416); // "𩶘" // or "\xF0A9B698"
// or
let v2 = textchr(171416);</syntaxhighlight>
|-
|var=||var().str(num)||Get a string of repeated substrings.
<em>var:</em> The substring to be repeated
<em>num:</em> How many times to repeat the substring
<em>Returns:</em> A string
<syntaxhighlight lang="c++">
let v1 = "ab"_var.str(3); // "ababab"
// or
let v2 = str("ab", 3);</syntaxhighlight>
|-
|var=||varnum.space()||Get a string containing a given number of spaces.
<em>var:</em> The number of spaces required.
<em>Returns:</em> A string of space chars.
<syntaxhighlight lang="c++">
let v1 = var(3).space(); // "␣␣␣"
// or
let v2 = space(3);</syntaxhighlight>
|-
|var=||varnum.numberinwords(languagename_or_locale_id = "")||Returns: A string representing a given number written in words instead of digits.
<em>locale:</em> Something like en_GB, ar_AE, el_CY, es_US, fr_FR etc.
<syntaxhighlight lang="c++">
let softhyphen = "\xc2\xad";
let v1 = var(123.45).numberinwords("de_DE").replace(softhyphen, " "); // "ein␣hundert␣drei␣und␣zwanzig␣Komma␣vier␣fünf"</syntaxhighlight>
|}
===== String Scanning =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|var=||strvar.at(pos1)||Get a single char from a string.
<em>pos1:</em> First char is 1. Last char is -1.
<em>Returns:</em> A single char if pos1 ± the length of the string, or "" if greater. Returns the first char if pos1 is 0 or (-pos1) > length.
<syntaxhighlight lang="c++">
var v1 = "abc";
var v2 = v1.at(2);  // "b"
var v3 = v1.at(-3); // "a"
var v4 = v1.at(4);  // ""</syntaxhighlight>
|-
|var=||strvar.seq()||Get the char number of a char
<em>Returns:</em> A number between 0 and 255.
If given a string, then only the first char is considered.
<syntaxhighlight lang="c++">
let v1 = "abc"_var.seq(); // 0x61 // decimal 97, 'a'
// or
let v2 = seq("abc");</syntaxhighlight>
|-
|var=||strvar.textseq()||Get the Unicode Code Point of a Unicode character.
<em>var:</em> A UTF-8 string. Only the first Unicode character is considered.
<em>Returns:</em> A number.
<syntaxhighlight lang="c++">
let v1 = "Γ"_var.textseq(); // 915 // U+0393: Greek Capital Letter Gamma (Unicode character)
// or
let v2 = textseq("Γ");</syntaxhighlight>
|-
|var=||strvar.len()||Get the length of a source string in number of chars
<em>Returns:</em> A number
<syntaxhighlight lang="c++">
let v1 = "abc"_var.len(); // 3
// or
let v2 = len("abc");</syntaxhighlight>
|-
|if||strvar.empty()||Checks if the var is an empty string.
<em>Returns:</em> True if it is empty amd false if not.
This is a shorthand and more expressive way of writing 'if (var == "")' or 'if (var.len() == 0)' or 'if (not var.len())'
Note that 'if (var.empty())' is not the same as 'if (not var)' because 'if (var("0.0")' is defined as false because the string can be converted to a 0 which is always considered to be false. Compare thia with common scripting languages where 'if (var("0"))' is defined as true.
<syntaxhighlight lang="c++">
let v1 = "0";
if (not v1.empty()) ... ok /// true
// or
if (not empty(v1)) ... ok // true</syntaxhighlight>
|-
|var=||strvar.textwidth()||Count the number of output columns required for a given source string.
<em>Returns:</em> A number
Allows wide multi-column Unicode characters that occupy more than one space in a text file or terminal screen.
Reduces combining characters to a single column. e.g. "e" followed by grave accent is multiple bytes but only occupies one output column.
Does not properly calculate all possible combining sequences of graphemes e.g. face followed by colour
<syntaxhighlight lang="c++">
let v1 = "🤡x🤡"_var.textwidth(); // 5
// or
let v2 = textwidth("🤡x🤡");</syntaxhighlight>
|-
|var=||strvar.textlen()||Count the number of Unicode code points in a source string.
<em>Returns:</em> A number.
<syntaxhighlight lang="c++">
let v1 = "Γιάννης"_var.textlen(); // 7
// or
let v2 = textlen("Γιάννης");</syntaxhighlight>
|-
|var=||strvar.fcount(sepstr)||Count the number of fields in a source string.
<em>sepstr:</em> The separator character or substr that delimits individual fields.
<em>Returns:</em> The count of the number of fields
This is similar to "var.count(sepstr) + 1" but it returns 0 for an empty source string.
<syntaxhighlight lang="c++">
let v1 = "aa**cc"_var.fcount("*"); // 3
// or
let v2 = fcount("aa**cc", "*");</syntaxhighlight>
|-
|var=||strvar.count(sepstr)||Count the number of occurrences of a given substr in a source string.
<em>substr:</em> The substr to count.
<em>Returns:</em> The count of the number of sepstr found.
Overlapping substrings are not counted.
<syntaxhighlight lang="c++">
let v1 = "aa**cc"_var.count("*"); // 2
// or
let v2 = count("aa**cc", "*");</syntaxhighlight>
|-
|if||strvar.starts(prefix)||Checks if a source string starts with a given prefix (substr).
<em>prefix:</em> The substr to check for.
<em>Returns:</em> True if the source string starts with the given prefix.
<em>Returns:</em> False if prefix is "". DIFFERS from c++, javascript, python3. See contains() for more info.
<syntaxhighlight lang="c++">
if ("abc"_var.starts("ab")) ... true
// or
if (starts("abc", "ab")) ... true</syntaxhighlight>
|-
|if||strvar.ends(suffix)||Checks if a source string ends with a given suffix (substr).
<em>suffix:</em> The substr to check for.
<em>Returns:</em> True if the source string ends with given suffix.
<em>Returns:</em> False if suffix is "". DIFFERS from c++, javascript, python3. See contains() for more info.
<syntaxhighlight lang="c++">
if ("abc"_var.ends("bc")) ... true
// or
if (ends("abc", "bc")) ... true</syntaxhighlight>
|-
|if||strvar.contains(substr)||Checks if a given substr exists in a source string.
<em>substr:</em> The substr to check for.
<em>Returns:</em> True if the source string starts with, ends with or contains the given substr.
<em>Returns:</em> False if suffix is "". DIFFERS from c++, javascript, python3
Human logic: "" is not equal to "x" therefore x does not contain "".
Human logic: Check each item (character) in the list for equality with what I am looking for and return success if any are equal.
Programmer logic: Compare as many characters as are in the search string for presence in the list of characters and return success if there are no failures.
<syntaxhighlight lang="c++">
if ("abcd"_var.contains("bc")) ... true
// or
if (contains("abcd", "bc")) ... true</syntaxhighlight>
|-
|var=||strvar.index(substr, startchar1 = 1)||Find a substr in a source string.
<em>substr:</em> The substr to search for.
<em>startchar1:</em> The char position (1 based) to start the search at. The default is 1, the first char.
<em>Returns:</em> The char position (1 based) that the substr is found at or 0 if not present.
<syntaxhighlight lang="c++">
let v1 = "abcd"_var.index("bc"); // 2
// or
let v2 = index("abcd", "bc");</syntaxhighlight>
|-
|var=||strvar.indexn(substr, occurrence)||Find the nth occurrence of a substr in a source string.
<em>substr:</em> The string to search for.
<em>Returns:</em> char position (1 based) or 0 if not present.
<syntaxhighlight lang="c++">
let v1 = "abcabc"_var.index("bc", 2); // 2
// or
let v2 = index("abcabc", "bc", 2);</syntaxhighlight>
|-
|var=||strvar.indexr(substr, startchar1 = -1)||Find the position of substr working backwards from the end of the string towards the beginning.
<em>substr:</em> The string to search for.
<em>Returns:</em> The char position of the substr if found, or 0 if not.
<em>startchar1:</em> defaults to -1 meaning start searching from the last char. Positive start1char1 counts from the beginning of the source string and negative startchar1 counts backwards from the last char.
<syntaxhighlight lang="c++">
let v1 = "abcabc"_var.indexr("bc"); // 5
// or
let v2 = indexr("abcabc", "bc");</syntaxhighlight>
|-
|var=||strvar.match(regex_str, regex_options = "")||Finds all matches of a given regular expression.
<em>Returns:</em> Zero or more matching substrings separated by FMs. Any groups are in VMs.
<syntaxhighlight lang="c++">
let v1 = "abc1abc2"_var.match("BC(\\d)", "i"); // "bc1]1^bc2]2"_var
// or
let v2 = match("abc1abc2", "BC(\\d)", "i");</syntaxhighlight>
<em>regex_options:</em>
<pre>
l - Literal (any regex chars are treated as normal chars)
i - Case insensitive
p - ECMAScript/Perl (the default)
b - Basic POSIX (same as sed)
e - Extended POSIX
a - awk
g - grep
eg - egrep or grep -E
char ranges like a-z are locale sensitive if ECMAScript
m - Multiline. Default in boost (and therefore exodus)
s - Single line. Default in std::regex
f - First only. Only for replace() (not match() or search())
w - Wildcard glob style (e.g. *.cfg) not regex style. Only for match() and search(). Not replace().
</pre>
|-
|var=||strvar.match(regex)||Ditto
|-
|var=||strvar.search(regex_str, io startchar1, regex_options = "")||Search for the first match of a regular expression.
<em>startchar1:</em> [in] char position to start the search from
<em>startchar1:</em> [out] char position to start the next search from
<em>Returns:</em> The 1st match like match()
regex_options as for match()
<syntaxhighlight lang="c++">
var startchar1 = 1;
let v1 = "abc1abc2"_var.search("BC(\\d)", startchar1, "i"); // "bc1]1"_var // startchar1 -> 5 /// Ready for the next search
// or
startchar1 = 1;
let v2 = search("abc1abc2", "BC(\\d)", startchar1, "i");</syntaxhighlight>
|-
|var=||strvar.search(regex_str)||Ditto starting from first char
|-
|var=||strvar.search(regex, io startchar1)||Ditto given a rex
|-
|var=||strvar.search(regex)||Ditto starting from first char.
|-
|var=||strvar.hash(std::uint64_t modulus = 0)||Get a hash of a source string.
<em>modulus:</em> The result is limited to [0, modulus)
<em>Returns:</em> A 64 bit signed integer.
MurmurHash3 is used.
<syntaxhighlight lang="c++">
let v1 = "abc"_var.hash(); assert(v1 == var(6'715'211'243'465'481'821));
// or
let v2 = hash("abc");</syntaxhighlight>
|}
===== String Conversion - Non-Mutating - Chainable =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|var=||strvar.ucase()||Convert to upper case
<syntaxhighlight lang="c++">
let v1 = "Γιάννης"_var.ucase(); // "ΓΙΆΝΝΗΣ"
// or
let v2 = ucase("Γιάννης");</syntaxhighlight>
|-
|var=||strvar.lcase()||Convert to lower case
<syntaxhighlight lang="c++">
let v1 = "ΓΙΆΝΝΗΣ"_var.lcase(); // "γιάννης"
// or
let v2 = lcase("ΓΙΆΝΝΗΣ");</syntaxhighlight>
|-
|var=||strvar.tcase()||Convert to title case.
<em>Returns:</em> Original source string with the first letter of each word is capitalised.
<syntaxhighlight lang="c++">
let v1 = "γιάννης παππάς"_var.tcase(); // "Γιάννης Παππάς"
// or
let v2 = tcase("γιάννης παππάς");</syntaxhighlight>
|-
|var=||strvar.fcase()||Convert to folded case.
Returns the source string standardised in a way to enable consistent indexing and searching,
Case folding is the process of converting text to a case independent representation.
https://www.w3.org/International/wiki/Case_folding
Accents can be significant. As in French cote, coté, côte and côté.
Case folding is not locale-dependent.
<syntaxhighlight lang="c++">
let v1 = "Grüßen"_var.fcase(); // "grüssen"
// or
let v2 = tcase("Grüßen");</syntaxhighlight>
|-
|var=||strvar.normalize()||Replace Unicode character sequences with their standardised NFC form.
Unicode normalization is the process of converting Unicode strings to a standard form, making them binary comparable and suitable for text processing and comparison. It is an important part of Unicode text processing.
For example, Unicode character "é" can be represented by either a single Unicode character, which is Unicode Code Point (\u00E9" - Latin Small Letter E with Acute), or a combination of two Unicode code points i.e. the ASCII letter "e" and a combining acute accent (Unicode Code Point "\u0301"). Unicode NFC definition converts the pair of code points to the single code point.
Normalization is not locale-dependent.
<syntaxhighlight lang="c++">
let v1 = "cafe\u0301"_var.normalize(); // "caf\u00E9" // "café"
// or
let v2 = normalize("cafe\u0301");</syntaxhighlight>
|-
|var=||strvar.invert()||Simple reversible disguising of string text.
It works by treating the string as UTF8 encoded Unicode code points and inverting the first 8 bits of their Unicode Code Points.
<em>Returns:</em> A string.
invert(invert()) returns to the original text.
ASCII bytes become multibyte UTF-8 so string sizes increase.
Inverted characters remain on their original Unicode Code Page but are jumbled up.
Non-existant Unicode Code Points may be created but UTF8 encoding remains valid.
<syntaxhighlight lang="c++">
let v1 = "abc"_var.invert(); // "\xC2" "\x9E" "\xC2" "\x9D" "\xC2" "\x9C"
// or
let v2 = invert("abc");</syntaxhighlight>
|-
|var=||strvar.lower()||Reduce all types of field mark chars by one level.
Convert all FM to VM, VM to SM etc.
<em>Returns:</em> The converted string.
Note that subtext ST chars are not converted because they are already the lowest level.
String size remains identical.
<syntaxhighlight lang="c++">
let v1 = "a1^b2^c3"_var.lower(); // "a1]b2]c3"_var
// or
let v2 = lower("a1^b2^c3"_var);</syntaxhighlight>
|-
|var=||strvar.raise()||Increase all types of field mark chars by one level.
Convert all VM to FM, SM to VM etc.
<em>Returns:</em> The converted string.
The record mark char RM is not converted because it is already the highest level.
String size remains identical.
<syntaxhighlight lang="c++">
let v1 = "a1]b2]c3"_var.raise(); // "a1^b2^c3"_var
// or
let v2 = "a1]b2]c3"_var;</syntaxhighlight>
|-
|var=||strvar.crop()||Remove any redundant FM, VM etc. chars (Trailing FM; VM before FM etc.)
<syntaxhighlight lang="c++">
let v1 = "a1^b2]]^c3^^"_var.crop(); // "a1^b2^c3"_var
// or
let v2 = crop("a1^b2]]^c3^^"_var);</syntaxhighlight>
|-
|var=||strvar.quote()||Wrap in double quotes.
<syntaxhighlight lang="c++">
let v1 = "abc"_var.quote(); // "\"abc\""
// or
let v2 = quote("abc");</syntaxhighlight>
|-
|var=||strvar.squote()||Wrap in single quotes.
<syntaxhighlight lang="c++">
let v1 = "abc"_var.squote(); // "'abc'"
// or
let v2 = squote("abc");</syntaxhighlight>
|-
|var=||strvar.unquote()||Remove one pair of surrounding double or single quotes.
<syntaxhighlight lang="c++">
let v1 = "'abc'"_var.unquote(); // "abc"
// or
let v2 = unquote("'abc'");</syntaxhighlight>
|-
|var=||strvar.trim(trimchars = " ")||Remove all leading, trailing and excessive inner bytes.
<em>trimchars:</em> The chars (bytes) to remove. The default is space.
<syntaxhighlight lang="c++">
let v1 = "␣␣a1␣␣b2␣c3␣␣"_var.trim(); // "a1␣b2␣c3"
// or
let v2 = trim("␣␣a1␣␣b2␣c3␣␣");</syntaxhighlight>
|-
|var=||strvar.trimfirst(trimchars = " ")||Ditto but only leading.
<syntaxhighlight lang="c++">
let v1 = "␣␣a1␣␣b2␣c3␣␣"_var.trimfirst(); // "a1␣␣b2␣c3␣␣"
// or
let v2 = trimfirst("␣␣a1␣␣b2␣c3␣␣");</syntaxhighlight>
|-
|var=||strvar.trimlast(trimchars = " ")||Ditto but only trailing.
<syntaxhighlight lang="c++">
let v1 = "␣␣a1␣␣b2␣c3␣␣"_var.trimlast(); // "␣␣a1␣␣b2␣c3"
// or
let v2 = trimlast("␣␣a1␣␣b2␣c3␣␣");</syntaxhighlight>
|-
|var=||strvar.trimboth(trimchars = " ")||Ditto but only leading and trailing, not inner.
<syntaxhighlight lang="c++">
let v1 = "␣␣a1␣␣b2␣c3␣␣"_var.trimboth(); // "a1␣␣b2␣c3"
// or
let v2 = trimboth("␣␣a1␣␣b2␣c3␣␣");</syntaxhighlight>
|-
|var=||strvar.first()||Get the first char of a string.
<em>Returns:</em> A char, or "" if empty.
Equivalent to var.substr(1,length) or var[1, length] in Pick OS
<syntaxhighlight lang="c++">
let v1 = "abc"_var.first(); // "a"
// or
let v2 = first("abc");</syntaxhighlight>
|-
|var=||strvar.last()||Get the last char of a string.
<em>Returns:</em> A char, or "" if empty.
Equivalent to var.substr(-1, 1) or var[-1, 1] in Pick OS
<syntaxhighlight lang="c++">
let v1 = "abc"_var.last(); // "c"
// or
let v2 = last("abc");</syntaxhighlight>
|-
|var=||strvar.first(std::size_t length)||Get the first n chars of a source string.
<em>length:</em> The number of chars (bytes) to get.
<em>Returns:</em> A string of up to n chars.
Equivalent to var.substr(1, length) or var[1, length] in Pick OS
<syntaxhighlight lang="c++">
let v1 = "abc"_var.first(2); // "ab"
// or
let v2 = first("abc", 2);</syntaxhighlight>
|-
|var=||strvar.last(std::size_t length)||Extract up to length trailing chars
Equivalent to var.substr(-length, length) or var[-length, length] in Pick OS
<syntaxhighlight lang="c++">
let v1 = "abc"_var.last(2); // "bc"
// or
let v2 = last("abc", 2);</syntaxhighlight>
|-
|var=||strvar.cut(length)||Remove n chars (bytes) from the source string.
<em>length:</em> Positive to remove first n chars or negative to remove the last n chars.
If the absolute value of length is >= the number of chars in the source string then all chars will be removed.
Equivalent to var.substr(length) or var[1, length] = "" in Pick OS
<syntaxhighlight lang="c++">
let v1 = "abcd"_var.cut(2); // "cd"
// or
let v2 = cut("abcd", 2);</syntaxhighlight>
|-
|var=||strvar.paste(pos1, length, insertstr)||Insert a substr at an given position after removing a given number of chars.
<em>pos1:</em> 0 or 1 : Remove length chars from the beginning and insert at the beginning.
<em>pos1:</em> > than the length of the source string. Insert after the last char.
<em>pos1:</em> -1 : Remove up to length chars before inserting.Insert on or before the last char.
<em>pos1:</em> -2 : Insert on or before the penultimate char.
Equivalent to var[pos1, length] = substr in Pick OS
<syntaxhighlight lang="c++">
let v1 = "abcd"_var.paste(2, 2, "XYZ"); // "aXYZd"
// or
let v2 = paste("abcd", 2, 2, "XYZ");</syntaxhighlight>
|-
|var=||strvar.paste(pos1, insertstr)||Insert text at char position without overwriting any following chars
Equivalent to var[pos1, 0] = substr in Pick OS
<syntaxhighlight lang="c++">
let v1 = "abcd"_var.paste(2, "XYZ"); // "aXYZbcd"
// or
let v2 = paste("abcd", 2, "XYZ");</syntaxhighlight>
|-
|var=||strvar.prefix(insertstr)||Insert text at the beginning
Equivalent to var[0, 0] = substr in Pick OS
<syntaxhighlight lang="c++">
let v1 = "abc"_var.prefix("XYZ"); // "XYZabc"
// or
let v2 = prefix("abc", "XYZ");</syntaxhighlight>
|-
|var=||strvar.append(appendable, ...)||Append anything at the end of a string
<syntaxhighlight lang="c++">
let v1 = "abc"_var.append(" is ", 10, " ok", '.'); // "abc is 10 ok."
// or
let v2 = append("abc", " is ", 10, " ok", '.');</syntaxhighlight>
|-
|var=||strvar.pop()||Remove one trailing char.
Equivalent to var[-1, 1] = "" in Pick OS
<syntaxhighlight lang="c++">
let v1 = "abc"_var.pop(); // "ab"
// or
let v2 = pop("abc");</syntaxhighlight>
|-
|var=||strvar.field(delimiter, fieldnx = 1, nfieldsx = 1)||Copies one or more consecutive fields from a string given a delimiter
<em>delimiter:</em> A Unicode character.
<em>fieldno:</em> The first field is 1, the last field is -1.
<em>Returns:</em> A substring
<syntaxhighlight lang="c++">
let v1 = "aa*bb*cc"_var.field("*", 2); // "bb"
// or
let v2 = field("aa*bb*cc", "*", 2);</syntaxhighlight>
<syntaxhighlight lang="c++">
let v1 = "aa*bb*cc"_var.field("*", -1); // "cc"
// or
let v2 = field("aa*bb*cc", "*", -1);</syntaxhighlight>
|-
|var=||strvar.fieldstore(separator, fieldno, nfields, replacement)||fieldstore() replaces, inserts or deletes subfields in a string.
<em>fieldno:</em> The field number to replace or, if not 1, the field number to start at. Negative fieldno counts backwards from the last field.
<em>nfields:</em> The number of fields to replace or, if negative, the number of fields to delete first. Can be 0 to cause simple insertion of fields.
<em>replacement:</em> A string that is the replacement field or fields.
<em>Returns:</em> A modified copy of the original string.
There is no way to simply delete n fields because the replacement argument cannot be omitted, however one can achieve the same result by replacing n+1 fields with the n+1th field.
The replacement can contain multiple fields itself. If replacing n fields and the replacement contains < n fields then the remaining fields become "", and if the replacement contains more fields than are required, they are unused.
<syntaxhighlight lang="c++">
let v1 = "aa,bb,cc,dd,ee"_var.fieldstore(",", 2, 3, "11,22"); // "aa,11,22,,ee"
// or
let v2 = fieldstore("aa,bb,cc,dd,ee", ",", 2, 3, "11,22");</syntaxhighlight>
If nfields is 0 then insert the replacement field(s) before fieldno
<syntaxhighlight lang="c++">
let v1 = "aa,bb,cc,dd,ee"_var.fieldstore(",", 2, 0, "11,22"); // "aa,11,22,bb,cc,dd,ee"</syntaxhighlight>
If nfields is negative then delete abs(n) fields before inserting whatever fields the replacement has.
<syntaxhighlight lang="c++">
let v1 = "aa,bb,cc,dd,ee"_var.fieldstore(",", 2, -2, "11"); // "aa,11,dd,ee"</syntaxhighlight>
If nfields exceeds the number of fields in the input then additional empty fields are added.
<syntaxhighlight lang="c++">
let v1 = "aa,bb,cc"_var.fieldstore(",", 6, 2, "11"); // "aa,bb,cc,,,11,"</syntaxhighlight>
|-
|var=||strvar.substr(pos1, length)||substr version 1.
Copies a substr of length chars from a given a starting char position.
<em>Returns:</em> A substr or "".
<em>pos1:</em> The char position to start at. If negative then start from a position counting backwards from the last char
<em>length:</em> The number of chars to copy. If negative then copy backwards. This reverses the order of the chars in the returned substr.
Equivalent to var[start, length] in Pick OS
Not Unicode friendly.
<syntaxhighlight lang="c++">
let v1 = "abcd"_var.substr(2, 2); // "bc"
// or
let v2 = substr("abcd", 2, 2);</syntaxhighlight>
If pos1 is negative then start counting backwards from the last char
<syntaxhighlight lang="c++">
let v1 = "abcd"_var.substr(-3, 2); // "bc"
// or
let v2 = substr("abcd", -3, 2);</syntaxhighlight>
If length is negative then work backwards and return chars reversed
<syntaxhighlight lang="c++">
let v1 = "abcd"_var.substr(3, -2); // "cb"
// or
let v2 = substr("abcd", 3, -2); // "cb"</syntaxhighlight>
|-
|var=||strvar.b(pos1, length)||Abbreviated alias of substr version 1.
|-
|var=||strvar.substr(pos1)||substr version 2.
Copies a substr from a given char position up to the end of the source string
<em>Returns:</em> A substr or "".
<em>pos1:</em> The char position to start at. If negative then start from a position counting backwards from the last char
Equivalent to var[pos1, 9999999] in Pick OS
Partially Unicode friendly but pos1 is in chars.
<syntaxhighlight lang="c++">
let v1 = "abcd"_var.substr(2); // "bcd"
// or
let v2 = substr("abcd", 2);</syntaxhighlight>
|-
|var=||strvar.b(pos1)||Shorthand alias of substr version 2.
|-
|var=||strvar.substr(pos1, delimiterchars, out pos2)||substr version 3.
Copies a substr from a given char position up to (but excluding) any one of some given delimiter chars
<em>Returns:</em> A substr or "".
<em>pos1:</em> [in] The position of the first char to copy. Negative positions count backwards from the last char of the string.
<em>pos2:</em> [out] The position of the next delimiter char, or one char position after the end of the source string if no subsequent delimiter chars are found.
<em>COL2:</em> is a predefined variable that can be used for pos2 instead of declaring a variable.
An empty string may be returned if pos1 [in] points to one of the delimiter chars or points beyond the end of the source string.
Equivalent to var[pos1, ",."] in Pick OS (non-numeric length).
Works with any encoding including UTF8 for the source string but the delimiter chars are bytes.
Add 1 to pos2 to skip over the next delimiter char to copy the next substr
Works with any encoding including UTF8 for the source string but the delimiter chars are bytes.
This function is similar to std::string::find_first_of but that function only returns pos2.
<syntaxhighlight lang="c++">
var pos1 = 4;
let v1 = "12,45 78"_var.substr(pos1, ", ", COL2);  // v1 -> "45" // COL2 -> 6 // 6 is the position of the next delimiter char found.
// or
let v2 = substr("12,45 78", COL2 + 1, ", ", COL2); // v2 -> "78" // COL2 -> 9 // 9 is one after the end of the string meaning that none of the delimiter chars were found.</syntaxhighlight>
|-
|var=||strvar.b(pos1, delimiterchars, out pos2)||Shorthand alias of substr version 3.
|-
|var=||strvar.substr2(io pos1, out delimiterno)||substr version 4.
Copies a substr from a given char position up to (but excluding) the next field mark char (RM, FM, VM, SM, TM, ST).
<em>Returns:</em> A substr or "".
<em>pos1:</em> [in] The position of the first char to copy. Negative positions count backwards from the last char of the string.
<em>pos1:</em> [out] The position of the first char of the next substr after whatever field mark char is found, or one char position after the end of the source string if no subsequent field mark char is found.
<em>field_mark_no:</em> [out] A number (1-6) indicating which of the standard field mark chars was found, or 0 if not.
An empty string may be returned if the pos1 [in] points to one of the field marks or beyond the end of the source string.
pos1 [out] is correctly positioned to copy the next substr.
Works with any encoding including UTF8. Was called "remove" in Pick OS.
The equivalent in Pick OS was the statement "Remove variable From string At column Setting flag"
...
This function is valuable for high performance processing of dynamic arrays.
It is notably used in "list" to print parallel columns of mixed combinations of multivalues/subvalues and text marks correctly lined up mv to mv, sv to sv, tm to tm even when particular values, subvalues and text fragments are missing from particular columns.
It is similar to version 3 of substr - substr(pos1, delimiterchars, pos2) except that in this version the delimiter chars are hard coded as the standard field mark chars (RM, FM, VM, SM, TM, ST) and it returns the first char position of the next substr, not the char position of the next field mark char.
<syntaxhighlight lang="c++">
var pos1 = 4, field_mark_no;
let v1 = "12^45^78"_var.substr2(pos1, field_mark_no);  // "45" // pos1 -> 7 // field_mark_no -> 2 // field_mark_no 2 means that a FM was found.
// or
let v2 = substr2("12^45^78"_var, pos1, field_mark_no); // "78" // pos1 -> 9 // field_mark_no -> 0 // field_mark_no 0 means that none of the standard field marks were found.</syntaxhighlight>
|-
|var=||strvar.b2(io pos1, out field_mark_no)||Shorthand alias of substr version 4.
|-
|var=||strvar.convert(from_chars, to_chars)||Convert or delete chars one for one to other chars
<em>from_chars:</em> chars to convert. If longer than to_chars then delete those characters instead of converting them.
<em>to_chars:</em> chars to convert to
Not UTF8 compatible.
<syntaxhighlight lang="c++">
let v1 = "abcde"_var.convert("aZd", "XY"); // "Xbce" // a is replaced and d is removed
// or
let v2 = convert("abcde", "aZd", "XY");</syntaxhighlight>
|-
|var=||strvar.textconvert(from_characters, to_characters)||Ditto for Unicode code points.
<syntaxhighlight lang="c++">
let v1 = "a🤡b😀c🌍d"_var.textconvert("🤡😀", "👋"); // "a👋bc🌍d"
// or
let v2 = textconvert("a🤡b😀c🌍d", "🤡😀", "👋");</syntaxhighlight>
|-
|var=||strvar.replace(fromstr, tostr)||Replace all occurrences of one substr with another.
Case sensitive.
<syntaxhighlight lang="c++">
let v1 = "Abc.Abc"_var.replace("bc", "X"); // "AX.AX"
// or
let v2 = replace("Abc Abc", "bc", "X");</syntaxhighlight>
|-
|var=||strvar.replace(regex, tostr)||Replace substring(s) using a regular expression.
Use $0, $1, $2 in tostr to refer to groups defined in the regex.
<syntaxhighlight lang="c++">
let v1 = "A a B b"_var.replace("[A-Z]"_rex, "'$0'"); // "'A' a 'B' b"
// or
let v2 = replace("A a B b", "[A-Z]"_rex, "'$0'");</syntaxhighlight>
|-
|var=||strvar.unique()||Remove duplicate fields in an FM or VM etc. separated list
<syntaxhighlight lang="c++">
let v1 = "a1^b2^a1^c2"_var.unique(); // "a1^b2^c2"_var
// or
let v2 = unique("a1^b2^a1^c2"_var);</syntaxhighlight>
|-
|var=||strvar.sort(delimiter = FM)||Reorder fields in an FM or VM etc. separated list in ascending order
Numeric data:
<syntaxhighlight lang="c++">
let v1 = "20^10^2^1^1.1"_var.sort(); // "1^1.1^2^10^20"_var
// or
let v2 = sort("20^10^2^1^1.1"_var);</syntaxhighlight>
Alphabetic data:
<syntaxhighlight lang="c++">
let v1 = "b1^a1^c20^c10^c2^c1^b2"_var.sort(); // "a1^b1^b2^c1^c10^c2^c20"_var
// or
let v2 = sort("b1^a1^c20^c10^c2^c1^b2"_var);</syntaxhighlight>
|-
|var=||strvar.reverse(delimiter = FM)||Reorder fields in an FM or VM etc. separated list in descending order
<syntaxhighlight lang="c++">
let v1 = "20^10^2^1^1.1"_var.reverse(); // "1.1^1^2^10^20"_var
// or
let v2 = reverse("20^10^2^1^1.1"_var);</syntaxhighlight>
|-
|var=||strvar.shuffle(delimiter = FM)||Randomise the order of fields in an FM, VM separated list
<syntaxhighlight lang="c++">
let v1 = "20^10^2^1^1.1"_var.shuffle(); /// e.g. "2^1^20^1.1^10" (random order depending on initrand())
// or
let v2 = shuffle("20^10^2^1^1.1"_var);</syntaxhighlight>
|-
|var=||strvar.parse(char sepchar = ' ')||Split a delimited string with embedded quotes into a dynamic array.
Can be used to process CSV data.
Replaces separator chars with FM chars except inside double or single quotes and ignoring escaped quotes &bsol;" &bsol;'
<syntaxhighlight lang="c++">
let v1 = "abc,\"def,\"123\" fgh\",12.34"_var.parse(','); // "abc^\"def,\"123\" fgh\"^12.34"_var
// or
let v2 = parse("abc,\"def,\"123\" fgh\",12.34", ',');</syntaxhighlight>
|-
|dim||strvar.split(delimiter = FM)||Split a delimited string into a dim array.
The delimiter can be multibyte Unicode.
<syntaxhighlight lang="c++">
dim d1 = "a^b^c"_var.split(); // A dimensioned array with three elements (vars)
// or
dim d2 = split("a^b^c"_var);</syntaxhighlight>
|}
===== String Mutation - Standalone Commands =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|cmd||strvar.ucaser()||Upper case
All string mutators follow the same pattern as ucaser.<br>See the non-mutating functions for details.
<syntaxhighlight lang="c++">
var v1 = "abc";
v1.ucaser(); // "ABC"
// or
ucaser(v1);</syntaxhighlight>
|-
|cmd||strvar.lcaser()||
|-
|cmd||strvar.tcaser()||
|-
|cmd||strvar.fcaser()||
|-
|cmd||strvar.normalizer()||
|-
|cmd||strvar.inverter()||
|-
|cmd||strvar.quoter()||
|-
|cmd||strvar.squoter()||
|-
|cmd||strvar.unquoter()||
|-
|cmd||strvar.lowerer()||
|-
|cmd||strvar.raiser()||
|-
|cmd||strvar.cropper()||
|-
|cmd||strvar.trimmer(trimchars = " ")||
|-
|cmd||strvar.trimmerfirst(trimchars = " ")||
|-
|cmd||strvar.trimmerlast(trimchars = " ")||
|-
|cmd||strvar.trimmerboth(trimchars = " ")||
|-
|cmd||strvar.firster()||
|-
|cmd||strvar.laster()||
|-
|cmd||strvar.firster(std::size_t length)||
|-
|cmd||strvar.laster(std::size_t length)||
|-
|cmd||strvar.cutter(length)||
|-
|cmd||strvar.paster(pos1, length, insertstr)||
|-
|cmd||strvar.paster(pos1, insertstr)||
|-
|cmd||strvar.prefixer(insertstr)||
|-
|cmd||strvar.appender(appendable, ...)||
|-
|cmd||strvar.popper()||
|-
|cmd||strvar.fieldstorer(delimiter, fieldno, nfields, replacement)||
|-
|cmd||strvar.substrer(pos1, length)||
|-
|cmd||strvar.substrer(pos1)||
|-
|cmd||strvar.converter(from_chars, to_chars)||
|-
|cmd||strvar.textconverter(from_characters, to_characters)||
|-
|cmd||strvar.replacer(regex, tostr)||
|-
|cmd||strvar.replacer(fromstr, tostr)||
|-
|cmd||strvar.uniquer()||
|-
|cmd||strvar.sorter(delimiter = FM)||
|-
|cmd||strvar.reverser(delimiter = FM)||
|-
|cmd||strvar.shuffler(delimiter = FM)||
|-
|cmd||strvar.parser(char sepchar = ' ')||
|}
===== I/O Conversion =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|var=||var.oconv(convstr)||Converts internal data to output external display format according to a given conversion code or pattern
If the internal data is invalid and cannot be converted then most conversions return the ORIGINAL data unconverted
Throws a runtime error VarNotImplemented if convstr is invalid
See [[#ICONV/OCONV PATTERNS]]
<syntaxhighlight lang="c++">
let v1 = var(30123).oconv("D/E"); // "21/06/2050"
// or
let v2 = oconv(30123, "D/E");</syntaxhighlight>
|-
|var=||var.iconv(convstr)||Converts external data to internal format according to a given conversion code or pattern
If the external data is invalid and cannot be converted then most conversions return the EMPTY STRING ""
Throws a runtime error VarNotImplemented if convstr is invalid
See [[#ICONV/OCONV PATTERNS]]
<syntaxhighlight lang="c++">
let v1 = "21 JUN 2050"_var.iconv("D/E"); // 30123
// or
let v2 = iconv("21 JUN 2050", "D/E");</syntaxhighlight>
|-
|var=||var.format(fmt_str, args, ...)||Classic format function in printf style
vars can be formatted either with C++ format codes e.g. {:_>8.2f}
or with exodus oconv codes e.g. {::MD20P|R(_)#8} as in the below example.
<syntaxhighlight lang="c++">
let v1 = var(12.345).format("'{:_>8.2f}'"); // "'___12.35'"
let v2 = var(12.345).format("'{::MD20P|R(_)#8}'");
// or
var v3 = format("'{:_>8.2f}'", var(12.345)); // "'___12.35'"
var v4 = format("'{::MD20P|R(_)#8}'", var(12.345));</syntaxhighlight>
|-
|var=||strvar.from_codepage(codepage)||Converts from codepage encoded text to UTF-8 encoded text
e.g. Codepage "CP1124" (Ukrainian).
Use Linux command "iconv -l" for complete list of code pages and encodings.
<syntaxhighlight lang="c++">
let v1 = "\xa4"_var.from_codepage("CP1124"); // "Є"
// or
let v2 = from_codepage("\xa4", "CP1124");
// U+0404 Cyrillic Capital Letter Ukrainian Ie Unicode character</syntaxhighlight>
|-
|var=||strvar.to_codepage(codepage)||Converts to codepage encoded text from UTF-8 encoded text
<syntaxhighlight lang="c++">
let v1 = "Є"_var.to_codepage("CP1124").oconv("HEX"); // "A4"
// or
let v2 = to_codepage("Є", "CP1124").oconv("HEX");</syntaxhighlight>
|}
===== Dynamic Array Functions =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|var=||strvar.f(fieldno, valueno = 0, subvalueno = 0)||f() is a highly abbreviated alias for the Pick OS field/value/subvalue extract() function.
"f()" can be thought of as "field" although the function can extract values and subvalues as well.
The convenient Pick OS angle bracket syntax for field extraction (e.g. xxx<20>) is not available in C++.
The abbreviated exodus field extraction function (e.g. xxx.f(20)) is provided instead since field access is extremely heavily used in source code.
<syntaxhighlight lang="c++">
let v1 = "f1^f2v1]f2v2]f2v3^f2"_var;
let v2 = v1.f(2, 2); // "f2v2"</syntaxhighlight>
|-
|var=||strvar.extract(fieldno, valueno = 0, subvalueno = 0)||Extract a specific field, value or subvalue from a dynamic array.
<syntaxhighlight lang="c++">
let v1 = "f1^f2v1]f2v2]f2v3^f2"_var;
let v2 = v1.extract(2, 2); // "f2v2"
//
// For brevity the function alias "f()" (standing for "field") is normally used instead of "extract()" as follows:
var v3 = v1.f(2, 2);</syntaxhighlight>
|-
|var=||strvar.pickreplace(fieldno, valueno, subvalueno, replacement)||Same as var.r() function but returns a new string instead of updating a variable in place.<br>Rarely used.
|-
|var=||strvar.pickreplace(fieldno, valueno, replacement)||Ditto for a specific multivalue
|-
|var=||strvar.pickreplace(fieldno, replacement)||Ditto for a specific field
|-
|var=||strvar.insert(fieldno, valueno, subvalueno, insertion)||Same as var.inserter() function but returns a new string instead of updating a variable in place.
|-
|var=||strvar.insert(fieldno, valueno, insertion)||Ditto for a specific multivalue
|-
|var=||strvar.insert(fieldno, insertion)||Ditto for a specific field
|-
|var=||strvar.remove(fieldno, valueno = 0, subvalueno = 0)||Same as var.remover() function but returns a new string instead of updating a variable in place.
"remove" was called "delete" in Pick OS.
|}
===== Dynamic Array Filters =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|var=||strvar.sum()||Sum up multiple values into one higher level
<syntaxhighlight lang="c++">
let v1 = "1]2]3^4]5]6"_var.sum(); // "6^15"_var
// or
let v2 = sum("1]2]3^4]5]6"_var);</syntaxhighlight>
|-
|var=||strvar.sumall()||Sum up all levels into a single figure
<syntaxhighlight lang="c++">
let v1 = "1]2]3^4]5]6"_var.sumall(); // 21
// or
let v2 = sumall("1]2]3^4]5]6"_var);</syntaxhighlight>
|-
|var=||strvar.sum(delimiter)||Ditto allowing commas etc.
<syntaxhighlight lang="c++">
let v1 = "10,20,30"_var.sum(","); // 60
// or
let v2 = sum("10,20,30", ",");</syntaxhighlight>
|-
|var=||strvar.mv(opcode, var2)||Binary ops (+, -, *, /) in parallel on multiple values
<syntaxhighlight lang="c++">
let v1 = "10]20]30"_var.mv("+","2]3]4"_var); // "12]23]34"_var</syntaxhighlight>
|}
===== Dynamic Array Mutators Standalone Commands =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|cmd||strvar.r(fieldno, replacement)||Replaces a specific field in a dynamic array
<syntaxhighlight lang="c++">
var v1 = "f1^v1]v2}s2}s3^f3"_var;
v1.r(2, "X"); // "f1^X^f3"_var</syntaxhighlight>
|-
|cmd||strvar.r(fieldno, valueno, replacement)||Ditto for specific value in a specific field.
<syntaxhighlight lang="c++">
var v1 = "f1^v1]v2}s2}s3^f3"_var;
v1.r(2, 2, "X"); // "f1^v1]X^f3"_var</syntaxhighlight>
|-
|cmd||strvar.r(fieldno, valueno, subvalueno, replacement)||Ditto for a specific subvalue in a specific value of a specific field
<syntaxhighlight lang="c++">
var v1 = "f1^v1]v2}s2}s3^f3"_var;
v1.r(2, 2, 2, "X"); // "f1^v1]v2}X}s3^f3"_var</syntaxhighlight>
|-
|cmd||strvar.inserter(fieldno, insertion)||Insert a specific field in a dynamic array, moving all other fields up.
<syntaxhighlight lang="c++">
var v1 = "f1^v1]v2}s2}s3^f3"_var;
v1.inserter(2, "X"); // "f1^X^v1]v2}s2}s3^f3"_var
// or
inserter(v1, 2, "X");</syntaxhighlight>
|-
|cmd||strvar.inserter(fieldno, valueno, insertion)||Ditto for a specific value in a specific field, moving all other values up.
<syntaxhighlight lang="c++">
var v1 = "f1^v1]v2}s2}s3^f3"_var;
v1.inserter(2, 2, "X"); // "f1^v1]X]v2}s2}s3^f3"_var
// or
inserter(v1, 2, 2, "X");</syntaxhighlight>
|-
|cmd||strvar.inserter(fieldno, valueno, subvalueno, insertion)||Ditto for a specific subvalue in a dynamic array, moving all other subvalues up.
<syntaxhighlight lang="c++">
var v1 = "f1^v1]v2}s2}s3^f3"_var;
v1.inserter(2, 2, 2, "X"); // "f1^v1]v2}X}s2}s3^f3"_var
// or
v1.inserter(2, 2, 2, "X");</syntaxhighlight>
|-
|cmd||strvar.remover(fieldno, valueno = 0, subvalueno = 0)||Remove a specific field (or value, or subvalue) from a dynamic array, moving all other fields (or values, or subvalues)  down.
<syntaxhighlight lang="c++">
var v1 = "f1^v1]v2}s2}s3^f3"_var;
v1.remover(2, 2); // "f1^v1^f3"_var
// or
remover(v1, 2, 2);</syntaxhighlight>
|}
===== Dynamic Array Search =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|var=||strvar.locate(target)||locate() with only the target substr argument provided searches unordered values separated by any of the field mark chars.
<em>Returns:</em> The field, value, subvalue etc. number if found or 0 if not.
Searching for empty fields, values etc. (i.e. "") will work. Locating "" in "]yy" will return 1, in "xx]]zz" 2, and in "xx]yy]" 3, however, locating "" in "xx" will return 0 because there is conceptually no empty value in "xx". Locate "" in "" will return 1.
<syntaxhighlight lang="c++">
if ("UK^US^UA"_var.locate("US")) ... ok // 2
// or
if (locate("US", "UK^US^UA"_var)) ... ok</syntaxhighlight>
|-
|if||strvar.locate(target, out valueno)||locate() with only the target substr provided and setting returned searches unordered values separated by any type of field mark chars.
<em>Returns:</em> True if found
<em>Setting:</em> Field, value, subvalue etc. number if found or the max number + 1 if not. Suitable for additiom of new values
<syntaxhighlight lang="c++">
var setting;
if ("UK]US]UA"_var.locate("US", setting)) ... ok // setting -> 2
// or
if (locate("US", "UK]US]UA"_var, setting)) ... ok</syntaxhighlight>
|-
|if||strvar.locate(target, out setting, fieldno, valueno = 0)||locate() the target in unordered fields if fieldno is 0, or values if a fieldno is specified, or subvalues if the valueno argument is provided.
<em>Returns:</em> True if found and with the field, value or subvalue number in setting.
<em>Returns:</em> False if not found and with the max field, value or subvalue number found + 1 in setting. Suitable for replacement of new fields, values or subvalues.
<syntaxhighlight lang="c++">
var setting;
if ("f1^f2v1]f2v2]s1}s2}s3}s4^f3^f4"_var.locate("s4", setting, 2, 3)) ... ok // setting -> 4 // returns true</syntaxhighlight>
|-
|if||strvar.locateby(ordercode, target, out valueno)||locateby() without fieldno or valueno arguments searches ordered values separated by VM chars.
The order code can be AL, DL, AR, DR meaning Ascending Left, Descending Right, Ascending Right, Ascending Left.
Left is used to indicate alphabetic order where 10 < 2.
Right is used to indicate numeric order where 10 > 2.
Data must be in the correct order for searching to work properly.
<em>Returns:</em> True if found.
In case the target is not exactly found then the correct value no for inserting the target is returned in setting.
<syntaxhighlight lang="c++">
var valueno; if ("aaa]bbb]ccc"_var.locateby("AL", "bb", valueno)) ... // valueno -> 2 // returns false and valueno = where it could be correctly inserted.</syntaxhighlight>
|-
|if||strvar.locateby(ordercode, target, out setting, fieldno, valueno = 0)||locateby() ordered as above but in fields if fieldno is 0, or values in a specific fieldno, or subvalues in a specific valueno.
<syntaxhighlight lang="c++">
var setting;
if ("f1^f2^aaa]bbb]ccc^f4"_var.locateby("AL", "bb", setting, 3)) ... // setting -> 2 // return false and where it could be correctly inserted.</syntaxhighlight>
|-
|if||strvar.locateusing(usingchar, target)||locate() a target substr in the whole unordered string using a given delimiter char returning true if found.
<syntaxhighlight lang="c++">
if ("AB,EF,CD"_var.locateusing(",", "EF")) ... ok</syntaxhighlight>
|-
|if||strvar.locateusing(usingchar, target, out setting, fieldno = 0, valueno = 0, subvalueno = 0)||locate() the target in a specific field, value or subvalue using a specified delimiter and unordered data
<em>Returns:</em> True If found and returns in setting the number of the delimited field found.
<em>Returns:</em> False if not found and returns in setting the maximum number of delimited fields + 1 if not found.
This is similar to the main locate command but the delimiter char can be specified e.g. a comma or TM etc.
<syntaxhighlight lang="c++">
var setting;
if ("f1^f2^f3c1,f3c2,f3c3^f4"_var.locateusing(",", "f3c2", setting, 3)) ... ok // setting -> 2 // returns true</syntaxhighlight>
|-
|if||strvar.locatebyusing(ordercode, usingchar, target, out setting, fieldno = 0, valueno = 0, subvalueno = 0)||locatebyusing() supports all the above features in a single function.
<em>Returns:</em> True if found.
|}
===== Database Access =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|if||conn.connect(conninfo = "")||For all db operations, the operative var can either be a db connection created with dbconnect() or be any var and a default connection will be established on the fly.
The db connection string (conninfo) parameters are merged from the following places in descending priority.
1. Provided in connect()'s conninfo argument. See 4. for the complete list of parameters.
2. Any environment variables EXO_HOST EXO_PORT EXO_USER EXO_DATA EXO_PASS EXO_TIME
3. Any parameters found in a configuration file at ~/.config/exodus/exodus.cfg
4. The default conninfo is "host=127.0.0.1 port=5432 dbname=exodus user=exodus password=somesillysecret connect_timeout=10"
Setting environment variable EXO_DBTRACE=1 will cause tracing of db interface including SQL commands.
<syntaxhighlight lang="c++">
let conninfo = "dbname=exodus user=exodus password=somesillysecret";
if (not conn.connect(conninfo)) ...;
// or
if (not connect()) ...
// or
if (not connect("exodus")) ...</syntaxhighlight>
|-
|if||conn.attach(filenames)||Attach (connect) specific files by name to specific connections.
It is not necessary to attach files before opening them. Attach is meant to control the defaults.
For the remainder of the session, opening the db file by name without specifying a connection will automatically use the specified connection applies during the attach command.
If conn is not specified then filename will be attached to the default connection.
Multiple file names must be separated by FM
<syntaxhighlight lang="c++">
let filenames = "xo_clients^dict.xo_clients"_var, conn = "exodus";
if (conn.attach(filenames)) ... ok
// or
if (attach(filenames)) ... ok</syntaxhighlight>
|-
|cmd||conn.detach(filenames)||Detach (disconnect) files that have been attached using attach().
|-
|if||conn.begintrans()||Begin a db transaction.
<syntaxhighlight lang="c++">
if (not conn.begintrans()) ...
// or
if (not begintrans()) ...</syntaxhighlight>
|-
|if||conn.statustrans()||Check if a db transaction is in progress.
<syntaxhighlight lang="c++">
if (conn.statustrans()) ... ok
// or
if (statustrans()) ... ok</syntaxhighlight>
|-
|if||conn.rollbacktrans()||Rollback a db transaction.
<syntaxhighlight lang="c++">
if (conn.rollbacktrans()) ... ok
// or
if (rollbacktrans()) ... ok</syntaxhighlight>
|-
|if||conn.committrans()||Commit a db transaction.
<em>Returns:</em> True if successfully committed or if there was no transaction in progress, otherwise false.
<syntaxhighlight lang="c++">
if (conn.committrans()) ... ok
// or
if (committrans()) ... ok</syntaxhighlight>
|-
|if||conn.sqlexec(sqlcmd)||Execute an sql command.
<em>Returns:</em> True if there was no sql error otherwise lasterror() returns a detailed error message.
<syntaxhighlight lang="c++">
if (conn.sqlexec("select 1")) ... ok
// or
if (sqlexec("select 1")) ... ok</syntaxhighlight>
|-
|if||conn.sqlexec(sqlcmd, io response)||Execute an SQL command and capture the response.
<em>Returns:</em> True if there was no sql error otherwise response contains a detailed error message.
<em>response:</em> Any rows and columns returned are separated by RM and FM respectively. The first row is the column names.
<em>Recommended:</em> Don't use sql directly unless you must to manage or configure a database.
<syntaxhighlight lang="c++">
let sqlcmd = "select 'xxx' as col1, 'yyy' as col2";
var response;
if (conn.sqlexec(sqlcmd, response)) ... ok // response -> "col1^col2\x1fxxx^yyy"_var /// \x1f is the Record Mark (RM) char. The backtick char is used here by gendoc to deliminate source code.
// or
if (sqlexec(sqlcmd, response)) ... ok</syntaxhighlight>
|-
|cmd||conn.disconnect()||Closes db connection and frees process resources both locally and in the database server.
<syntaxhighlight lang="c++">
conn.disconnect();
// or
disconnect();</syntaxhighlight>
|-
|cmd||conn.disconnectall()||Closes all connections and frees process resources both locally and in the database server(s).
All connections are closed automatically when a process terminates.
<syntaxhighlight lang="c++">
conn.disconnectall();
// or
disconnectall();</syntaxhighlight>
|-
|var=||conn.lasterror()||Returns: The last os or db error message.
<syntaxhighlight lang="c++">
var v1 = var().lasterror();
// or
var v2 = lasterror();</syntaxhighlight>
|-
|var=||conn.loglasterror(source = "")||Log the last os or db error message.
<em>Output:</em> to stdlog
Prefixes the output with source if provided.
<syntaxhighlight lang="c++">
var().loglasterror("main:");
// or
loglasterror("main:");</syntaxhighlight>
|}
===== Database Management =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|if||conn.dbcreate(new_dbname, old_dbname = "")||Create a named database on a particular connection.
The target database cannot already exist.
Optionally copies an existing database from the same connection and which cannot have any current connections.
<syntaxhighlight lang="c++">
var conn = "exodus";
if (not dbdelete("xo_gendoc_testdb")) {}; // Cleanup first
if (conn.dbcreate("xo_gendoc_testdb")) ... ok
// or
if (dbcreate("xo_gendoc_testdb")) ...</syntaxhighlight>
|-
|if||conn.dbcopy(from_dbname, to_dbname)||Create a named database as a copy of an existing database.
The target database cannot already exist.
The source database must exist on the same connection and cannot have any current connections.
<syntaxhighlight lang="c++">
var conn = "exodus";
if (not dbdelete("xo_gendoc_testdb2")) {}; // Cleanup first
if (conn.dbcopy("xo_gendoc_testdb", "xo_gendoc_testdb2")) ... ok
// or
if (dbcopy("xo_gendoc_testdb", "xo_gendoc_testdb2")) ...</syntaxhighlight>
|-
|var=||conn.dblist()||Returns: A list of available databases on a particular connection.
<syntaxhighlight lang="c++">
let v1 = conn.dblist();
// or
let v2 = dblist();</syntaxhighlight>
|-
|if||conn.dbdelete(dbname)||Delete (drop) a named database.
The target database must exist and cannot have any current connections.
<syntaxhighlight lang="c++">
var conn = "exodus";
if (conn.dbdelete("xo_gendoc_testdb2")) ... ok
// or
if (dbdelete("xo_gendoc_testdb2")) ...</syntaxhighlight>
|-
|if||conn.createfile(filename)||Create a named db file.
<syntaxhighlight lang="c++">
let filename = "xo_gendoc_temp", conn = "exodus";
if (conn.createfile(filename)) ... ok
// or
if (createfile(filename)) ...</syntaxhighlight>
|-
|if||conn.renamefile(filename, newfilename)||Rename a db file.
<syntaxhighlight lang="c++">
let conn = "exodus", filename = "xo_gendoc_temp", new_filename = "xo_gendoc_temp2";
if (conn.renamefile(filename, new_filename)) ... ok
// or
if (renamefile(filename, new_filename)) ...</syntaxhighlight>
|-
|var=||conn.listfiles()||Returns: A list of all files in a database
<syntaxhighlight lang="c++">
var conn = "exodus";
if (not conn.listfiles()) ...
// or
if (not listfiles()) ...</syntaxhighlight>
|-
|if||conn.clearfile(filename)||Delete all records in a db file
<syntaxhighlight lang="c++">
let conn = "exodus", filename = "xo_gendoc_temp2";
if (not conn.clearfile(filename)) ...
// or
if (not clearfile(filename)) ...</syntaxhighlight>
|-
|if||conn.deletefile(filename)||Delete a db file
<syntaxhighlight lang="c++">
let conn = "exodus", filename = "xo_gendoc_temp2";
if (conn.deletefile(filename)) ... ok
// or
if (deletefile(filename)) ...</syntaxhighlight>
|-
|var=||conn_or_file.reccount(filename = "")||Returns: The approx. number of records in a db file
<syntaxhighlight lang="c++">
let conn = "exodus", filename = "xo_clients";
var nrecs1 = conn.reccount(filename);
// or
var nrecs2 = reccount(filename);</syntaxhighlight>
|-
|if||conn_or_file.flushindex(filename = "")||Calls db maintenance function (vacuum)
This doesnt actually flush any indexes but does make sure that reccount() function is reasonably accurate.
|}
===== Database File I/O =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|if||file.open(dbfilename, connection = "")||Opens a db file to a var which can be used in subsequent functions to work on the specified file and database connection.
<syntaxhighlight lang="c++">
var file, filename = "xo_clients";
if (not file.open(filename)) ...
// or
if (not open(filename to file)) ...</syntaxhighlight>
|-
|cmd||file.close()||Closes db file var
Does nothing currently since database file vars consume no resources
<syntaxhighlight lang="c++">
var file = "xo_clients";
file.close();
// or
close(file);</syntaxhighlight>
|-
|if||file.createindex(fieldname, dictfile = "")||Creates a secondary index for a given db file and field name.
The fieldname must exist in a dictionary file. The default dictionary is "dict." ^ filename.
<em>Returns:</em> False if the index cannot be created for any reason.
* Index already exists
* File does not exist
* The dictionary file does not have a record with a key of the given field name.
* The dictionary file does not exist. Default is "dict." ^ filename.
* The dictionary field defines a calculated field that uses an exodus function. Using a psql function is OK.
<syntaxhighlight lang="c++">
var filename = "xo_clients", fieldname = "DATE_CREATED";
if (not deleteindex("xo_clients", "DATE_CREATED")) {}; // Cleanup first
if (filename.createindex(fieldname)) ... ok
// or
if (createindex(filename, fieldname)) ...</syntaxhighlight>
|-
|var=||file|conn.listindex(file_or_filename = "", fieldname = "")||Lists secondary indexes in a database or for a db file
<em>Returns:</em> False if the db file or fieldname are given and do not exist
<syntaxhighlight lang="c++">
var conn = "exodus";
if (conn.listindex()) ... ok // includes "xo_clients__date_created"
// or
if (listindex()) ... ok</syntaxhighlight>
|-
|if||file.deleteindex(fieldname)||Deletes a secondary index for a db file and field name.
<em>Returns:</em> False if the index cannot be deleted for any reason
* File does not exist
* Index does not already exists
<syntaxhighlight lang="c++">
var file = "xo_clients", fieldname = "DATE_CREATED";
if (file.deleteindex(fieldname)) ... ok
// or
if (deleteindex(file, fieldname)) ...</syntaxhighlight>
|-
|var=||file.lock(key)||Places a metaphorical db lock on a particular record given a db file and key.
This is a advisory lock, not a physical lock, since it makes no restriction on the access or modification of data by other connections.
Neither the db file nor the record key need to actually exist since a lock is just a hash of the db file name and key combined.
If another connection attempts to place an identical lock on the same database it will be denied.
Locks can be removed by unlock() or unlockall() or will be automatically removed at the end of a transaction or when the connection is closed.
If the same process attempts to place an identical lock more than once it may be denied (if not in a transaction) or succeed but be ignored (if in a transaction).
Locks can be used to avoid processing a transaction simultaneously with another connection only to have one of them fail due to mutually updating the same records.
Returns::
* 0: Failure: Another connection has already placed the same lock.
* "" Failure: The lock has already been placed.
* 1: Success: A new lock has been placed.
* 2: Success: The lock has already been placed and the connection is in a transaction.
<syntaxhighlight lang="c++">
var file = "xo_clients", key = "1000";
if (file.lock(key)) ... ok
// or
if (lock(file, key)) ...</syntaxhighlight>
|-
|if||file.unlock(key)||Removes a db lock placed by the lock function.
Only locks placed on the specified connection can be removed.
Locks cannot be removed while a connection is in a transaction.
<em>Returns:</em> False if the lock is not present in a connection.
<syntaxhighlight lang="c++">
var file = "xo_clients", key = "1000";
if (file.unlock(key)) ... ok
// or
if (unlock(file, key)) ...</syntaxhighlight>
|-
|if||file.unlockall()||Removes all db locks placed by the lock function in the specified connection.
Locks cannot be removed while in a transaction.
<syntaxhighlight lang="c++">
var conn = "exodus";
if (not conn.unlockall()) ...
// or
if (not unlockall(conn)) ...</syntaxhighlight>
|-
|cmd||record.write(file, key)||Writes a record into a db file given a unique primary key.
Either inserts a new record or updates an existing record.
It always succeeds so no result code is returned.
Any memory cached record is deleted.
<syntaxhighlight lang="c++">
let record = "Client GD^G^20855^30000^1001.00^20855.76539"_var;
let file = "xo_clients", key = "GD001";
if (not deleterecord("xo_clients", "GD001")) {}; // Cleanup first
record.write(file, key);
// or
write(record on file, key);</syntaxhighlight>
|-
|if||record.read(file, key)||Reads a record from a db file for a given key.
<em>Returns:</em> False if the key doesnt exist
<em>var:</em> Contains the record if it exists or is unassigned if not.
<syntaxhighlight lang="c++">
var record;
let file = "xo_clients", key = "GD001";
if (not record.read(file, key)) ... // record -> "Client GD^G^20855^30000^1001.00^20855.76539"_var
// or
if (not read(record from file, key)) ...</syntaxhighlight>
|-
|if||file.deleterecord(key)||Deletes a record from a db file given a key.
<em>Returns:</em> False if the key doesnt exist
Any memory cached record is deleted.
<syntaxhighlight lang="c++">
let file = "xo_clients", key = "GD001";
if (file.deleterecord(key)) ... ok
// or
if (deleterecord(file, key)) ...</syntaxhighlight>
|-
|if||record.insertrecord(file, key)||Inserts a new record in a db file.
<em>Returns:</em> False if the key already exists
Any memory cached record is deleted.
<syntaxhighlight lang="c++">
let record = "Client GD^G^20855^30000^1001.00^20855.76539"_var;
let file = "xo_clients", key = "GD001";
if (record.insertrecord(file, key)) ... ok
// or
if (insertrecord(record on file, key)) ...</syntaxhighlight>
|-
|if||record.updaterecord(file, key)||Updates an existing record in a db file.
<em>Returns:</em> False if the key doesnt already exist
Any memory cached record is deleted.
<syntaxhighlight lang="c++">
let record = "Client GD^G^20855^30000^1001.00^20855.76539"_var;
let file = "xo_clients", key = "GD001";
if (not record.updaterecord(file, key)) ...
// or
if (not updaterecord(record on file, key)) ...</syntaxhighlight>
|-
|if||strvar.readf(file, key, fieldno)||"Read field" Same as read() but only returns a specific field number from the record.
<syntaxhighlight lang="c++">
var field, file = "xo_clients", key = "GD001", fieldno = 2;
if (not field.readf(file, key, fieldno)) ... // field -> "G"
// or
if (not readf(field from file, key, fieldno)) ...</syntaxhighlight>
|-
|cmd||strvar.writef(file, key, fieldno)||"write field" Same as write() but only writes to a specific field number in the record
<syntaxhighlight lang="c++">
var field = "f3", file = "xo_clients", key = "1000", fieldno = 3;
field.writef(file, key, fieldno);
// or
writef(field on file, key, fieldno);</syntaxhighlight>
|-
|cmd||record.writec(file, key)||"Write cache" Writes a record and key into a memory cached "db file".
The actual database file is NOT updated.
writec() either updates an existing cache record if the key already exists or otherwise inserts a new record into the cache.
It always succeeds so no result code is returned.
Neither the db file nor the record key need to actually exist in the actual db.
<syntaxhighlight lang="c++">
let record = "Client XD^X^20855^30000^1001.00^20855.76539"_var;
let file = "xo_clients", key = "XD001";
record.writec(file, key);
// or
writec(record on file, key);</syntaxhighlight>
|-
|if||record.readc(file, key)||"Read cache" Same as "read() but first reads from a memory cache.
1. Tries to read from a memory cache. Returns true if successful.
2a. Tries to read from the actual db file and returns false if unsuccessful.
2b. Writes the record and key to the memory cache and returns true.
Cached db file data lives in exodus process memory and is lost when the process terminates or cleardbcache() is called.
<syntaxhighlight lang="c++">
var record;
let file = "xo_clients", key = "XD001";
if (record.readc(file, key)) ... ok
// or
if (readc(record from file, key)) ... ok
// Verify not in actual database file by using read() not readc()
if (read(record from file, key)) abort("Error: " ^ key ^ " should not be in the actual database file"); // error</syntaxhighlight>
|-
|if||dbfile.deletec(key)||Deletes a record and key from a memory cached "file".
The actual database file is NOT updated.
<em>Returns:</em> False if the key doesnt exist
<syntaxhighlight lang="c++">
var file = "xo_clients", key = "XD001";
if (file.deletec(key)) ... ok
// or
if (deletec(file, key)) ...</syntaxhighlight>
|-
|cmd||conn.cleardbcache()||Clears the memory cache of all records for the given connection
All future cache readc() function calls will be forced to obtain records from the actual database and refresh the cache.
<syntaxhighlight lang="c++">
conn.cleardbcache();
// or
cleardbcache(conn);</syntaxhighlight>
|-
|var=||strvar.xlate(filename, fieldno, mode)||The xlate ("translate") function is similar to readf() but, when called as an exodus program member function, it can be used efficiently with exodus file dictionaries using column names and functions and multivalued data.
<em>Arguments:</em>
<em>strvar:</em> Used as the primary key to lookup a field in a given file and field no or field name.
<em>filename:</em> The db file in which to look up data.
If var key is multivalued then a multivalued field is returned.
<em>fieldno:</em> Determines which field of the record is returned.
* Integer returns that field number
* 0 means return the key unchanged.
* "" means return the whole record.
<em>mode:</em> Determines what is returned if the record does not exist for the given key and file.
* "X" returns ""
* "C" returns the key unconverted.
<syntaxhighlight lang="c++">
let key = "SB001";
let client_name = key.xlate("xo_clients", 1, "X"); // "Client AAA"
// or
let name_and_type = xlate("xo_clients", key, "NAME_AND_TYPE", "X"); // "Client AAA (A)"</syntaxhighlight>
|}
===== Database Sort/Select =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|if||dbfile.select(sort_select_command = "")||Create an active select list of keys of a database file.
The select(command) function searches and orders database records for subsequent processing given an English language-like command.
The primary job of a database, beyond mere storage and retrieval of information, is to allow rapid searching and ordering of information on demand.
In Exodus, searching and ordering of information is known as "sort/select" and is performed by the select() function.
Executing the select() function creates an "active select list" which can then be consumed by the readnext() function.
<em>dbfile:</em> A opened database file or file name, or an open connection or an empty var for default connections. Subsequent readnext calls must use the same.
<em>sort_select_command:</em> A natural language command using dictionary field names. The command can be blank if a dbfile or filename is given in dbfile or just a file name and all keys will be selected in undefined order.
<em>Example:</em> "select xo_clients with type 'B' and with balance ge 100 by type by name"
<em>Option:</em> "(R)" appended to the sort_select_command acquires the database records as well.
<em>Returns:</em> True if any records are selected or false if none.
<em>Throws:</em> VarDBException in case of any syntax error in the command.
Active select lists created using var.select()'s member function syntax cannot be consumed by the free function form of readnext() and vice versa.
<syntaxhighlight lang="c++">
var clients = "xo_clients";
if (clients.select("with type 'B' and with balance ge 100 by type by name"))
    while (clients.readnext(ID))
        println("Client code is {}", ID);
// or
if (select("xo_clients with type 'B' and with balance ge 100 by type by name"))
    while (readnext(ID))
        println("Client code is {}", ID);</syntaxhighlight>
|-
|if||dbfile.selectkeys(keys)||Create an active select list from a string of keys.
Similar to select() but creates the list directly from a var.
<em>keys:</em> An FM separated list of keys or key^VM^valueno pairs.
<em>Returns:</em> True if any keys are provided or false if not.
<syntaxhighlight lang="c++">
var dbfile = "";
let keys = "A01^B02^C03"_var;
if (dbfile.selectkeys(keys)) ... ok
assert(dbfile.readnext(ID) and ID == "A01");
// or
if (selectkeys(keys)) ... ok
assert(readnext(ID) and ID == "A01");</syntaxhighlight>
|-
|if||dbfile.hasnext()||Checks if a select list is active.
<em>dbfile:</em> A file or connection var used in a prior select, selectkeys or getlist function call.
<em>Returns:</em> True if a select list is active and false if not.
If it returns true then a call to readnext() will return a database record key, otherwise not.
<syntaxhighlight lang="c++">
var clients = "xo_clients", key;
if (clients.select()) {
    assert(clients.hasnext());
}
// or
if (select("xo_clients")) {
    assert(hasnext());
}</syntaxhighlight>
|-
|if||dbfile.readnext(out key)||Acquires and consumes one key from an active select list of database record keys.
<em>dbfile:</em> A file or connection var used in a prior select, selectkeys or getlist function call.
<em>key:</em> Returns the first (next) key present in an active select list or "" if no select list is active.
<em>Returns:</em> True if a list is active and a key is available, false if not.
Each call to readnext consumes one key from the list.
Once all the keys in an active select list have been consumed by calls to readnext, the list becomes inactive.
See select() for example code.
|-
|if||dbfile.readnext(out key, out valueno)||Similar to readnext(key) but multivalued.
If the active list was ordered by multivalued database fields then pairs of key and multivalue number will be available to the readnext function.
|-
|if||dbfile.readnext(out record, out key, out valueno)||Similar to readnext(key) but acquires the database record as well.
<em>record:</em> Returns the next database record from the select list assuming that the select list was created with the (R) option otherwise "" if not.
<em>key:</em> Returns the next database record key in the select list.
<em>valueno:</em> The multivalue number if the select list was ordered on multivalued database record fields or 1 if not.
<syntaxhighlight lang="c++">
var clients = "xo_clients";
if (clients.select("with type 'B' and with balance ge 100 by type by name (R)"))
    while (clients.readnext(RECORD, ID, MV))
        println("Code is {}, Name is {}", ID, RECORD.f(1));
// or
DICT = "dict.xo_clients";
if (select("xo_clients with type 'B' and with balance ge 100 by type by name (R)"))
    while (readnext(RECORD, ID, MV))
        println("Code is {}, Name is {}", calculate("CODE"), calculate("NAME"));</syntaxhighlight>
|-
|cmd||dbfile.clearselect()||Deactivates an active select list.
<em>dbfile:</em> A file or connection var used in a prior select, selectkeys or getlist function call.
<em>Returns:</em> Nothing
Has no effect if no select list is active for dbfile.
<syntaxhighlight lang="c++">
var clients = "xo_clients";
clients.clearselect();
if (not clients.hasnext()) ... ok
// or
clearselect();
if (not hasnext()) ... ok</syntaxhighlight>
|-
|if||dbfile.savelist(listname)||Stores an active select list for later retrieval.
<em>dbfile:</em> A file or connection var used in a prior select, selectkeys or getlist function call.
<em>listname:</em> A suitable name that will be required for later retrieval.
<em>Returns:</em> True if saved successfully or false if there was no active list to be saved.
Any existing list with the same name will be overwritten.
Only the remaining unconsumed part of the active select list is saved.
Saved lists are stand-alone and are not tied to specific database files although they usually hold keys related to specific files.
Saved lists can be created from one file and used to access another.
savelist() merely writes an FM separated string of keys as a record in the "lists" database file using the list name as the key of the record.
If a saved list is very long, additional blocks of keys for the same list may be stored with keys like listname*2, listname*3 etc.
Select lists saved in the lists database file may be created, deleted and listed like database records in any other database file.
<syntaxhighlight lang="c++">
var clients = "xo_clients";
if (clients.select("with type 'B' by name")) {
}
// or
if (select("xo_clients with type 'B' by name")) {
    if (savelist("mylist")) ... ok
}</syntaxhighlight>
|-
|if||dbfile.getlist(listname)||Retrieve and reactivate a saved select list.
<em>dbfile:</em> A file or connection var to be used by subsequent readnext function calls.
<em>listname:</em> The name of an existing list in the "lists" database file, either created by savelist or manually.
<em>Returns:</em> True if the list was successfully retrieved and activated, or false if the list name doesnt exist.
Any currently active select list is replaced.
Retrieving a list does not delete it and a list can be retrieved more than once until specifically deleted.
<syntaxhighlight lang="c++">
var file = "";
if (file.getlist("mylist")) {
    while (file.readnext(ID))
        println("Key is {}", ID);
}
// or
if (getlist("mylist")) {
    while (readnext(ID))
        println("Key is {}", ID);
}</syntaxhighlight>
|-
|if||dbfile.deletelist(listname)||Delete a saved select list.
<em>dbfile:</em> A file or connection to the desired database.
<em>listname:</em> The name of an existing list in the "lists" database file.
<em>Returns:</em> True if successful or false if the list name doesnt exist.
<syntaxhighlight lang="c++">
var conn = "";
if (conn.deletelist("mylist")) ... ok
// or
if (deletelist("mylist")) ... ok</syntaxhighlight>
|}
===== OS Time/Date =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|var=||var().date()||Number of whole days since pick epoch 1967-12-31 00:00:00 UTC. Negative for dates before.
e.g. was 20821 from 2025-01-01 00:00:00 UTC for 24 hours
<syntaxhighlight lang="c++">
let today1 = var().date();
// or
let today2 = date();</syntaxhighlight>
|-
|var=||var().time()||Number of whole seconds since last 00:00:00 (UTC).
e.g. 43200 if time is 12:00
Range 0 - 86399 since there are 24*60*60 (86400) seconds in a day.
<syntaxhighlight lang="c++">
let now1 = var().time();
// or
let now2 = time();</syntaxhighlight>
|-
|var=||var().ostime()||Number of fractional seconds since last 00:00:00 (UTC).
A floating point with approx. nanosecond resolution depending on hardware.
e.g. 23343.704387955 approx. 06:29:03 UTC
<syntaxhighlight lang="c++">
let now1 = var().ostime();
// or
let now2 = ostime();</syntaxhighlight>
|-
|var=||var().timestamp()||Number of fractional days since pick epoch 1967-12-31 00:00:00 UTC. Negative for dates before.
A floating point with approx. nanosecond resolution depending on hardware.
e.g. Was 20821.99998842593 around 2025-01-01 23:59:59 UTC
<syntaxhighlight lang="c++">
let now1 = var().timestamp();
// or
let now2 = timestamp();</syntaxhighlight>
|-
|var=||var().timestamp(ostime)||Construct a timestamp from a date and time
<syntaxhighlight lang="c++">
let idate = iconv("2025-01-01", "D"), itime = iconv("23:59:59", "MT");
let ts1 = idate.timestamp(itime); // 20821.99998842593
// or
let ts2 = timestamp(idate, itime);</syntaxhighlight>
|-
|cmd||var().ossleep(milliseconds)||Sleep/pause/wait for a number of milliseconds
Releases the processor if not needed for a period of time or a delay is required.
<syntaxhighlight lang="c++">
var().ossleep(100); // sleep for 100ms
// or
ossleep(100);</syntaxhighlight>
|-
|var=||file_dir_list.oswait(milliseconds)||Sleep/pause/wait up to a given number of milliseconds or until any changes occur in an FM delimited list of directories and/or files.
Any terminal input (e.g. a key press) will also terminate the wait.
An FM array of event information is returned. See below.
Multiple events are returned in multivalues.
<syntaxhighlight lang="c++">
let v1 = ".^/etc/hosts"_var.oswait(100); /// e.g. "IN_CLOSE_WRITE^/etc^hosts^f"_var
// or
let v2 = oswait(".^/etc/hosts"_var, 100);</syntaxhighlight>
Returned array fields
1. Event type codes
2. dirpaths
3. filenames
4. d=dir, f=file
<pre>
Possible event type codes are as follows:
* IN_CLOSE_WRITE - A file opened for writing was closed
* IN_ACCESS      - Data was read from file
* IN_MODIFY      - Data was written to file
* IN_ATTRIB      - File attributes changed
* IN_CLOSE      - File was closed (read or write)
* IN_MOVED_FROM  - File was moved away from watched directory
* IN_MOVED_TO    - File was moved into watched directory
* IN_MOVE        - File was moved (in or out of directory)
* IN_CREATE      - A file was created in the directory
* IN_DELETE      - A file was deleted from the directory
* IN_DELETE_SELF - Directory or file under observation was deleted
* IN_MOVE_SELF  - Directory or file under observation was moved
</pre>
|}
===== OS File I/O =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|if||osfilevar.osopen(osfilename, utf8 = true)||Initialises an os file handle var that can be used in subsequent random access osbread and osbwrite functions.
<em>osfilename:</em> The name of an existing os file name including path.
<em>utf8:</em> Defaults to true which causes trimming of partial utf-8 Unicode byte sequences from the end of osbreads. For raw untrimmed osbreads pass tf8 = false;
<em>Returns:</em> True if successful or false if not possible for any reason. e.g. Target doesnt exist, permissions etc.
The file will be opened for writing if possible otherwise for reading.
<syntaxhighlight lang="c++">
let osfilename = ostempdirpath() ^ "xo_gendoc_test.conf";
if (oswrite("" on osfilename)) ... ok /// Create an empty os file
var ostempfile;
if (ostempfile.osopen(osfilename)) ... ok
// or
if (osopen(osfilename to ostempfile)) ... ok</syntaxhighlight>
|-
|if||osfilevar.osbwrite(osfilevar, io offset)||Writes data to an existing os file starting at a given byte offset (0 based).
See osbread for more info.
<syntaxhighlight lang="c++">
let osfilename = ostempdirpath() ^ "xo_gendoc_test.conf";
let text = "aaa=123\nbbb=456\n";
var offset = osfile(osfilename).f(1); /// Size of file therefore append
if (text.osbwrite(osfilename, offset)) ... ok // offset -> 16
// or
if (not osbwrite(text on osfilename, offset)) ...</syntaxhighlight>
|-
|if||osfilevar.osbread(osfilevar, io offset, length)||Reads length bytes from an existing os file starting at a given byte offset (0 based).
The osfilevar file handle may either be initialised by osopen or be just be a normal string variable holding the path and name of the os file.
After reading, the offset is updated to point to the correct offset for a subsequent sequential read.
If reading UTF8 data (the default) then the length of data actually returned may be a few bytes shorter than requested in order to be a complete number of UTF-8 code points.
<syntaxhighlight lang="c++">
let osfilename = ostempdirpath() ^ "xo_gendoc_test.conf";
var text, offset = 0;
if (text.osbread(osfilename, offset, 8)) ... ok // text -> "aaa=123\n" // offset -> 8
// or
if (osbread(text from osfilename, offset, 8)) ... ok // text -> "bbb=456\n" // offset -> 16</syntaxhighlight>
|-
|cmd||osfilevar.osclose()||Removes an osfilevar handle from the internal memory cache of os file handles. This frees up both exodus process memory and operating system resources.
It is advisable to osclose any file handles after use, regardless of whether they were specifically opened using osopen or not, especially in long running programs. Exodus performs caching of internal os file handles per thread and os file. If not closed, then the operating system will probably not flush deleted files from storage until the process is terminated. This can potentially create an memory issue or file system resource issue especially if osopening/osreading/oswriting many perhaps temporary files in a long running process.
<syntaxhighlight lang="c++">
osfilevar.osclose();
// or
osclose(osfilevar);</syntaxhighlight>
|-
|if||strvar.oswrite(osfilename, codepage = "")||Create a complete os file from a var.
Any existing os file is removed first.
<em>Returns:</em> True if successful or false if not possible for any reason.
e.g. Path is not writeable, permissions etc.
If codepage is specified then output is converted from utf-8 to that codepage. Otherwise no conversion is done.
<syntaxhighlight lang="c++">
let text = "aaa = 123\nbbb = 456";
let osfilename = ostempdirpath() ^ "xo_gendoc_test.conf";
if (text.oswrite(osfilename)) ... ok
// or
if (oswrite(text on osfilename)) ... ok</syntaxhighlight>
|-
|if||strvar.osread(osfilename, codepage = "")||Read a complete os file into a var.
If codepage is specified then input is converted from that codepage to utf-8 otherwise no conversion is done.
<em>Returns:</em> True if successful or false if not possible for any reason.
e.g. File doesnt exist, permissions etc.
<syntaxhighlight lang="c++">
var text;
let osfilename = ostempdirpath() ^ "xo_gendoc_test.conf";
if (text.osread(osfilename)) ... ok // text -> "aaa = 123\nbbb = 456"
// or
if (osread(text from osfilename)) ... ok</syntaxhighlight>
|-
|if||osfile_or_dirname.osrename(new_dirpath_or_filepath)||Renames an os file or dir in the OS file system.
Will not overwrite an existing os file or dir.
Source and target must exist in the same storage device.
<em>Returns:</em> True if successful or false if not possible for any reason.
e.g. Target already exists, path is not writeable, permissions etc.
Uses std::filesystem::rename internally.
<syntaxhighlight lang="c++">
let from_osfilename = ostempdirpath() ^ "xo_gendoc_test.conf";
let to_osfilename = from_osfilename ^ ".bak";
if (not osremove(ostempdirpath() ^ "xo_gendoc_test.conf.bak")) {}; // Cleanup first
if (from_osfilename.osrename(to_osfilename)) ... ok
// or
if (osrename(from_osfilename, to_osfilename)) ...</syntaxhighlight>
|-
|if||osfile_or_dirname.osmove(to_osfilename)||"Moves" an os file or dir within the os file system.
Will not overwrite an existing os file or dir.
<em>Returns:</em> True if successful or false if not possible for any reason.
e.g. Source doesnt exist or cannot be accessed, target already exists, source or target is not writeable, permissions etc.
Attempts osrename first then oscopy followed by osremove original.
<syntaxhighlight lang="c++">
let from_osfilename = ostempdirpath() ^ "xo_gendoc_test.conf.bak";
let to_osfilename = from_osfilename.cut(-4);
if (not osremove(ostempdirpath() ^ "xo_gendoc_test.conf")) {}; // Cleanup first
if (from_osfilename.osmove(to_osfilename)) ... ok
// or
if (osmove(from_osfilename, to_osfilename)) ...</syntaxhighlight>
|-
|if||osfile_or_dirname.oscopy(to_osfilename)||Copies an os file or directory recursively within the os file system.
Will overwrite an existing os file or dir.
Uses std::filesystem::copy internally with recursive and overwrite options
<syntaxhighlight lang="c++">
let from_osfilename = ostempdirpath() ^ "xo_gendoc_test.conf";
let to_osfilename = from_osfilename ^ ".bak";
if (from_osfilename.oscopy(to_osfilename)) ... ok;
// or
if (oscopy(from_osfilename, to_osfilename)) ... ok</syntaxhighlight>
|-
|if||osfilename.osremove()||Removes/deletes an os file from the OS file system given path and name.
Will not remove directories. Use osrmdir() to remove directories
<em>Returns:</em> True if successful or false if not possible for any reason.
e.g. Target doesnt exist, path is not writeable, permissions etc.
<syntaxhighlight lang="c++">
let osfilename = ostempdirpath() ^ "xo_gendoc_test.conf";
if (osfilename.osremove()) ... ok
// or
if (osremove(osfilename)) ...</syntaxhighlight>
|}
===== OS Directories =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|var=||dirpath.oslist(globpattern = "", mode = 0)||Returns: A FM delimited string containing all matching dir entries given a dir path
A glob pattern (e.g. *.conf) can be appended to the path or passed as argument.
<syntaxhighlight lang="c++">
var entries1 = "/etc/"_var.oslist("*.cfg"); /// e.g. "adduser.conf^ca-certificates.con^... etc."
// or
var entries2 = oslist("/etc/" "*.conf");</syntaxhighlight>
|-
|var=||dirpath.oslistf(globpattern = "")||Same as oslist for files only
|-
|var=||dirpath.oslistd(globpattern = "")||Same as oslist for files only
|-
|var=||osfile_or_dirpath.osinfo(mode = 0)||Returns: Dir info for any dir entry or "" if it doesnt exist
A short string containing size ^ FM ^ modified_time ^ FM ^ modified_time
mode 0 default
mode 1 returns "" if not an os file
mode 2 returns "" if not an os dir
See also osfile() and osdir()
<syntaxhighlight lang="c++">
var info1 = "/etc/hosts"_var.osinfo(); /// e.g. "221^20597^78309"_var
// or
var info2 = osinfo("/etc/hosts");</syntaxhighlight>
|-
|var=||osfilename.osfile()||Returns: Dir info for a os file
A short string containing size ^ FM ^ modified_time ^ FM ^ modified_time
Alias for osinfo(1)
<syntaxhighlight lang="c++">
var fileinfo1 = "/etc/hosts"_var.osfile(); /// e.g. "221^20597^78309"_var
// or
var fileinfo2 = osfile("/etc/hosts");</syntaxhighlight>
|-
|var=||dirpath.osdir()||Returns: Dir info for a dir.
A short string containing FM ^ modified_time ^ FM ^ modified_time
Alias for osinfo(2)
<syntaxhighlight lang="c++">
var dirinfo1 = "/etc/"_var.osdir(); /// e.g. "^20848^44464"_var
// or
var dirinfo2 = osfile("/etc/");</syntaxhighlight>
|-
|if||dirpath.osmkdir()||Makes a new directory and returns true if successful.
Including parent dirs if necessary.
<syntaxhighlight lang="c++">
let osdirname = "xo_test/aaa";
if (osrmdir("xo_test/aaa")) {}; // Cleanup first
if (osdirname.osmkdir()) ... ok
// or
if (osmkdir(osdirname)) ...</syntaxhighlight>
|-
|if||dirpath.oscwd(newpath)||Changes the current working dir and returns true if successful.
<syntaxhighlight lang="c++">
let osdirname = "xo_test/aaa";
if (osdirname.oscwd()) ... ok
// or
if (oscwd(osdirname)) ... ok
if (oscwd("../..")) ... ok /// Change back to avoid errors in following code.</syntaxhighlight>
|-
|var=||dirpath.oscwd()||Returns: The current working directory
e.g. "/root/exodus/cli/src/xo_test/aaa"
<syntaxhighlight lang="c++">
var cwd1 = var().oscwd();
// or
var cwd2 = oscwd();</syntaxhighlight>
|-
|if||dirpath.osrmdir(evenifnotempty = false)||Removes a os dir and returns true if successful.
Optionally even if not empty. Including subdirs.
<syntaxhighlight lang="c++">
let osdirname = "xo_test/aaa";
if (osdirname.osrmdir()) ... ok
// or
if (osrmdir(osdirname)) ...</syntaxhighlight>
|}
===== OS Shell/Environment =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|if||command.osshell()||Execute a shell command.
<em>Returns:</em> True if the process terminates with error status 0 and false otherwise.
Append "&>/dev/null" to the command to suppress terminal output.
<syntaxhighlight lang="c++">
let cmd = "echo $HOME";
if (cmd.osshell()) ... ok
// or
if (osshell(cmd)) ... ok</syntaxhighlight>
|-
|if||instr.osshellread(oscmd)||Same as osshell but captures and returns stdout
<em>Returns:</em> The stout of the shell command.
Append "2>&1" to the command to capture stderr/stdlog output as well.
<syntaxhighlight lang="c++">
let cmd = "echo $HOME";
var text;
if (text.osshellread(cmd)) ... ok
// or capturing stdout but ignoring exit status
text = osshellread(cmd);</syntaxhighlight>
|-
|if||outstr.osshellwrite(oscmd)||Same as osshell but provides stdin to the process
<em>Returns:</em> True if the process terminates with error status 0 and false otherwise.
Append "&> somefile" to the command to suppress and/or capture output.
<syntaxhighlight lang="c++">
let outtext = "abc xyz";
if (outtext.osshellwrite("grep xyz")) ... ok
// or
if (osshellwrite(outtext, "grep xyz")) ... ok</syntaxhighlight>
|-
|var=||var().ostempdirpath()||Returns: The path of the tmp dir
e.g. "/tmp/"
<syntaxhighlight lang="c++">
let v1 = var().ostempdirpath();
// or
let v2 = ostempdirpath();</syntaxhighlight>
|-
|var=||var().ostempfilename()||Returns: The name of a new temporary file
e.g. Something like "/tmp/~exoEcLj3C"
<syntaxhighlight lang="c++">
var temposfilename1 = var().ostempfilename();
// or
var temposfilename2 = ostempfilename();</syntaxhighlight>
|-
|cmd||envvalue.ossetenv(envcode)||Set the value of an environment variable code
<syntaxhighlight lang="c++">
let envcode = "EXO_ABC", envvalue = "XYZ";
envvalue.ossetenv(envcode);
// or
ossetenv(envcode, envvalue);</syntaxhighlight>
|-
|if||envvalue.osgetenv(envcode)||Get the value of an environment variable.
<em>envcode:</em> The code of the desired environment variable or "" for all.
<em>Returns:</em> True if set or false if not.
<em>var:</em> If envcode exists: var is set to the value of the environment variable
<em>var:</em> If envcode doesnt exist: var is set to ""
<em>var:</em> If envcode is "": var is set to an dynamic array of all environment variables LIKE CODE1=VALUE1^CODE2=VALUE2...
osgetenv and ossetenv work with a per thread copy of the process environment. This avoids multithreading issues but not actually changing the process environment.
For the actual system environment, see "man environ". extern char **environ; // environ is a pointer to an array of pointers to char* env pairs like xxx=yyy and the last pointer in the array is nullptr.
<syntaxhighlight lang="c++">
var envvalue1;
if (envvalue1.osgetenv("HOME")) ... ok // e.g. "/home/exodus"
// or
var envvalue2 = osgetenv("EXO_ABC"); // "XYZ"</syntaxhighlight>
|-
|var=||var().ospid()||Get the os process id
<syntaxhighlight lang="c++">
let pid1 = var().ospid(); /// e.g. 663237
// or
let pid2 = ospid();</syntaxhighlight>
|-
|var=||var().ostid()||Get the os thread process id
<syntaxhighlight lang="c++">
let tid1 = var().ostid(); /// e.g. 663237
// or
let tid2 = ostid();</syntaxhighlight>
|-
|var=||var().version()||Get the libexodus build date and time
<syntaxhighlight lang="c++">
let v1 = var().version(); /// e.g. "29 JAN 2025 14:56:52"</syntaxhighlight>
|-
|if||strvar.setxlocale()||Sets the current thread's default locale codepage code
True if successful
<syntaxhighlight lang="c++">
if ("en_US.utf8"_var.setxlocale()) ... ok
// or
if (setxlocale("en_US.utf8")) ... ok</syntaxhighlight>
|-
|var=||var.getxlocale()||Returns: The current thread's default locale codepage code
<syntaxhighlight lang="c++">
let v1 = var().getxlocale(); // "en_US.utf8"
// or
let v2 = getxlocale();</syntaxhighlight>
|}
===== Output =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|expr||varstr.outputl(prefix = "")||Output to stdout with optional prefix.
Appends an NL char.
Is FLUSHED, not buffered.
The raw string bytes are output. No character or byte conversion is performed.
<syntaxhighlight lang="c++">
"abc"_var.outputl("xyz = "); /// Sends "xyz = abc\n" to stdout and flushes.
// or
outputl("xyz = ", "abc"); /// Any number of arguments is allowed. All will be output.</syntaxhighlight>
|-
|expr||varstr.output(prefix = "")|| Same as outputl() but doesnt append an NL char and is BUFFERED, not flushed.
|-
|expr||varstr.outputt(prefix = "")|| Same as outputl() but appends a tab char instead of an NL char and is BUFFERED, not flushed.
|-
|expr||varstr.logputl(prefix = "")||Output to stdlog with optional prefix.
Appends an NL char.
Is BUFFERED not flushed.
Any of the six types of field mark chars present are converted to their visible versions,
<syntaxhighlight lang="c++">
"abc"_var.logputl("xyz = "); /// Sends "xyz = abc\n" to stdlog buffer and is not flushed.
// or
logputl("xyz = ", "abc");; /// Any number of arguments is allowed. All will be output.</syntaxhighlight>
|-
|expr||varstr.logput(prefix = "")|| Same as logputl() but doesnt append an NL char.
|-
|expr||varstr.errputl(prefix = "")||Output to stderr with optional prefix.
Appends an NL char.
Is FLUSHED not buffered.
Any of the six types of field mark chars present are converted to their visible versions,
<syntaxhighlight lang="c++">
"abc"_var.errputl("xyz = "); /// Sends "xyz = abc\n" to stderr
// or
errputl("xyz = ", "abc"); /// Any number of arguments is allowed. All will be output.</syntaxhighlight>
|-
|expr||varstr.errput(prefix = "")|| Same as errputl() but doesnt append an NL char and is BUFFERED not flushed.
|-
|expr||varstr.put(std::ostream& ostream1)||Output to a given stream.
Is BUFFERED not flushed.
The raw string bytes are output. No character or byte conversion is performed.
|-
|cmd||var().osflush()||Flush any and all buffered output to stdout and stdlog.
<syntaxhighlight lang="c++">
var().osflush();
// or
osflush();</syntaxhighlight>
|}
===== Input =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|if||var.input(prompt = "")||Returns one line of input from stdin.
<em>Returns:</em> True if successful or false if EOF or user pressed Esc or Ctrl+X in a terminal.
<em>var:</em> [in] The default value for terminal input and editing. Ignored if not a terminal.
<em>var:</em> [out] Raw bytes up to but excluding the first new line char. In case of EOF or user pressed Esc or Ctrl+X in a terminal it will be changed to "".
<em>Prompt:</em> If provided, it will be displayed on the terminal.
Multibyte/UTF8 friendly.
<syntaxhighlight lang="c++">
// var v1 = "defaultvalue";
// if (v1.input("Prompt:")) ... ok
// or
// var v2 = input();</syntaxhighlight>
|-
|expr||var.keypressed(wait = false)||Return the code of the current terminal key pressed.
<em>wait:</em> Defaults to false. True means wait for a key to be pressed if not already pressed.
<em>Returns:</em> ASCII or key code defined according to terminal protocol.
<em>Returns:</em> "" if stdin is not a terminal.
e.g. The PgDn key if pressed might return an escape sequence like "\x1b[6~"
It only takes a few µsecs to return false if no key is pressed.
<syntaxhighlight lang="c++">
var v1; v1.keypressed();
// or
var v2 = keypressed();</syntaxhighlight>
|-
|if||var().isterminal(arg = 1)||Checks if one of stdin, stdout, stderr is a terminal or a file/pipe.
<em>arg:</em> 0 - stdin, 1 - stdout (Default), 2 - stderr.
<em>Returns:</em> True if it is a terminal or false if it is a file or pipe.
Note that if the process is at the start or end of a pipeline, then only stdin or stdout will be a terminal.
The type of stdout terminal can be obtained from the TERM environment variable.
<syntaxhighlight lang="c++">
var v1 = var().isterminal(); /// 1 or 0
// or
var v2 = isterminal();</syntaxhighlight>
|-
|if||var().hasinput(milliseconds = 0)||Checks if stdin has any bytes available for input.
If no bytes are immediately available, the process sleeps for up to the given number of milliseconds, returning true immediately any bytes become available or false if the period expires without any bytes becoming available.
<em>Returns:</em> True if any bytes are available otherwise false.
It only takes a few µsecs to return false if no bytes are available and no wait time has been requested.
|-
|if||var().eof()||True if stdin is at end of file
|-
|if||var().echo(on_off = true)||Sets terminal echo on or off.
"On" causes all stdin data to be reflected to stdout if stdin is a terminal.
Turning terminal echo off can be used to prevent display of confidential information.
<em>Returns:</em> True if successful.
|-
|cmd||var().breakon()||Install various interrupt handlers.
Automatically called in program/thread initialisation by exodus_main.
SIGINT - Ctrl+C -> "Interrupted. (C)ontinue (Q)uit (B)acktrace (D)ebug (A)bort ?"
SIGHUP - Sets a static variable "RELOAD_req" which may be handled or ignored by the program.
SIGTERM - Sets a static variable "TERMINATE_req" which may be handled or ignored by the program.
|-
|cmd||var().breakoff()||Disable keyboard interrupt.
Ctrl+C becomes inactive in terminal.
|}
===== Math/Boolean =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|var=||varnum.abs()||Absolute value
<syntaxhighlight lang="c++">
let v1 = -12.34;
let v2 = v1.abs(); // 12.34
// or
let v3 = abs(v1);</syntaxhighlight>
|-
|var=||varnum.pwr(exponent)||Power
<syntaxhighlight lang="c++">
let v1 = var(2).pwr(8); // 256
// or
let v2 = pwr(2, 8);</syntaxhighlight>
|-
|cmd||varnum.initrnd()||Initialise the seed for rnd()
Allows the stream of pseudo random numbers generated by rnd() to be reproduced.
Seeded from std::chrono::high_resolution_clock::now() if the argument is 0;
<syntaxhighlight lang="c++">
var(123).initrnd(); /// Set seed to 123
// or
initrnd(123);</syntaxhighlight>
|-
|var=||varnum.rnd()||Pseudo random number generator
<em>Returns:</em> a pseudo random integer between 0 and the provided maximum minus 1.
Uses std::mt19937 and std::uniform_int_distribution<int>
<syntaxhighlight lang="c++">
let v1 = var(100).rnd(); /// Random 0 to 99
// or
let v2 = rnd(100);</syntaxhighlight>
|-
|var=||varnum.exp()||Power of e
<syntaxhighlight lang="c++">
let v1 = var(1).exp(); // 2.718281828459045
// or
let v2 = exp(1);</syntaxhighlight>
|-
|var=||varnum.sqrt()||Square root
<syntaxhighlight lang="c++">
let v1 = var(100).sqrt(); // 10
// or
let v2 = sqrt(100);</syntaxhighlight>
|-
|var=||varnum.sin()||Sine of degrees
<syntaxhighlight lang="c++">
let v1 = var(30).sin(); // 0.5
// or
let v2 = sin(30);</syntaxhighlight>
|-
|var=||varnum.cos()||Cosine of degrees
<syntaxhighlight lang="c++">
let v1 = var(60).cos(); // 0.5
// or
let v2 = cos(60);</syntaxhighlight>
|-
|var=||varnum.tan()||Tangent of degrees
<syntaxhighlight lang="c++">
let v1 = var(45).tan(); // 1
// or
let v2 = tan(45);</syntaxhighlight>
|-
|var=||varnum.atan()||Arctangent of degrees
<syntaxhighlight lang="c++">
let v1 = var(1).atan(); // 45
// or
let v2 = atan(1);</syntaxhighlight>
|-
|var=||varnum.loge()||Natural logarithm
<em>Returns:</em> Floating point ver (double)
<syntaxhighlight lang="c++">
let v1 = var(2.718281828459045).loge(); // 1
// or
let v2 = loge(2.718281828459045);</syntaxhighlight>
|-
|var=||varnum.integer()||Truncate decimal numbers towards zero
<em>Returns:</em> An integer var
<syntaxhighlight lang="c++">
let v1 = var(2.9).integer(); // 2
// or
let v2 = integer(2.9);
var v3 = var(-2.9).integer(); // -2
// or
var v4 = integer(-2.9);</syntaxhighlight>
|-
|var=||varnum.floor()||Truncate decimal numbers towards negative
<em>Returns:</em> An integer var
<syntaxhighlight lang="c++">
let v1 = var(2.9).floor(); // 2
// or
let v2 = floor(2.9);
var v3 = var(-2.9).floor(); // -3
// or
var v4 = floor(-2.9);</syntaxhighlight>
|-
|var=||varnum.mod(modulus)||Modulus function
Identical to C++ % operator only for positive numbers and modulus
Negative denominators are considered as periodic with positiive numbers
Result is between [0, modulus) if modulus is positive
Result is between (modulus, 0] if modulus is negative (symmetric)
<em>Throws:</em> VarDivideByZero if modulus is zero.
Floating point works.
<syntaxhighlight lang="c++">
let v1 = var(11).mod(5); // 1
// or
let v2 = mod(11, 5); // 1
let v3 = mod(-11, 5); // 4
let v4 = mod(11, -5); // -4
let v5 = mod(-11, -5); // -1</syntaxhighlight>
|}
=== I/O Conversion Codes  ===
{|class="wikitable"
!Usage!!Function!!Description
|-
|var=||vardate.oconv("D")||Date output: Convert internal date format to human readable date or calendar info in text format.
<em>Returns:</em> Human readable date or calendar info, or the original value unconverted if non-numeric.
<em>Flags:</em> See examples below.
Any multifield/multivalue structure is preserved.
<syntaxhighlight lang="c++">
let v1 = 12345;
assert( v1.oconv( "D"  ) == "18 OCT 2001"  ); // Default
assert( v1.oconv( "D/"  ) == "10/18/2001"  ); // / separator
assert( v1.oconv( "D-"  ) == "10-18-2001"  ); // - separator
assert( v1.oconv( "D2"  ) == "18 OCT 01"    ); // 2 digit year
assert( v1.oconv( "D/E" ) == "18/10/2001"  ); // International order with /
assert( v1.oconv( "DS"  ) == "2001 OCT 18"  ); // ISO Year first
assert( v1.oconv( "DS-" ) == "2001-10-18"  ); // ISO Year first with -
assert( v1.oconv( "DM"  ) == "10"          ); // Month number
assert( v1.oconv( "DMA" ) == "OCTOBER"      ); // Month name
assert( v1.oconv( "DY"  ) == "2001"        ); // Year number
assert( v1.oconv( "DY2" ) == "01"          ); // Year 2 digits
assert( v1.oconv( "DD"  ) == "18"          ); // Day number in month (1-31)
assert( v1.oconv( "DW"  ) == "4"            ); // Weekday number (1-7)
assert( v1.oconv( "DWA" ) == "THURSDAY"    ); // Weekday name
assert( v1.oconv( "DQ"  ) == "4"            ); // Quarter number
assert( v1.oconv( "DJ"  ) == "291"          ); // Day number in year
assert( v1.oconv( "DL"  ) == "31"          ); // Last day number of month (28-31)
// Multifield/multivalue
var v2 = "12345^12346]12347"_var;
assert(v2.oconv("D") == "18 OCT 2001^19 OCT 2001]20 OCT 2001"_var);
  // or
  assert( oconv(v1, "D"  ) == "18 OCT 2001"  );</syntaxhighlight>
|-
|var=||varstr.iconv("D")||Date input: Convert human readable date to internal date format.
<em>Returns:</em> Internal date or "" if the input is an invalid date.
Internal date format is whole days since 1967-12-31 00:00:00 which is day 0.
Any multifield/multivalue structure is preserved.
<syntaxhighlight lang="c++">
// International order "DE"
assert(            oconv(19005, "DE") == "12 JAN 2020");
assert(  "12/1/2020"_var.iconv("DE") == 19005);
assert(  "12 1 2020"_var.iconv("DE") == 19005);
assert(  "12-1-2020"_var.iconv("DE") == 19005);
assert( "12 JAN 2020"_var.iconv("DE") == 19005);
assert( "jan 12 2020"_var.iconv("DE") == 19005);
// American order "D"
assert(            oconv(19329, "D") == "01 DEC 2020");
assert(  "12/1/2020"_var.iconv("D") == 19329);
assert(  "DEC 1 2020"_var.iconv("D") == 19329);
assert(  "1 dec 2020"_var.iconv("D") == 19329);
// Reverse order
assert(  "2020/12/1"_var.iconv("DE") == 19329);
assert(  "2020-12-1"_var.iconv("D") == 19329);
assert(  "2020 1 dec"_var.iconv("D") == 19329);
//Invalid date
assert(  "2/29/2021"_var.iconv("D") == "");
assert(  "29/2/2021"_var.iconv("DE") == "");
// or
assert(iconv("12/1/2020"_var, "DE") == 19005);</syntaxhighlight>
|-
|var=||vartime.oconv("MT")||Time output: Convert internal time format to human readable time e.g. "10:30:59".
<em>Returns:</em> Human readable time or the original value unconverted if non-numeric.
Conversion code (e.g. "MTHS") is "MT" + flags ...
<em>Flags:</em>
"H" - Show AM/PM otherwise 24 hour clock is used.
"S" - Output seconds
"2" = Ignored (used in iconv)
":" - Any other flag is used as the separator char instead of ":"
Any multifield/multivalue structure is preserved.
<syntaxhighlight lang="c++">
var v1 = 234800;
assert( v1.oconv( "MT"  ) == "17:13"      ); // Default
assert( v1.oconv( "MTH"  ) == "05:13PM"    ); // 'H' flag for AM/PM
assert( v1.oconv( "MTS"  ) == "17:13:20"  ); // 'S' flag for seconds
assert( v1.oconv( "MTHS" ) == "05:13:20PM" ); // Both flags
var v2 = 0;
assert( v2.oconv( "MT"  ) == "00:00"      );
assert( v2.oconv( "MTH"  ) == "12:00AM"    );
assert( v2.oconv( "MTS"  ) == "00:00:00"  );
assert( v2.oconv( "MTHS" ) == "12:00:00AM" );
// Multifield/multivalue
var v3 = "234800^234860]234920"_var;
assert(v3.oconv("MT") == "17:13^17:14]17:15"_var);
// or
assert( oconv(v1, "MT"  ) == "17:13"      );</syntaxhighlight>
|-
|var=||varstr.iconv("MT")||Time input: Convert human readable time (e.g. "10:30:59") to internal time format.
<em>Returns:</em> Internal time or "" if the input is an invalid time.
Internal time format is whole seconds since midnight.
<em>Accepts:</em> Two or three groups of digits surrounded and separated by any non-digits char(s).
Any multifield/multivalue structure is preserved.
<syntaxhighlight lang="c++">
assert(      "17:13"_var.iconv( "MT" ) == 61980);
assert(    "05:13PM"_var.iconv( "MT" ) == 61980);
assert(  "17:13:20"_var.iconv( "MT" ) == 62000);
assert( "05:13:20PM"_var.iconv( "MT" ) == 62000);
assert(      "00:00"_var.iconv( "MT" ) == 0);
assert(    "12:00AM"_var.iconv( "MT" ) == 0);    // Midnight
assert(    "12:00PM"_var.iconv( "MT" ) == 43200); // Noon
assert(  "00:00:00"_var.iconv( "MT" ) == 0);
assert( "12:00:00AM"_var.iconv( "MT" ) == 0);
// Multifield/multivalue
assert("17:13^05:13PM]17:13:20"_var.iconv("MT") == "61980^61980]62000"_var);
// or
assert(iconv("17:13", "MT") == 61980);</syntaxhighlight>
|-
|var=||varnum.oconv("MD")||Number output: Convert internal numbers to external text format after rounding and optional scaling.
<em>Returns:</em> A string or, if the value is not numeric, then no conversion is performed and the original value is returned.
Conversion code (e.g. "MD20") is "MD" or "MC", 1st digit, 2nd digit, flags ...
MD outputs like 123.45 (International)
MC outputs like 123,45 (European)
1st digit = Decimal places to display. Also decimal places to move if 2nd digit not present and no P flag present.
2nd digit = Optional decimal places to move left if P flag not present.
<em>Flags:</em>
"P" - Preserve decimal places. Same as 2nd digit = 0;
"Z" - Zero flag - return "" if zero.
"X" - No conversion - return as is.
"." or "," - Separate thousands depending on MD or MC.
"-" means suffix negatives with "-" and positives with " " (space).
"<" means wrap negatives in "<" and ">" chars.
"C" means suffix negatives with "CR" and positives or zero with "DB".
"D" means suffix negatives with "DB" and positives or zero with "CR".
Any multifield/multivalue structure is preserved.
<syntaxhighlight lang="c++">
var v1 = -1234.567;
assert( v1.oconv( "MD20"  ) ==  "-1234.57"  );
assert( v1.oconv( "MD20,"  ) == "-1,234.57"  ); // , flag
assert( v1.oconv( "MC20,"  ) == "-1.234,57"  ); // MC code
assert( v1.oconv( "MD20,-" ) ==  "1,234.57-"  ); // - flag
assert( v1.oconv( "MD20,<" ) == "<1,234.57>"  ); // < flag
assert( v1.oconv( "MD20,C" ) ==  "1,234.57CR" ); // C flag
assert( v1.oconv( "MD20,D" ) ==  "1,234.57DB" ); // D flag
// Multifield/multivalue
var v2 = "1.1^2.1]2.2"_var;
assert( v2.oconv( "MD20"  ) == "1.10^2.10]2.20"_var);
// or
assert( oconv(v1, "MD20"  ) ==  "-1234.57"  );</syntaxhighlight>
|-
|var=||var.oconv("LRC")||Text justification: Left, right and center. Padding and truncating. See Procrustes.
e.g. "L#10", "R#10", "C#10"
Useful when outputting to terminal devices where spaces are used for alignment.
Multifield/multivalue structure is preserved.
ASCII only.
<syntaxhighlight lang="c++">
assert(    "abcde"_var.oconv( "L#3" ) == "abc" ); // Truncating
assert(    "abcde"_var.oconv( "R#3" ) == "cde" );
assert(    "abcde"_var.oconv( "C#3" ) == "abc" );
assert(    "ab"_var.oconv( "L#6" ) == "ab␣␣␣␣" ); // Padding
assert(    "ab"_var.oconv( "R#6" ) == "␣␣␣␣ab" );
assert(    "ab"_var.oconv( "C#6" ) == "␣␣ab␣␣" );
assert(      var(42).oconv( "L(0)#5" ) == "42000" ); // Padding char (x)
assert(      var(42).oconv( "R(0)#5" ) == "00042" );
assert(      var(42).oconv( "C(0)#5" ) == "04200" );
assert(      var(42).oconv( "C(0)#5" ) == "04200" );
// Multifield/multivalue
assert(      "f1^v1]v2"_var.oconv("L(_)#5") == "f1___^v1___]v2___"_var);
// Fail for non-ASCII (Should be 5)
assert(    "🐱"_var.oconv("L#5").textwidth() == 3);
// or
assert(    oconv("abcd", "L#3" ) == "abc" );</syntaxhighlight>
|-
|var=||varstr.oconv("T")||Text folding and justification.
e.g. T#20
Useful when outputting to terminal devices where spaces are used for alignment.
Splits text into multiple fixed length lines by inserting spaces and TM chars.
ASCII only.
<syntaxhighlight lang="c++">
var v1 = "Have a nice day";
assert(  v1.oconv("T#10") == "Have a␣␣␣␣|nice day␣␣"_var);
// or
assert( oconv(v1, "T#10") == "Have a␣␣␣␣|nice day␣␣"_var );</syntaxhighlight>
|-
|var=||varstr.oconv("HEX")||Convert a string of bytes to a string of hexadecimal digits. The size of the output is precisely double that of the input.
Multifield/multivalue structure is not preserved. Field marks are converted to HEX as for all other bytes.
<syntaxhighlight lang="c++">
assert(    "ab01"_var.oconv( "HEX" ) == "61" "62" "30" "31" );
assert( "\xff\x00"_var.oconv( "HEX" ) == "FF" "00"          ); // Any bytes are ok.
assert(        var(10).oconv( "HEX" ) == "31" "30"          ); // Uses ASCII string equivalent of 10 i.e. "10".
assert(  "\u0393"_var.oconv( "HEX" ) == "CE" "93"          ); // Greek capital Gamma in UTF8 bytes.
assert(    "a^]b"_var.oconv( "HEX" ) == "61" "1E" "1D" "62" ); // Field and value marks.
// or
assert(      oconv("ab01"_var, "HEX") == "61" "62" "30" "31");</syntaxhighlight>
|-
|var=||varstr.iconv("HEX")||Convert a string of hexadecimal digits to a string of bytes. After prefixing a "0" to an odd sized input, the size of the output is precisely half that of the input.
Reverse of oconv("HEX") above.
|-
|var=||varnum.oconv("MX")||Number to hex format: Convert number to hexadecimal string
If the value is not numeric then no conversion is performed and the original value is returned.
<syntaxhighlight lang="c++">
assert( var("255").oconv("MX") == "FF");
// or
assert( oconv(var("255"), "MX") == "FF");</syntaxhighlight>
|-
|var=||varnum.oconv("MB")||Number to binary format: Convert number to strings of 1s and 0s
If the value is not numeric then no conversion is performed and the original value is returned.
<syntaxhighlight lang="c++">
assert( var(255).oconv("MB") == 1111'1111);
// or
assert( oconv(var(255), "MB") == 1111'1111);</syntaxhighlight>
|-
|var=||varstr.oconv("TX")||Convert dynamic arrays to standard text format.
Useful for using text editors on dynamic arrays.
FMs -> NL after escaping any embedded NL
<syntaxhighlight lang="c++">
  // backslash in text remains backslash
  assert(var(_BS).oconv("TX") == _BS);
  // 1. Double escape any _BS "n" -> _BS _BS "n"
  assert(var(_BS "n").oconv("TX") == _BS _BS "n");
  // 2. Single escape any _NL -> _BS "n"
  assert(var(_NL).oconv("TX") == _BS "n");
  // 3. FMs -> _NL (⏎)
  assert("🌍^🌍"_var.oconv("TX") == "🌍" _NL "🌍");
  // 4. VMs -> _BS _NL (\⏎)
  assert("🌍]🌍"_var.oconv("TX") == "🌍" _BS _NL "🌍");
  // 5. SMs -> _BS _BS _NL (\\⏎)
  assert("🌍}🌍"_var.oconv("TX") == "🌍" _BS _BS _NL "🌍");
  // 6. TMs -> _BS _BS _BS _NL (\\\⏎)
  assert("🌍|🌍"_var.oconv("TX") == "🌍" _BS _BS _BS _NL "🌍");
  // 7. STs -> _BS _BS _BS _BS _NL (\\\\⏎)
  assert("🌍~🌍"_var.oconv("TX") == "🌍" _BS _BS _BS _BS _NL "🌍");</syntaxhighlight>
|-
|var=||varstr.iconv("TX")||Convert standard text format to dynamic array.
Reverse of oconv("TX") above.
|}
=== Dimensioned Array Construction  ===
{|class="wikitable"
!Usage!!Function!!Description
|-
|dim()||dim d1;||Create an undimensioned array of var.
|-
|dim(const||dim d1 = d2; // Copy||Copy an array.
|-
|dim(dim&&||dim d1 = dim(); // Move||Save an array created elsewhere.
|-
|dim(const||dim d1(nrows, ncols = 1); // Constructor||Create an array of vars with a fixed number of columns and rows. All vars are unassigned.
|-
|dim(std::initializer_list<T>||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..
|-
|cmd||dim d1 = v1;||Initialise all elements of an array to some single value or constant. A var, "", 0 etc.
|-
|cmd||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".
|-
|cmd||d1.swap(dim& d2) ||Swap one array with another.
Either or both may be undimensioned.
|}
=== Array Access ===
{|class="wikitable"
!Usage!!Function!!Description
|-
|VARREF||var v1 = d1[rowno];      d1[rowno] = v1;||Access and update elements of a one dimensional array using [] brackets
|-
|VARREF||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
<em>Returns:</em> A count. Can be zero, indicating an empty array.
|-
|var=||d1.cols()||Get the number of columns in the dimensioned array
<em>Returns:</em> A count.  0 if the array is undimensioned.
|-
|var=||d1.join(delimiter = FM)||Joins all elements into a single delimited string
<em>Returns:</em> A string var.
|}
=== Array Mutation ===
{|class="wikitable"
!Usage!!Function!!Description
|-
|dim2||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>
|-
|dim2||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.
|-
|dim2||d1.reverser()||Reverse the elements of the array. In place.
|-
|dim2||d1.shuffler()||Randomly shuffle the order of the elements of the array. In place.
|}
=== Array Conversion ===
{|class="wikitable"
!Usage!!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"
!Usage!!Function!!Description
|-
|cmd||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.
<em>Returns:</em> 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"
!Usage!!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.
<em>codepage:</em> Optional: Data is converted from UTF8 to the required codepage/encoding before output. If the conversion cannot be performed then return false.
<em>Returns:</em> 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.
<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>Returns:</em> 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>
|}:
=== Var Creation  ===
{|class="wikitable"
!Usage!!Function!!Description
|-
|var()||var <1;||Create an unassigned var.
Whereever possible, variables should be assigned an initial value immediately at their point of definition, and marked as const if appropriate. However variables often have no real single initial value and are commonly defined in advance of being assigned a particular value. For example, a variable may be assigned differently on different branches of a conditional statement, or be provided as an outbound argument of a function call.
Even when not assigned, "use before initialisation" bugs do not occur because a runtime error VarUnassigned is thrown if a var is used before it has been assigned a value.
Use "let" instead of "var" as a shorthand way of writing "const var" whereever possible.
<syntaxhighlight lang="c++">
let clients = "xo_clients", key = "SB001"; // const vars
var client;                                // Unassigned var
if (not read(client from clients, key)) ...</syntaxhighlight>
|-
|cmd||<em>operator=</em>(expression)||Assign a var using a literal or an expression. Alternatively, use "let" instead of "var" as a shorthand way of writing "const var" where appropriate.
<syntaxhighlight lang="c++">
var v1 = 42;                // Integer
var v2 = 42.3;              // Double
var v3 = "abc";              // String
var v4 = 'x';                // char
var v5 = true;              // bool
var v6 = v1 + 100;          // Arithmetic
var v7 = v3 ^ "xyz";        // Concatenation
var v8 = oslist(".").sort(); // Built in functions
let v9 = 12345;              // A const var
var v10 = 12'345_var;        // A literal var integer
var v11 = 123.45_var;        // A literal var double
var v12 = "f1^v1]v2^f3"_var; // A literal var string
var x = 0.1, y = "0.2", z = x + y; // z -> 0.3</syntaxhighlight>
|-
|if||v1.<em>assigned</em>()||Returns: True if the var is assigned, otherwise false
|-
|if||v1.<em>unassigned</em>()||Returns: True if the var is unassigned, otherwise false
|-
|var=||v2.<em>or_default</em>(defaultvalue)||Returns: A copy of the var if it is assigned or the default value if it is not.
Can be used to handle optional arguments in functions.
<em>defaultvalue:</em> Cannot be unassigned.
<syntaxhighlight lang="c++">
var v1; // Unassigned
var v2 = v1.or_default("abc"); // v2 -> "abc"
// or
var v3 = or_default(v1, "abc");</syntaxhighlight>
|-
|cmd||v1.<em>defaulter</em>(defaultvalue)||If the var is unassigned then assign the default value to it, otherwise do nothing.
<em>defaultvalue:</em> Cannot be unassigned.
<syntaxhighlight lang="c++">
var v1; // Unassigned
v1.defaulter("abc"); // v1 -> "abc"
// or
defaulter(v1, "abc");</syntaxhighlight>
|-
|cmd||v1.<em>swap</em>(io v2)||Swap the contents of one var with another.
Useful for stashing large strings quickly. They are moved using pointers without making copies or allocating memory.
Eiher or both variables may be unassigned.
<syntaxhighlight lang="c++">
var v1 = space(65'536);
var v2 = "";
v1.swap(v2); // v1 -> "" // v2.len() -> 65'536
// or
swap(v1, v2);</syntaxhighlight>
|-
|var=||v2.<em>move</em>()||Force the contents of a var to be moved instead of copied. The moved var becomes an empty string.
This allows large strings to be handled efficiently. They are moved using pointers without making copies or allocating memory.
The moved var must be assigned otherwise a VarUnassigned error is thrown.
<syntaxhighlight lang="c++">
var v1 = space(65'536);
var v2 = v1.move(); // v2.len() -> 65'536 // v1 -> ""
// or
var v3 = move(v2);</syntaxhighlight>
|-
|var=||v2.<em>clone</em>()||Returns a copy of the var.
The cloned var may be unassigned, in which case the copy will be unassigned too.
<syntaxhighlight lang="c++">
var v1 = "abc";
var v2 = v1.clone(); // "abc"
// or
var v3 = clone(v2);</syntaxhighlight>
|-
|var=||v1.<em>dump</em>()||Return a string describing internal data of a var.
If the str is located on the heap then its address is given.
<em>typ:</em>
0x01 str is available.
0x02 int is available.
0x04 dbl is available.
0x08 nan: str is not a number.
0x16 osfile: str, int and dbl have special meaning.
<syntaxhighlight lang="c++">
var v1 = str("x", 32);
v1.dump().outputl(); // e.g. var:0x7ffea7462cd0 typ:1 str:0x584d9e9f6e70 "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
// or
outputl(dump(v1));</syntaxhighlight>
|}
=== Arithmetical Operators  ===
{|class="wikitable"
!Usage!!Function!!Description
|-
|if||v1.<em>isnum</em>()||Checks if a var is numeric.
<em>Returns:</em> True if a var holds a double, an integer, or a string that is defined as numeric.
A string is defined as numeric only if it consists of one or more digits 0-9, with an optional decimal point "." placed anywhere, with an optional + or - sign prefix, or it is the empty string "", which is defined to be zero.
<syntaxhighlight lang="c++">
if ("+123.45"_var.isnum()) ... ok
if (      ""_var.isnum()) ... ok
if (not  "."_var.isnum()) ... ok
// or
if (isnum("123.")) ... ok</syntaxhighlight>
|-
|var=||v1.<em>num</em>()||Returns a copy of the var if it is numeric or 0 otherwise.
<em>Returns:</em> A guaranteed numeric var
Allows working numerically with data that may be non-numeric.
<syntaxhighlight lang="c++">
var v1 = "123.45"_var.num();    // 123.45
var v2 = "abc"_var.num() + 100; // 100</syntaxhighlight>
|-
|var=||v1.<em>operator+</em>(var)||Addition
Attempts to perform mumeric operations on non-numeric strings will throw a runtime error VarNonNumeric.
Floating point numbers are implicitly converted to strings with no more than 12 significant digits of precision. This practically eliminates all floatng point rounding errors.
Internally, 0.1 + 0.2 looks like this using doubles.
0.10000000000000003 + 0.20000000000000004 -> 0.30000000000000004
<syntaxhighlight lang="c++">
var v1 = 0.1;
var v2 = v1 + 0.2; // 0.3</syntaxhighlight>
|-
|var=||v1.<em>operator-</em>(var)||Subtraction
|-
|var=||v1.<em>operator*</em>(var)||Multiplication
|-
|var=||v1.<em>operator/</em>(var)||Division
|-
|var=||v1.<em>operator%</em>(var)||Modulus
|-
|var=||v1.<em>operator+=</em>(var)||Self addition
<syntaxhighlight lang="c++">
var v1 = 0.1;
v1 += 0.2; // 0.3</syntaxhighlight>
|-
|var=||v1.<em>operator-=</em>(var)||Self subtraction
|-
|var=||v1.<em>operator*=</em>(var)||Self multiplication
|-
|var=||v1.<em>operator/=</em>(var)||Self division
|-
|var=||v1.<em>operator%=</em>(var)||Self modulus
|-
|var=||v1.<em>operator++</em>(INT)||Post increment
<syntaxhighlight lang="c++">
var v1 = 3;
var v2 = v1 ++; // v2 -> 3 // v1 -> 4</syntaxhighlight>
|-
|var=||v1.<em>operator--</em>(INT)||Post decrement
<syntaxhighlight lang="c++">
var v1 = 3;
var v2 = v1 --; // v2 -> 3 // v1 -> 2</syntaxhighlight>
|-
|expr||v1.<em>operator++</em>()||Pre increment
<syntaxhighlight lang="c++">
var v1 = 3;
var v2 = ++ v1; // v2 -> 4 // v1 -> 4</syntaxhighlight>
|-
|expr||v1.<em>operator--</em>()||Pre decrement
<syntaxhighlight lang="c++">
var v1 = 3;
var v2 = -- v1; // v2 -> 2 // v1 -> 2</syntaxhighlight>
|}
=== Dynamic Array Creation, Access And Update ===
{|class="wikitable"
!Usage!!Function!!Description
|-
|var=||<em>""_var||The literal suffix "_var" allows dynamic arrays to be seamlessly embedded in code using the visible equivalents of unprintable field mark characters.
RM ` Record mark
FM ^ Field mark
VM ] Value mark
SM } Subvalue mark
TM | Text mark
ST ~ Subtext mark
<syntaxhighlight lang="c++">
var v1 = "f1^f2^v1]v2^f4"_var; // "f1" _FM "f2" _FM "v1" _VM "v2" _FM "f4"</syntaxhighlight>
|-
|var(std::initializer_list<T>||var <1 = {"a", "b", "c" ...}; // Initializer list||Create an dynamic array var from a list. C++ constrains list elements to be all the same type. var, string, double, int, etc.
<syntaxhighlight lang="c++">
var v1 = {11, 22, 33}; // "11^22^33"_var</syntaxhighlight>
|-
|var=||v1.<em>operator</em>()(fieldno)||Dynamic array - field update and append:
See also inserter() and remover().
<syntaxhighlight lang="c++">
var v1 = "aa^bb"_var;
v1(4) = 44; // v1 -> "aa^bb^^44"_var
// Field number -1 causes appending a field when updating.
v1(-1) = "55"; // v1 -> "aa^bb^^44^55"_var</syntaxhighlight>
Field access:
It is recommended to use "v1.f(fieldno)" syntax using a ".f(" prefix to access fields in expressions instead of plain "v1(fieldno)". The former syntax (using .f()) will always compile whereas the latter does not compile in all contexts. It will compile only if being called on a constant var or in a location which requires a var. This is due to C++ not making a clear distinction between usage on the left and right side of assignment operator =.
Furthermore using plain round brackets without the leading .f can be confused with function call syntax.
<syntaxhighlight lang="c++">
var v1 = "aa^bb^cc"_var;
var v2 = v1.f(2); // "bb" /// .f() style access. Recommended.
var v3 =  v1(2); // "bb" ///  () style access. Not recommended.</syntaxhighlight>
|-
|var=||v1.<em>operator</em>()(fieldno, valueno)||Dynamic array - value update and append
See also inserter() and remover().
<syntaxhighlight lang="c++">
var v1 = "aa^b1]b2^cc"_var;
v1(2, 4) = "44"; // v1 -> "aa^b1]b2]]44^cc"_var
// value number -1 causes appending a value when updating.
v1(2, -1) = 55; // v1 -> "aa^b1]b2]]44]55^cc"_var</syntaxhighlight>
Value access:
<syntaxhighlight lang="c++">
var v1 = "aa^b1]b2^cc"_var;
var v2 = v1.f(2,2); // "b2" /// .f() style access. Recommended.
var v3 =  v1(2,2); // "b2" ///  () style access. Not recommended.</syntaxhighlight>
|-
|var=||v1.<em>operator</em>()(fieldno, valueno = 0, subvalueno = 0)||Dynamic array - subvalue update and append
See also inserter() and remover().
<syntaxhighlight lang="c++">
var v1 = "aa^bb^cc"_var;
v1(2, 2, 2) = "22"; // v1 -> "aa^bb]}22^cc"_var
// subvalue number -1 causes appending a subvalue when updating.
v1(2, 2, -1) = 33; // v1 -> "aa^bb]}22}33^cc"_var</syntaxhighlight>
Subvalue access:
<syntaxhighlight lang="c++">
var v1 = "aa^b1]b2}s2^cc"_var;
var v2 = v1.f(2, 2, 2); // "s2" /// .f() style access. Recommended.
var v3 =  v1(2, 2, 2); // "s2" ///  () style access. Not recommended.</syntaxhighlight>
|}
=== String Creation  ===
{|class="wikitable"
!Usage!!Function!!Description
|-
|var=||v1.<em>operator^</em>(var)||String concatention operator ^
At least one side must be a var.
"aa" ^ "22" will not compile but "aa" "22".
Floating point numbers are implicitly converted to strings with no more than 12 significant digits of precision. This practically eliminates all floatng point rounding errors.
<syntaxhighlight lang="c++">
var v2 = "aa";
var v1 = v2 ^ 22; // "aa22"</syntaxhighlight>
|-
|var=||v1.<em>operator^=</em>(var)||String self concatention ^= (append)
<syntaxhighlight lang="c++">
var v1 = "aa";
v1 ^= 22; // v1 -> "aa22"</syntaxhighlight>
|-
|var=||varnum.<em>round</em>(ndecimals = 0)||Convert a number into a string after rounding it to a given number of decimal places.
<em>var:</em> The number to be converted.
<em>ndecimals:</em> Determines how many decimal places are shown to the right of the decimal point or, if ndecimals is negative, how many 0's to the left of it.
<em>Returns:</em> A var containing an ASCII string of digits with a leading "-" if negative, and a decimal point "." if ndecimals is > 0.
Trailing zeros are not omitted. A leading "0." is shown where appropriate.
0.5 always rounds away from zero. i.e. 1.5 -> 2 and -1.5 -> -2
<syntaxhighlight lang="c++">
let v1 = var(0.295).round(2);  //  "0.30"
// or
let v2 = round(1.295, 2);      //  "1.30"
var v3 = var(-0.295).round(2); // "-0.30"
// or
var v4 = round(-1.295, 2);    // "-1.30"</syntaxhighlight>
var v4 = round(0, 1);          // "0.0";
var v5 = round(0, 0);          // "0";
var v6 = round(0, -1);          // "0";
Negative number of decimals rounds to the left of the decimal point
<syntaxhighlight lang="c++">
let v1 = round(123456.789,  0); // "123457"
let v2 = round(123456.789, -1); // "123460"
let v3 = round(123456.789, -2); // "123500"</syntaxhighlight>
|-
|var=||var().<em>chr</em>(num)||Get a char given an integer 0-255.
<em>Returns:</em> A string containing a single char
0-127 -> ASCII, 128-255 -> invalid UTF-8 which cannot be written to the database or used in many exodus string operations
<syntaxhighlight lang="c++">
let v1 = var().chr(0x61); // "a"
// or
let v2 = chr(0x61);</syntaxhighlight>
|-
|var=||var().<em>textchr</em>(num)||Get a Unicode character given a Unicode Code Point (Number)
<em>Returns:</em> A single Unicode character in UTF8 encoding.
To get UTF code points > 2^63 you must provide negative ints because var doesnt provide an implicit constructor to unsigned int due to getting ambigious conversions because int and unsigned int are parallel priority in c++ implicit conversions.
<syntaxhighlight lang="c++">
let v1 = var().textchr(171416); // "𩶘" // or "\xF0A9B698"
// or
let v2 = textchr(171416);</syntaxhighlight>
|-
|var=||var().<em>str</em>(num)||Get a string of repeated substrings.
<em>var:</em> The substring to be repeated
<em>num:</em> How many times to repeat the substring
<em>Returns:</em> A string
<syntaxhighlight lang="c++">
let v1 = "ab"_var.str(3); // "ababab"
// or
let v2 = str("ab", 3);</syntaxhighlight>
|-
|var=||varnum.<em>space</em>()||Get a string containing a given number of spaces.
<em>var:</em> The number of spaces required.
<em>Returns:</em> A string of space chars.
<syntaxhighlight lang="c++">
let v1 = var(3).space(); // "␣␣␣"
// or
let v2 = space(3);</syntaxhighlight>
|-
|var=||varnum.<em>numberinwords</em>(languagename_or_locale_id = "")||Returns: A string representing a given number written in words instead of digits.
<em>locale:</em> Something like en_GB, ar_AE, el_CY, es_US, fr_FR etc.
<syntaxhighlight lang="c++">
let softhyphen = "\xc2\xad";
let v1 = var(123.45).numberinwords("de_DE").replace(softhyphen, " "); // "ein␣hundert␣drei␣und␣zwanzig␣Komma␣vier␣fünf"</syntaxhighlight>
|}
===== String Scanning =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|var=||strvar.<em>at</em>(pos1)||Get a single char from a string.
<em>pos1:</em> First char is 1. Last char is -1.
<em>Returns:</em> A single char if pos1 ± the length of the string, or "" if greater. Returns the first char if pos1 is 0 or (-pos1) > length.
<syntaxhighlight lang="c++">
var v1 = "abc";
var v2 = v1.at(2);  // "b"
var v3 = v1.at(-3); // "a"
var v4 = v1.at(4);  // ""</syntaxhighlight>
|-
|var=||strvar.<em>seq</em>()||Get the char number of a char
<em>Returns:</em> A number between 0 and 255.
If given a string, then only the first char is considered.
<syntaxhighlight lang="c++">
let v1 = "abc"_var.seq(); // 0x61 // decimal 97, 'a'
// or
let v2 = seq("abc");</syntaxhighlight>
|-
|var=||strvar.<em>textseq</em>()||Get the Unicode Code Point of a Unicode character.
<em>var:</em> A UTF-8 string. Only the first Unicode character is considered.
<em>Returns:</em> A number.
<syntaxhighlight lang="c++">
let v1 = "Γ"_var.textseq(); // 915 // U+0393: Greek Capital Letter Gamma (Unicode character)
// or
let v2 = textseq("Γ");</syntaxhighlight>
|-
|var=||strvar.<em>len</em>()||Get the length of a source string in number of chars
<em>Returns:</em> A number
<syntaxhighlight lang="c++">
let v1 = "abc"_var.len(); // 3
// or
let v2 = len("abc");</syntaxhighlight>
|-
|if||strvar.<em>empty</em>()||Checks if the var is an empty string.
<em>Returns:</em> True if it is empty amd false if not.
This is a shorthand and more expressive way of writing 'if (var == "")' or 'if (var.len() == 0)' or 'if (not var.len())'
Note that 'if (var.empty())' is not the same as 'if (not var)' because 'if (var("0.0")' is defined as false because the string can be converted to a 0 which is always considered to be false. Compare thia with common scripting languages where 'if (var("0"))' is defined as true.
<syntaxhighlight lang="c++">
let v1 = "0";
if (not v1.empty()) ... ok /// true
// or
if (not empty(v1)) ... ok // true</syntaxhighlight>
|-
|var=||strvar.<em>textwidth</em>()||Count the number of output columns required for a given source string.
<em>Returns:</em> A number
Allows wide multi-column Unicode characters that occupy more than one space in a text file or terminal screen.
Reduces combining characters to a single column. e.g. "e" followed by grave accent is multiple bytes but only occupies one output column.
Does not properly calculate all possible combining sequences of graphemes e.g. face followed by colour
<syntaxhighlight lang="c++">
let v1 = "🤡x🤡"_var.textwidth(); // 5
// or
let v2 = textwidth("🤡x🤡");</syntaxhighlight>
|-
|var=||strvar.<em>textlen</em>()||Count the number of Unicode code points in a source string.
<em>Returns:</em> A number.
<syntaxhighlight lang="c++">
let v1 = "Γιάννης"_var.textlen(); // 7
// or
let v2 = textlen("Γιάννης");</syntaxhighlight>
|-
|var=||strvar.<em>fcount</em>(sepstr)||Count the number of fields in a source string.
<em>sepstr:</em> The separator character or substr that delimits individual fields.
<em>Returns:</em> The count of the number of fields
This is similar to "var.count(sepstr) + 1" but it returns 0 for an empty source string.
<syntaxhighlight lang="c++">
let v1 = "aa**cc"_var.fcount("*"); // 3
// or
let v2 = fcount("aa**cc", "*");</syntaxhighlight>
|-
|var=||strvar.<em>count</em>(sepstr)||Count the number of occurrences of a given substr in a source string.
<em>substr:</em> The substr to count.
<em>Returns:</em> The count of the number of sepstr found.
Overlapping substrings are not counted.
<syntaxhighlight lang="c++">
let v1 = "aa**cc"_var.count("*"); // 2
// or
let v2 = count("aa**cc", "*");</syntaxhighlight>
|-
|if||strvar.<em>starts</em>(prefix)||Checks if a source string starts with a given prefix (substr).
<em>prefix:</em> The substr to check for.
<em>Returns:</em> True if the source string starts with the given prefix.
<em>Returns:</em> False if prefix is "". DIFFERS from c++, javascript, python3. See contains() for more info.
<syntaxhighlight lang="c++">
if ("abc"_var.starts("ab")) ... true
// or
if (starts("abc", "ab")) ... true</syntaxhighlight>
|-
|if||strvar.<em>ends</em>(suffix)||Checks if a source string ends with a given suffix (substr).
<em>suffix:</em> The substr to check for.
<em>Returns:</em> True if the source string ends with given suffix.
<em>Returns:</em> False if suffix is "". DIFFERS from c++, javascript, python3. See contains() for more info.
<syntaxhighlight lang="c++">
if ("abc"_var.ends("bc")) ... true
// or
if (ends("abc", "bc")) ... true</syntaxhighlight>
|-
|if||strvar.<em>contains</em>(substr)||Checks if a given substr exists in a source string.
<em>substr:</em> The substr to check for.
<em>Returns:</em> True if the source string starts with, ends with or contains the given substr.
<em>Returns:</em> False if suffix is "". DIFFERS from c++, javascript, python3
Human logic: "" is not equal to "x" therefore x does not contain "".
Human logic: Check each item (character) in the list for equality with what I am looking for and return success if any are equal.
Programmer logic: Compare as many characters as are in the search string for presence in the list of characters and return success if there are no failures.
<syntaxhighlight lang="c++">
if ("abcd"_var.contains("bc")) ... true
// or
if (contains("abcd", "bc")) ... true</syntaxhighlight>
|-
|var=||strvar.<em>index</em>(substr, startchar1 = 1)||Find a substr in a source string.
<em>substr:</em> The substr to search for.
<em>startchar1:</em> The char position (1 based) to start the search at. The default is 1, the first char.
<em>Returns:</em> The char position (1 based) that the substr is found at or 0 if not present.
<syntaxhighlight lang="c++">
let v1 = "abcd"_var.index("bc"); // 2
// or
let v2 = index("abcd", "bc");</syntaxhighlight>
|-
|var=||strvar.<em>indexn</em>(substr, occurrence)||Find the nth occurrence of a substr in a source string.
<em>substr:</em> The string to search for.
<em>Returns:</em> char position (1 based) or 0 if not present.
<syntaxhighlight lang="c++">
let v1 = "abcabc"_var.index("bc", 2); // 2
// or
let v2 = index("abcabc", "bc", 2);</syntaxhighlight>
|-
|var=||strvar.<em>indexr</em>(substr, startchar1 = -1)||Find the position of substr working backwards from the end of the string towards the beginning.
<em>substr:</em> The string to search for.
<em>Returns:</em> The char position of the substr if found, or 0 if not.
<em>startchar1:</em> defaults to -1 meaning start searching from the last char. Positive start1char1 counts from the beginning of the source string and negative startchar1 counts backwards from the last char.
<syntaxhighlight lang="c++">
let v1 = "abcabc"_var.indexr("bc"); // 5
// or
let v2 = indexr("abcabc", "bc");</syntaxhighlight>
|-
|var=||strvar.<em>match</em>(regex_str, regex_options = "")||Finds all matches of a given regular expression.
<em>Returns:</em> Zero or more matching substrings separated by FMs. Any groups are in VMs.
<syntaxhighlight lang="c++">
let v1 = "abc1abc2"_var.match("BC(\\d)", "i"); // "bc1]1^bc2]2"_var
// or
let v2 = match("abc1abc2", "BC(\\d)", "i");</syntaxhighlight>
<em>regex_options:</em>
<pre>
l - Literal (any regex chars are treated as normal chars)
i - Case insensitive
p - ECMAScript/Perl (the default)
b - Basic POSIX (same as sed)
e - Extended POSIX
a - awk
g - grep
eg - egrep or grep -E
char ranges like a-z are locale sensitive if ECMAScript
m - Multiline. Default in boost (and therefore exodus)
s - Single line. Default in std::regex
f - First only. Only for replace() (not match() or search())
w - Wildcard glob style (e.g. *.cfg) not regex style. Only for match() and search(). Not replace().
</pre>
|-
|var=||strvar.<em>match</em>(regex)||Ditto
|-
|var=||strvar.<em>search</em>(regex_str, io startchar1, regex_options = "")||Search for the first match of a regular expression.
<em>startchar1:</em> [in] char position to start the search from
<em>startchar1:</em> [out] char position to start the next search from
<em>Returns:</em> The 1st match like match()
regex_options as for match()
<syntaxhighlight lang="c++">
var startchar1 = 1;
let v1 = "abc1abc2"_var.search("BC(\\d)", startchar1, "i"); // "bc1]1"_var // startchar1 -> 5 /// Ready for the next search
// or
startchar1 = 1;
let v2 = search("abc1abc2", "BC(\\d)", startchar1, "i");</syntaxhighlight>
|-
|var=||strvar.<em>search</em>(regex_str)||Ditto starting from first char
|-
|var=||strvar.<em>search</em>(regex, io startchar1)||Ditto given a rex
|-
|var=||strvar.<em>search</em>(regex)||Ditto starting from first char.
|-
|var=||strvar.<em>hash</em>(std::uint64_t modulus = 0)||Get a hash of a source string.
<em>modulus:</em> The result is limited to [0, modulus)
<em>Returns:</em> A 64 bit signed integer.
MurmurHash3 is used.
<syntaxhighlight lang="c++">
let v1 = "abc"_var.hash(); assert(v1 == var(6'715'211'243'465'481'821));
// or
let v2 = hash("abc");</syntaxhighlight>
|}
===== String Conversion - Non-Mutating - Chainable =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|var=||strvar.<em>ucase</em>()||Convert to upper case
<syntaxhighlight lang="c++">
let v1 = "Γιάννης"_var.ucase(); // "ΓΙΆΝΝΗΣ"
// or
let v2 = ucase("Γιάννης");</syntaxhighlight>
|-
|var=||strvar.<em>lcase</em>()||Convert to lower case
<syntaxhighlight lang="c++">
let v1 = "ΓΙΆΝΝΗΣ"_var.lcase(); // "γιάννης"
// or
let v2 = lcase("ΓΙΆΝΝΗΣ");</syntaxhighlight>
|-
|var=||strvar.<em>tcase</em>()||Convert to title case.
<em>Returns:</em> Original source string with the first letter of each word is capitalised.
<syntaxhighlight lang="c++">
let v1 = "γιάννης παππάς"_var.tcase(); // "Γιάννης Παππάς"
// or
let v2 = tcase("γιάννης παππάς");</syntaxhighlight>
|-
|var=||strvar.<em>fcase</em>()||Convert to folded case.
Returns the source string standardised in a way to enable consistent indexing and searching,
Case folding is the process of converting text to a case independent representation.
https://www.w3.org/International/wiki/Case_folding
Accents can be significant. As in French cote, coté, côte and côté.
Case folding is not locale-dependent.
<syntaxhighlight lang="c++">
let v1 = "Grüßen"_var.fcase(); // "grüssen"
// or
let v2 = tcase("Grüßen");</syntaxhighlight>
|-
|var=||strvar.<em>normalize</em>()||Replace Unicode character sequences with their standardised NFC form.
Unicode normalization is the process of converting Unicode strings to a standard form, making them binary comparable and suitable for text processing and comparison. It is an important part of Unicode text processing.
For example, Unicode character "é" can be represented by either a single Unicode character, which is Unicode Code Point (\u00E9" - Latin Small Letter E with Acute), or a combination of two Unicode code points i.e. the ASCII letter "e" and a combining acute accent (Unicode Code Point "\u0301"). Unicode NFC definition converts the pair of code points to the single code point.
Normalization is not locale-dependent.
<syntaxhighlight lang="c++">
let v1 = "cafe\u0301"_var.normalize(); // "caf\u00E9" // "café"
// or
let v2 = normalize("cafe\u0301");</syntaxhighlight>
|-
|var=||strvar.<em>invert</em>()||Simple reversible disguising of string text.
It works by treating the string as UTF8 encoded Unicode code points and inverting the first 8 bits of their Unicode Code Points.
<em>Returns:</em> A string.
invert(invert()) returns to the original text.
ASCII bytes become multibyte UTF-8 so string sizes increase.
Inverted characters remain on their original Unicode Code Page but are jumbled up.
Non-existant Unicode Code Points may be created but UTF8 encoding remains valid.
<syntaxhighlight lang="c++">
let v1 = "abc"_var.invert(); // "\xC2" "\x9E" "\xC2" "\x9D" "\xC2" "\x9C"
// or
let v2 = invert("abc");</syntaxhighlight>
|-
|var=||strvar.<em>lower</em>()||Reduce all types of field mark chars by one level.
Convert all FM to VM, VM to SM etc.
<em>Returns:</em> The converted string.
Note that subtext ST chars are not converted because they are already the lowest level.
String size remains identical.
<syntaxhighlight lang="c++">
let v1 = "a1^b2^c3"_var.lower(); // "a1]b2]c3"_var
// or
let v2 = lower("a1^b2^c3"_var);</syntaxhighlight>
|-
|var=||strvar.<em>raise</em>()||Increase all types of field mark chars by one level.
Convert all VM to FM, SM to VM etc.
<em>Returns:</em> The converted string.
The record mark char RM is not converted because it is already the highest level.
String size remains identical.
<syntaxhighlight lang="c++">
let v1 = "a1]b2]c3"_var.raise(); // "a1^b2^c3"_var
// or
let v2 = "a1]b2]c3"_var;</syntaxhighlight>
|-
|var=||strvar.<em>crop</em>()||Remove any redundant FM, VM etc. chars (Trailing FM; VM before FM etc.)
<syntaxhighlight lang="c++">
let v1 = "a1^b2]]^c3^^"_var.crop(); // "a1^b2^c3"_var
// or
let v2 = crop("a1^b2]]^c3^^"_var);</syntaxhighlight>
|-
|var=||strvar.<em>quote</em>()||Wrap in double quotes.
<syntaxhighlight lang="c++">
let v1 = "abc"_var.quote(); // "\"abc\""
// or
let v2 = quote("abc");</syntaxhighlight>
|-
|var=||strvar.<em>squote</em>()||Wrap in single quotes.
<syntaxhighlight lang="c++">
let v1 = "abc"_var.squote(); // "'abc'"
// or
let v2 = squote("abc");</syntaxhighlight>
|-
|var=||strvar.<em>unquote</em>()||Remove one pair of surrounding double or single quotes.
<syntaxhighlight lang="c++">
let v1 = "'abc'"_var.unquote(); // "abc"
// or
let v2 = unquote("'abc'");</syntaxhighlight>
|-
|var=||strvar.<em>trim</em>(trimchars = " ")||Remove all leading, trailing and excessive inner bytes.
<em>trimchars:</em> The chars (bytes) to remove. The default is space.
<syntaxhighlight lang="c++">
let v1 = "␣␣a1␣␣b2␣c3␣␣"_var.trim(); // "a1␣b2␣c3"
// or
let v2 = trim("␣␣a1␣␣b2␣c3␣␣");</syntaxhighlight>
|-
|var=||strvar.<em>trimfirst</em>(trimchars = " ")||Ditto but only leading.
<syntaxhighlight lang="c++">
let v1 = "␣␣a1␣␣b2␣c3␣␣"_var.trimfirst(); // "a1␣␣b2␣c3␣␣"
// or
let v2 = trimfirst("␣␣a1␣␣b2␣c3␣␣");</syntaxhighlight>
|-
|var=||strvar.<em>trimlast</em>(trimchars = " ")||Ditto but only trailing.
<syntaxhighlight lang="c++">
let v1 = "␣␣a1␣␣b2␣c3␣␣"_var.trimlast(); // "␣␣a1␣␣b2␣c3"
// or
let v2 = trimlast("␣␣a1␣␣b2␣c3␣␣");</syntaxhighlight>
|-
|var=||strvar.<em>trimboth</em>(trimchars = " ")||Ditto but only leading and trailing, not inner.
<syntaxhighlight lang="c++">
let v1 = "␣␣a1␣␣b2␣c3␣␣"_var.trimboth(); // "a1␣␣b2␣c3"
// or
let v2 = trimboth("␣␣a1␣␣b2␣c3␣␣");</syntaxhighlight>
|-
|var=||strvar.<em>first</em>()||Get the first char of a string.
<em>Returns:</em> A char, or "" if empty.
Equivalent to var.substr(1,length) or var[1, length] in Pick OS
<syntaxhighlight lang="c++">
let v1 = "abc"_var.first(); // "a"
// or
let v2 = first("abc");</syntaxhighlight>
|-
|var=||strvar.<em>last</em>()||Get the last char of a string.
<em>Returns:</em> A char, or "" if empty.
Equivalent to var.substr(-1, 1) or var[-1, 1] in Pick OS
<syntaxhighlight lang="c++">
let v1 = "abc"_var.last(); // "c"
// or
let v2 = last("abc");</syntaxhighlight>
|-
|var=||strvar.<em>first</em>(std::size_t length)||Get the first n chars of a source string.
<em>length:</em> The number of chars (bytes) to get.
<em>Returns:</em> A string of up to n chars.
Equivalent to var.substr(1, length) or var[1, length] in Pick OS
<syntaxhighlight lang="c++">
let v1 = "abc"_var.first(2); // "ab"
// or
let v2 = first("abc", 2);</syntaxhighlight>
|-
|var=||strvar.<em>last</em>(std::size_t length)||Extract up to length trailing chars
Equivalent to var.substr(-length, length) or var[-length, length] in Pick OS
<syntaxhighlight lang="c++">
let v1 = "abc"_var.last(2); // "bc"
// or
let v2 = last("abc", 2);</syntaxhighlight>
|-
|var=||strvar.<em>cut</em>(length)||Remove n chars (bytes) from the source string.
<em>length:</em> Positive to remove first n chars or negative to remove the last n chars.
If the absolute value of length is >= the number of chars in the source string then all chars will be removed.
Equivalent to var.substr(length) or var[1, length] = "" in Pick OS
<syntaxhighlight lang="c++">
let v1 = "abcd"_var.cut(2); // "cd"
// or
let v2 = cut("abcd", 2);</syntaxhighlight>
|-
|var=||strvar.<em>paste</em>(pos1, length, insertstr)||Insert a substr at an given position after removing a given number of chars.
<em>pos1:</em> 0 or 1 : Remove length chars from the beginning and insert at the beginning.
<em>pos1:</em> > than the length of the source string. Insert after the last char.
<em>pos1:</em> -1 : Remove up to length chars before inserting.Insert on or before the last char.
<em>pos1:</em> -2 : Insert on or before the penultimate char.
Equivalent to var[pos1, length] = substr in Pick OS
<syntaxhighlight lang="c++">
let v1 = "abcd"_var.paste(2, 2, "XYZ"); // "aXYZd"
// or
let v2 = paste("abcd", 2, 2, "XYZ");</syntaxhighlight>
|-
|var=||strvar.<em>paste</em>(pos1, insertstr)||Insert text at char position without overwriting any following chars
Equivalent to var[pos1, 0] = substr in Pick OS
<syntaxhighlight lang="c++">
let v1 = "abcd"_var.paste(2, "XYZ"); // "aXYZbcd"
// or
let v2 = paste("abcd", 2, "XYZ");</syntaxhighlight>
|-
|var=||strvar.<em>prefix</em>(insertstr)||Insert text at the beginning
Equivalent to var[0, 0] = substr in Pick OS
<syntaxhighlight lang="c++">
let v1 = "abc"_var.prefix("XYZ"); // "XYZabc"
// or
let v2 = prefix("abc", "XYZ");</syntaxhighlight>
|-
|var=||strvar.<em>append</em>(appendable, ...)||Append anything at the end of a string
<syntaxhighlight lang="c++">
let v1 = "abc"_var.append(" is ", 10, " ok", '.'); // "abc is 10 ok."
// or
let v2 = append("abc", " is ", 10, " ok", '.');</syntaxhighlight>
|-
|var=||strvar.<em>pop</em>()||Remove one trailing char.
Equivalent to var[-1, 1] = "" in Pick OS
<syntaxhighlight lang="c++">
let v1 = "abc"_var.pop(); // "ab"
// or
let v2 = pop("abc");</syntaxhighlight>
|-
|var=||strvar.<em>field</em>(delimiter, fieldnx = 1, nfieldsx = 1)||Copies one or more consecutive fields from a string given a delimiter
<em>delimiter:</em> A Unicode character.
<em>fieldno:</em> The first field is 1, the last field is -1.
<em>Returns:</em> A substring
<syntaxhighlight lang="c++">
let v1 = "aa*bb*cc"_var.field("*", 2); // "bb"
// or
let v2 = field("aa*bb*cc", "*", 2);</syntaxhighlight>
<syntaxhighlight lang="c++">
let v1 = "aa*bb*cc"_var.field("*", -1); // "cc"
// or
let v2 = field("aa*bb*cc", "*", -1);</syntaxhighlight>
|-
|var=||strvar.<em>fieldstore</em>(separator, fieldno, nfields, replacement)||fieldstore() replaces, inserts or deletes subfields in a string.
<em>fieldno:</em> The field number to replace or, if not 1, the field number to start at. Negative fieldno counts backwards from the last field.
<em>nfields:</em> The number of fields to replace or, if negative, the number of fields to delete first. Can be 0 to cause simple insertion of fields.
<em>replacement:</em> A string that is the replacement field or fields.
<em>Returns:</em> A modified copy of the original string.
There is no way to simply delete n fields because the replacement argument cannot be omitted, however one can achieve the same result by replacing n+1 fields with the n+1th field.
The replacement can contain multiple fields itself. If replacing n fields and the replacement contains < n fields then the remaining fields become "", and if the replacement contains more fields than are required, they are unused.
<syntaxhighlight lang="c++">
let v1 = "aa,bb,cc,dd,ee"_var.fieldstore(",", 2, 3, "11,22"); // "aa,11,22,,ee"
// or
let v2 = fieldstore("aa,bb,cc,dd,ee", ",", 2, 3, "11,22");</syntaxhighlight>
If nfields is 0 then insert the replacement field(s) before fieldno
<syntaxhighlight lang="c++">
let v1 = "aa,bb,cc,dd,ee"_var.fieldstore(",", 2, 0, "11,22"); // "aa,11,22,bb,cc,dd,ee"</syntaxhighlight>
If nfields is negative then delete abs(n) fields before inserting whatever fields the replacement has.
<syntaxhighlight lang="c++">
let v1 = "aa,bb,cc,dd,ee"_var.fieldstore(",", 2, -2, "11"); // "aa,11,dd,ee"</syntaxhighlight>
If nfields exceeds the number of fields in the input then additional empty fields are added.
<syntaxhighlight lang="c++">
let v1 = "aa,bb,cc"_var.fieldstore(",", 6, 2, "11"); // "aa,bb,cc,,,11,"</syntaxhighlight>
|-
|var=||strvar.<em>substr</em>(pos1, length)||substr version 1.
Copies a substr of length chars from a given a starting char position.
<em>Returns:</em> A substr or "".
<em>pos1:</em> The char position to start at. If negative then start from a position counting backwards from the last char
<em>length:</em> The number of chars to copy. If negative then copy backwards. This reverses the order of the chars in the returned substr.
Equivalent to var[start, length] in Pick OS
Not Unicode friendly.
<syntaxhighlight lang="c++">
let v1 = "abcd"_var.substr(2, 2); // "bc"
// or
let v2 = substr("abcd", 2, 2);</syntaxhighlight>
If pos1 is negative then start counting backwards from the last char
<syntaxhighlight lang="c++">
let v1 = "abcd"_var.substr(-3, 2); // "bc"
// or
let v2 = substr("abcd", -3, 2);</syntaxhighlight>
If length is negative then work backwards and return chars reversed
<syntaxhighlight lang="c++">
let v1 = "abcd"_var.substr(3, -2); // "cb"
// or
let v2 = substr("abcd", 3, -2); // "cb"</syntaxhighlight>
|-
|var=||strvar.<em>b</em>(pos1, length)||Abbreviated alias of substr version 1.
|-
|var=||strvar.<em>substr</em>(pos1)||substr version 2.
Copies a substr from a given char position up to the end of the source string
<em>Returns:</em> A substr or "".
<em>pos1:</em> The char position to start at. If negative then start from a position counting backwards from the last char
Equivalent to var[pos1, 9999999] in Pick OS
Partially Unicode friendly but pos1 is in chars.
<syntaxhighlight lang="c++">
let v1 = "abcd"_var.substr(2); // "bcd"
// or
let v2 = substr("abcd", 2);</syntaxhighlight>
|-
|var=||strvar.<em>b</em>(pos1)||Shorthand alias of substr version 2.
|-
|var=||strvar.<em>substr</em>(pos1, delimiterchars, out pos2)||substr version 3.
Copies a substr from a given char position up to (but excluding) any one of some given delimiter chars
<em>Returns:</em> A substr or "".
<em>pos1:</em> [in] The position of the first char to copy. Negative positions count backwards from the last char of the string.
<em>pos2:</em> [out] The position of the next delimiter char, or one char position after the end of the source string if no subsequent delimiter chars are found.
<em>COL2:</em> is a predefined variable that can be used for pos2 instead of declaring a variable.
An empty string may be returned if pos1 [in] points to one of the delimiter chars or points beyond the end of the source string.
Equivalent to var[pos1, ",."] in Pick OS (non-numeric length).
Works with any encoding including UTF8 for the source string but the delimiter chars are bytes.
Add 1 to pos2 to skip over the next delimiter char to copy the next substr
Works with any encoding including UTF8 for the source string but the delimiter chars are bytes.
This function is similar to std::string::find_first_of but that function only returns pos2.
<syntaxhighlight lang="c++">
var pos1 = 4;
let v1 = "12,45 78"_var.substr(pos1, ", ", COL2);  // v1 -> "45" // COL2 -> 6 // 6 is the position of the next delimiter char found.
// or
let v2 = substr("12,45 78", COL2 + 1, ", ", COL2); // v2 -> "78" // COL2 -> 9 // 9 is one after the end of the string meaning that none of the delimiter chars were found.</syntaxhighlight>
|-
|var=||strvar.<em>b</em>(pos1, delimiterchars, out pos2)||Shorthand alias of substr version 3.
|-
|var=||strvar.<em>substr2</em>(io pos1, out delimiterno)||substr version 4.
Copies a substr from a given char position up to (but excluding) the next field mark char (RM, FM, VM, SM, TM, ST).
<em>Returns:</em> A substr or "".
<em>pos1:</em> [in] The position of the first char to copy. Negative positions count backwards from the last char of the string.
<em>pos1:</em> [out] The position of the first char of the next substr after whatever field mark char is found, or one char position after the end of the source string if no subsequent field mark char is found.
<em>field_mark_no:</em> [out] A number (1-6) indicating which of the standard field mark chars was found, or 0 if not.
An empty string may be returned if the pos1 [in] points to one of the field marks or beyond the end of the source string.
pos1 [out] is correctly positioned to copy the next substr.
Works with any encoding including UTF8. Was called "remove" in Pick OS.
The equivalent in Pick OS was the statement "Remove variable From string At column Setting flag"
...
This function is valuable for high performance processing of dynamic arrays.
It is notably used in "list" to print parallel columns of mixed combinations of multivalues/subvalues and text marks correctly lined up mv to mv, sv to sv, tm to tm even when particular values, subvalues and text fragments are missing from particular columns.
It is similar to version 3 of substr - substr(pos1, delimiterchars, pos2) except that in this version the delimiter chars are hard coded as the standard field mark chars (RM, FM, VM, SM, TM, ST) and it returns the first char position of the next substr, not the char position of the next field mark char.
<syntaxhighlight lang="c++">
var pos1 = 4, field_mark_no;
let v1 = "12^45^78"_var.substr2(pos1, field_mark_no);  // "45" // pos1 -> 7 // field_mark_no -> 2 // field_mark_no 2 means that a FM was found.
// or
let v2 = substr2("12^45^78"_var, pos1, field_mark_no); // "78" // pos1 -> 9 // field_mark_no -> 0 // field_mark_no 0 means that none of the standard field marks were found.</syntaxhighlight>
|-
|var=||strvar.<em>b2</em>(io pos1, out field_mark_no)||Shorthand alias of substr version 4.
|-
|var=||strvar.<em>convert</em>(from_chars, to_chars)||Convert or delete chars one for one to other chars
<em>from_chars:</em> chars to convert. If longer than to_chars then delete those characters instead of converting them.
<em>to_chars:</em> chars to convert to
Not UTF8 compatible.
<syntaxhighlight lang="c++">
let v1 = "abcde"_var.convert("aZd", "XY"); // "Xbce" // a is replaced and d is removed
// or
let v2 = convert("abcde", "aZd", "XY");</syntaxhighlight>
|-
|var=||strvar.<em>textconvert</em>(from_characters, to_characters)||Ditto for Unicode code points.
<syntaxhighlight lang="c++">
let v1 = "a🤡b😀c🌍d"_var.textconvert("🤡😀", "👋"); // "a👋bc🌍d"
// or
let v2 = textconvert("a🤡b😀c🌍d", "🤡😀", "👋");</syntaxhighlight>
|-
|var=||strvar.<em>replace</em>(fromstr, tostr)||Replace all occurrences of one substr with another.
Case sensitive.
<syntaxhighlight lang="c++">
let v1 = "Abc.Abc"_var.replace("bc", "X"); // "AX.AX"
// or
let v2 = replace("Abc Abc", "bc", "X");</syntaxhighlight>
|-
|var=||strvar.<em>replace</em>(regex, tostr)||Replace substring(s) using a regular expression.
Use $0, $1, $2 in tostr to refer to groups defined in the regex.
<syntaxhighlight lang="c++">
let v1 = "A a B b"_var.replace("[A-Z]"_rex, "'$0'"); // "'A' a 'B' b"
// or
let v2 = replace("A a B b", "[A-Z]"_rex, "'$0'");</syntaxhighlight>
|-
|var=||strvar.<em>unique</em>()||Remove duplicate fields in an FM or VM etc. separated list
<syntaxhighlight lang="c++">
let v1 = "a1^b2^a1^c2"_var.unique(); // "a1^b2^c2"_var
// or
let v2 = unique("a1^b2^a1^c2"_var);</syntaxhighlight>
|-
|var=||strvar.<em>sort</em>(delimiter = FM)||Reorder fields in an FM or VM etc. separated list in ascending order
Numeric data:
<syntaxhighlight lang="c++">
let v1 = "20^10^2^1^1.1"_var.sort(); // "1^1.1^2^10^20"_var
// or
let v2 = sort("20^10^2^1^1.1"_var);</syntaxhighlight>
Alphabetic data:
<syntaxhighlight lang="c++">
let v1 = "b1^a1^c20^c10^c2^c1^b2"_var.sort(); // "a1^b1^b2^c1^c10^c2^c20"_var
// or
let v2 = sort("b1^a1^c20^c10^c2^c1^b2"_var);</syntaxhighlight>
|-
|var=||strvar.<em>reverse</em>(delimiter = FM)||Reorder fields in an FM or VM etc. separated list in descending order
<syntaxhighlight lang="c++">
let v1 = "20^10^2^1^1.1"_var.reverse(); // "1.1^1^2^10^20"_var
// or
let v2 = reverse("20^10^2^1^1.1"_var);</syntaxhighlight>
|-
|var=||strvar.<em>shuffle</em>(delimiter = FM)||Randomise the order of fields in an FM, VM separated list
<syntaxhighlight lang="c++">
let v1 = "20^10^2^1^1.1"_var.shuffle(); /// e.g. "2^1^20^1.1^10" (random order depending on initrand())
// or
let v2 = shuffle("20^10^2^1^1.1"_var);</syntaxhighlight>
|-
|var=||strvar.<em>parse</em>(char sepchar = ' ')||Split a delimited string with embedded quotes into a dynamic array.
Can be used to process CSV data.
Replaces separator chars with FM chars except inside double or single quotes and ignoring escaped quotes &bsol;" &bsol;'
<syntaxhighlight lang="c++">
let v1 = "abc,\"def,\"123\" fgh\",12.34"_var.parse(','); // "abc^\"def,\"123\" fgh\"^12.34"_var
// or
let v2 = parse("abc,\"def,\"123\" fgh\",12.34", ',');</syntaxhighlight>
|-
|dim||strvar.<em>split</em>(delimiter = FM)||Split a delimited string into a dim array.
The delimiter can be multibyte Unicode.
<syntaxhighlight lang="c++">
dim d1 = "a^b^c"_var.split(); // A dimensioned array with three elements (vars)
// or
dim d2 = split("a^b^c"_var);</syntaxhighlight>
|}
===== String Mutation - Standalone Commands =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|cmd||strvar.<em>ucaser</em>()||Upper case
All string mutators follow the same pattern as ucaser.<br>See the non-mutating functions for details.
<syntaxhighlight lang="c++">
var v1 = "abc";
v1.ucaser(); // "ABC"
// or
ucaser(v1);</syntaxhighlight>
|-
|cmd||strvar.<em>lcaser</em>()||
|-
|cmd||strvar.<em>tcaser</em>()||
|-
|cmd||strvar.<em>fcaser</em>()||
|-
|cmd||strvar.<em>normalizer</em>()||
|-
|cmd||strvar.<em>inverter</em>()||
|-
|cmd||strvar.<em>quoter</em>()||
|-
|cmd||strvar.<em>squoter</em>()||
|-
|cmd||strvar.<em>unquoter</em>()||
|-
|cmd||strvar.<em>lowerer</em>()||
|-
|cmd||strvar.<em>raiser</em>()||
|-
|cmd||strvar.<em>cropper</em>()||
|-
|cmd||strvar.<em>trimmer</em>(trimchars = " ")||
|-
|cmd||strvar.<em>trimmerfirst</em>(trimchars = " ")||
|-
|cmd||strvar.<em>trimmerlast</em>(trimchars = " ")||
|-
|cmd||strvar.<em>trimmerboth</em>(trimchars = " ")||
|-
|cmd||strvar.<em>firster</em>()||
|-
|cmd||strvar.<em>laster</em>()||
|-
|cmd||strvar.<em>firster</em>(std::size_t length)||
|-
|cmd||strvar.<em>laster</em>(std::size_t length)||
|-
|cmd||strvar.<em>cutter</em>(length)||
|-
|cmd||strvar.<em>paster</em>(pos1, length, insertstr)||
|-
|cmd||strvar.<em>paster</em>(pos1, insertstr)||
|-
|cmd||strvar.<em>prefixer</em>(insertstr)||
|-
|cmd||strvar.<em>appender</em>(appendable, ...)||
|-
|cmd||strvar.<em>popper</em>()||
|-
|cmd||strvar.<em>fieldstorer</em>(delimiter, fieldno, nfields, replacement)||
|-
|cmd||strvar.<em>substrer</em>(pos1, length)||
|-
|cmd||strvar.<em>substrer</em>(pos1)||
|-
|cmd||strvar.<em>converter</em>(from_chars, to_chars)||
|-
|cmd||strvar.<em>textconverter</em>(from_characters, to_characters)||
|-
|cmd||strvar.<em>replacer</em>(regex, tostr)||
|-
|cmd||strvar.<em>replacer</em>(fromstr, tostr)||
|-
|cmd||strvar.<em>uniquer</em>()||
|-
|cmd||strvar.<em>sorter</em>(delimiter = FM)||
|-
|cmd||strvar.<em>reverser</em>(delimiter = FM)||
|-
|cmd||strvar.<em>shuffler</em>(delimiter = FM)||
|-
|cmd||strvar.<em>parser</em>(char sepchar = ' ')||
|}
===== I/O Conversion =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|var=||var.<em>oconv</em>(convstr)||Converts internal data to output external display format according to a given conversion code or pattern
If the internal data is invalid and cannot be converted then most conversions return the ORIGINAL data unconverted
Throws a runtime error VarNotImplemented if convstr is invalid
See [[#ICONV/OCONV PATTERNS]]
<syntaxhighlight lang="c++">
let v1 = var(30123).oconv("D/E"); // "21/06/2050"
// or
let v2 = oconv(30123, "D/E");</syntaxhighlight>
|-
|var=||var.<em>iconv</em>(convstr)||Converts external data to internal format according to a given conversion code or pattern
If the external data is invalid and cannot be converted then most conversions return the EMPTY STRING ""
Throws a runtime error VarNotImplemented if convstr is invalid
See [[#ICONV/OCONV PATTERNS]]
<syntaxhighlight lang="c++">
let v1 = "21 JUN 2050"_var.iconv("D/E"); // 30123
// or
let v2 = iconv("21 JUN 2050", "D/E");</syntaxhighlight>
|-
|var=||var.<em>format</em>(fmt_str, args, ...)||Classic format function in printf style
vars can be formatted either with C++ format codes e.g. {:_>8.2f}
or with exodus oconv codes e.g. {::MD20P|R(_)#8} as in the below example.
<syntaxhighlight lang="c++">
let v1 = var(12.345).format("'{:_>8.2f}'"); // "'___12.35'"
let v2 = var(12.345).format("'{::MD20P|R(_)#8}'");
// or
var v3 = format("'{:_>8.2f}'", var(12.345)); // "'___12.35'"
var v4 = format("'{::MD20P|R(_)#8}'", var(12.345));</syntaxhighlight>
|-
|var=||strvar.<em>from_codepage</em>(codepage)||Converts from codepage encoded text to UTF-8 encoded text
e.g. Codepage "CP1124" (Ukrainian).
Use Linux command "iconv -l" for complete list of code pages and encodings.
<syntaxhighlight lang="c++">
let v1 = "\xa4"_var.from_codepage("CP1124"); // "Є"
// or
let v2 = from_codepage("\xa4", "CP1124");
// U+0404 Cyrillic Capital Letter Ukrainian Ie Unicode character</syntaxhighlight>
|-
|var=||strvar.<em>to_codepage</em>(codepage)||Converts to codepage encoded text from UTF-8 encoded text
<syntaxhighlight lang="c++">
let v1 = "Є"_var.to_codepage("CP1124").oconv("HEX"); // "A4"
// or
let v2 = to_codepage("Є", "CP1124").oconv("HEX");</syntaxhighlight>
|}
===== Dynamic Array Functions =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|var=||strvar.<em>f</em>(fieldno, valueno = 0, subvalueno = 0)||f() is a highly abbreviated alias for the Pick OS field/value/subvalue extract() function.
"f()" can be thought of as "field" although the function can extract values and subvalues as well.
The convenient Pick OS angle bracket syntax for field extraction (e.g. xxx<20>) is not available in C++.
The abbreviated exodus field extraction function (e.g. xxx.f(20)) is provided instead since field access is extremely heavily used in source code.
<syntaxhighlight lang="c++">
let v1 = "f1^f2v1]f2v2]f2v3^f2"_var;
let v2 = v1.f(2, 2); // "f2v2"</syntaxhighlight>
|-
|var=||strvar.<em>extract</em>(fieldno, valueno = 0, subvalueno = 0)||Extract a specific field, value or subvalue from a dynamic array.
<syntaxhighlight lang="c++">
let v1 = "f1^f2v1]f2v2]f2v3^f2"_var;
let v2 = v1.extract(2, 2); // "f2v2"
//
// For brevity the function alias "f()" (standing for "field") is normally used instead of "extract()" as follows:
var v3 = v1.f(2, 2);</syntaxhighlight>
|-
|var=||strvar.<em>pickreplace</em>(fieldno, valueno, subvalueno, replacement)||Same as var.r() function but returns a new string instead of updating a variable in place.<br>Rarely used.
|-
|var=||strvar.<em>pickreplace</em>(fieldno, valueno, replacement)||Ditto for a specific multivalue
|-
|var=||strvar.<em>pickreplace</em>(fieldno, replacement)||Ditto for a specific field
|-
|var=||strvar.<em>insert</em>(fieldno, valueno, subvalueno, insertion)||Same as var.inserter() function but returns a new string instead of updating a variable in place.
|-
|var=||strvar.<em>insert</em>(fieldno, valueno, insertion)||Ditto for a specific multivalue
|-
|var=||strvar.<em>insert</em>(fieldno, insertion)||Ditto for a specific field
|-
|var=||strvar.<em>remove</em>(fieldno, valueno = 0, subvalueno = 0)||Same as var.remover() function but returns a new string instead of updating a variable in place.
"remove" was called "delete" in Pick OS.
|}
===== Dynamic Array Filters =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|var=||strvar.<em>sum</em>()||Sum up multiple values into one higher level
<syntaxhighlight lang="c++">
let v1 = "1]2]3^4]5]6"_var.sum(); // "6^15"_var
// or
let v2 = sum("1]2]3^4]5]6"_var);</syntaxhighlight>
|-
|var=||strvar.<em>sumall</em>()||Sum up all levels into a single figure
<syntaxhighlight lang="c++">
let v1 = "1]2]3^4]5]6"_var.sumall(); // 21
// or
let v2 = sumall("1]2]3^4]5]6"_var);</syntaxhighlight>
|-
|var=||strvar.<em>sum</em>(delimiter)||Ditto allowing commas etc.
<syntaxhighlight lang="c++">
let v1 = "10,20,30"_var.sum(","); // 60
// or
let v2 = sum("10,20,30", ",");</syntaxhighlight>
|-
|var=||strvar.<em>mv</em>(opcode, var2)||Binary ops (+, -, *, /) in parallel on multiple values
<syntaxhighlight lang="c++">
let v1 = "10]20]30"_var.mv("+","2]3]4"_var); // "12]23]34"_var</syntaxhighlight>
|}
===== Dynamic Array Mutators Standalone Commands =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|cmd||strvar.<em>r</em>(fieldno, replacement)||Replaces a specific field in a dynamic array
<syntaxhighlight lang="c++">
var v1 = "f1^v1]v2}s2}s3^f3"_var;
v1.r(2, "X"); // "f1^X^f3"_var</syntaxhighlight>
|-
|cmd||strvar.<em>r</em>(fieldno, valueno, replacement)||Ditto for specific value in a specific field.
<syntaxhighlight lang="c++">
var v1 = "f1^v1]v2}s2}s3^f3"_var;
v1.r(2, 2, "X"); // "f1^v1]X^f3"_var</syntaxhighlight>
|-
|cmd||strvar.<em>r</em>(fieldno, valueno, subvalueno, replacement)||Ditto for a specific subvalue in a specific value of a specific field
<syntaxhighlight lang="c++">
var v1 = "f1^v1]v2}s2}s3^f3"_var;
v1.r(2, 2, 2, "X"); // "f1^v1]v2}X}s3^f3"_var</syntaxhighlight>
|-
|cmd||strvar.<em>inserter</em>(fieldno, insertion)||Insert a specific field in a dynamic array, moving all other fields up.
<syntaxhighlight lang="c++">
var v1 = "f1^v1]v2}s2}s3^f3"_var;
v1.inserter(2, "X"); // "f1^X^v1]v2}s2}s3^f3"_var
// or
inserter(v1, 2, "X");</syntaxhighlight>
|-
|cmd||strvar.<em>inserter</em>(fieldno, valueno, insertion)||Ditto for a specific value in a specific field, moving all other values up.
<syntaxhighlight lang="c++">
var v1 = "f1^v1]v2}s2}s3^f3"_var;
v1.inserter(2, 2, "X"); // "f1^v1]X]v2}s2}s3^f3"_var
// or
inserter(v1, 2, 2, "X");</syntaxhighlight>
|-
|cmd||strvar.<em>inserter</em>(fieldno, valueno, subvalueno, insertion)||Ditto for a specific subvalue in a dynamic array, moving all other subvalues up.
<syntaxhighlight lang="c++">
var v1 = "f1^v1]v2}s2}s3^f3"_var;
v1.inserter(2, 2, 2, "X"); // "f1^v1]v2}X}s2}s3^f3"_var
// or
v1.inserter(2, 2, 2, "X");</syntaxhighlight>
|-
|cmd||strvar.<em>remover</em>(fieldno, valueno = 0, subvalueno = 0)||Remove a specific field (or value, or subvalue) from a dynamic array, moving all other fields (or values, or subvalues)  down.
<syntaxhighlight lang="c++">
var v1 = "f1^v1]v2}s2}s3^f3"_var;
v1.remover(2, 2); // "f1^v1^f3"_var
// or
remover(v1, 2, 2);</syntaxhighlight>
|}
===== Dynamic Array Search =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|var=||strvar.<em>locate</em>(target)||locate() with only the target substr argument provided searches unordered values separated by any of the field mark chars.
<em>Returns:</em> The field, value, subvalue etc. number if found or 0 if not.
Searching for empty fields, values etc. (i.e. "") will work. Locating "" in "]yy" will return 1, in "xx]]zz" 2, and in "xx]yy]" 3, however, locating "" in "xx" will return 0 because there is conceptually no empty value in "xx". Locate "" in "" will return 1.
<syntaxhighlight lang="c++">
if ("UK^US^UA"_var.locate("US")) ... ok // 2
// or
if (locate("US", "UK^US^UA"_var)) ... ok</syntaxhighlight>
|-
|if||strvar.<em>locate</em>(target, out valueno)||locate() with only the target substr provided and setting returned searches unordered values separated by any type of field mark chars.
<em>Returns:</em> True if found
<em>Setting:</em> Field, value, subvalue etc. number if found or the max number + 1 if not. Suitable for additiom of new values
<syntaxhighlight lang="c++">
var setting;
if ("UK]US]UA"_var.locate("US", setting)) ... ok // setting -> 2
// or
if (locate("US", "UK]US]UA"_var, setting)) ... ok</syntaxhighlight>
|-
|if||strvar.<em>locate</em>(target, out setting, fieldno, valueno = 0)||locate() the target in unordered fields if fieldno is 0, or values if a fieldno is specified, or subvalues if the valueno argument is provided.
<em>Returns:</em> True if found and with the field, value or subvalue number in setting.
<em>Returns:</em> False if not found and with the max field, value or subvalue number found + 1 in setting. Suitable for replacement of new fields, values or subvalues.
<syntaxhighlight lang="c++">
var setting;
if ("f1^f2v1]f2v2]s1}s2}s3}s4^f3^f4"_var.locate("s4", setting, 2, 3)) ... ok // setting -> 4 // returns true</syntaxhighlight>
|-
|if||strvar.<em>locateby</em>(ordercode, target, out valueno)||locateby() without fieldno or valueno arguments searches ordered values separated by VM chars.
The order code can be AL, DL, AR, DR meaning Ascending Left, Descending Right, Ascending Right, Ascending Left.
Left is used to indicate alphabetic order where 10 < 2.
Right is used to indicate numeric order where 10 > 2.
Data must be in the correct order for searching to work properly.
<em>Returns:</em> True if found.
In case the target is not exactly found then the correct value no for inserting the target is returned in setting.
<syntaxhighlight lang="c++">
var valueno; if ("aaa]bbb]ccc"_var.locateby("AL", "bb", valueno)) ... // valueno -> 2 // returns false and valueno = where it could be correctly inserted.</syntaxhighlight>
|-
|if||strvar.<em>locateby</em>(ordercode, target, out setting, fieldno, valueno = 0)||locateby() ordered as above but in fields if fieldno is 0, or values in a specific fieldno, or subvalues in a specific valueno.
<syntaxhighlight lang="c++">
var setting;
if ("f1^f2^aaa]bbb]ccc^f4"_var.locateby("AL", "bb", setting, 3)) ... // setting -> 2 // return false and where it could be correctly inserted.</syntaxhighlight>
|-
|if||strvar.<em>locateusing</em>(usingchar, target)||locate() a target substr in the whole unordered string using a given delimiter char returning true if found.
<syntaxhighlight lang="c++">
if ("AB,EF,CD"_var.locateusing(",", "EF")) ... ok</syntaxhighlight>
|-
|if||strvar.<em>locateusing</em>(usingchar, target, out setting, fieldno = 0, valueno = 0, subvalueno = 0)||locate() the target in a specific field, value or subvalue using a specified delimiter and unordered data
<em>Returns:</em> True If found and returns in setting the number of the delimited field found.
<em>Returns:</em> False if not found and returns in setting the maximum number of delimited fields + 1 if not found.
This is similar to the main locate command but the delimiter char can be specified e.g. a comma or TM etc.
<syntaxhighlight lang="c++">
var setting;
if ("f1^f2^f3c1,f3c2,f3c3^f4"_var.locateusing(",", "f3c2", setting, 3)) ... ok // setting -> 2 // returns true</syntaxhighlight>
|-
|if||strvar.<em>locatebyusing</em>(ordercode, usingchar, target, out setting, fieldno = 0, valueno = 0, subvalueno = 0)||locatebyusing() supports all the above features in a single function.
<em>Returns:</em> True if found.
|}
===== Database Access =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|if||conn.<em>connect</em>(conninfo = "")||For all db operations, the operative var can either be a db connection created with dbconnect() or be any var and a default connection will be established on the fly.
The db connection string (conninfo) parameters are merged from the following places in descending priority.
1. Provided in connect()'s conninfo argument. See 4. for the complete list of parameters.
2. Any environment variables EXO_HOST EXO_PORT EXO_USER EXO_DATA EXO_PASS EXO_TIME
3. Any parameters found in a configuration file at ~/.config/exodus/exodus.cfg
4. The default conninfo is "host=127.0.0.1 port=5432 dbname=exodus user=exodus password=somesillysecret connect_timeout=10"
Setting environment variable EXO_DBTRACE=1 will cause tracing of db interface including SQL commands.
<syntaxhighlight lang="c++">
let conninfo = "dbname=exodus user=exodus password=somesillysecret";
if (not conn.connect(conninfo)) ...;
// or
if (not connect()) ...
// or
if (not connect("exodus")) ...</syntaxhighlight>
|-
|if||conn.<em>attach</em>(filenames)||Attach (connect) specific files by name to specific connections.
It is not necessary to attach files before opening them. Attach is meant to control the defaults.
For the remainder of the session, opening the db file by name without specifying a connection will automatically use the specified connection applies during the attach command.
If conn is not specified then filename will be attached to the default connection.
Multiple file names must be separated by FM
<syntaxhighlight lang="c++">
let filenames = "xo_clients^dict.xo_clients"_var, conn = "exodus";
if (conn.attach(filenames)) ... ok
// or
if (attach(filenames)) ... ok</syntaxhighlight>
|-
|cmd||conn.<em>detach</em>(filenames)||Detach (disconnect) files that have been attached using attach().
|-
|if||conn.<em>begintrans</em>()||Begin a db transaction.
<syntaxhighlight lang="c++">
if (not conn.begintrans()) ...
// or
if (not begintrans()) ...</syntaxhighlight>
|-
|if||conn.<em>statustrans</em>()||Check if a db transaction is in progress.
<syntaxhighlight lang="c++">
if (conn.statustrans()) ... ok
// or
if (statustrans()) ... ok</syntaxhighlight>
|-
|if||conn.<em>rollbacktrans</em>()||Rollback a db transaction.
<syntaxhighlight lang="c++">
if (conn.rollbacktrans()) ... ok
// or
if (rollbacktrans()) ... ok</syntaxhighlight>
|-
|if||conn.<em>committrans</em>()||Commit a db transaction.
<em>Returns:</em> True if successfully committed or if there was no transaction in progress, otherwise false.
<syntaxhighlight lang="c++">
if (conn.committrans()) ... ok
// or
if (committrans()) ... ok</syntaxhighlight>
|-
|if||conn.<em>sqlexec</em>(sqlcmd)||Execute an sql command.
<em>Returns:</em> True if there was no sql error otherwise lasterror() returns a detailed error message.
<syntaxhighlight lang="c++">
if (conn.sqlexec("select 1")) ... ok
// or
if (sqlexec("select 1")) ... ok</syntaxhighlight>
|-
|if||conn.<em>sqlexec</em>(sqlcmd, io response)||Execute an SQL command and capture the response.
<em>Returns:</em> True if there was no sql error otherwise response contains a detailed error message.
<em>response:</em> Any rows and columns returned are separated by RM and FM respectively. The first row is the column names.
<em>Recommended:</em> Don't use sql directly unless you must to manage or configure a database.
<syntaxhighlight lang="c++">
let sqlcmd = "select 'xxx' as col1, 'yyy' as col2";
var response;
if (conn.sqlexec(sqlcmd, response)) ... ok // response -> "col1^col2\x1fxxx^yyy"_var /// \x1f is the Record Mark (RM) char. The backtick char is used here by gendoc to deliminate source code.
// or
if (sqlexec(sqlcmd, response)) ... ok</syntaxhighlight>
|-
|cmd||conn.<em>disconnect</em>()||Closes db connection and frees process resources both locally and in the database server.
<syntaxhighlight lang="c++">
conn.disconnect();
// or
disconnect();</syntaxhighlight>
|-
|cmd||conn.<em>disconnectall</em>()||Closes all connections and frees process resources both locally and in the database server(s).
All connections are closed automatically when a process terminates.
<syntaxhighlight lang="c++">
conn.disconnectall();
// or
disconnectall();</syntaxhighlight>
|-
|var=||conn.<em>lasterror</em>()||Returns: The last os or db error message.
<syntaxhighlight lang="c++">
var v1 = var().lasterror();
// or
var v2 = lasterror();</syntaxhighlight>
|-
|var=||conn.<em>loglasterror</em>(source = "")||Log the last os or db error message.
<em>Output:</em> to stdlog
Prefixes the output with source if provided.
<syntaxhighlight lang="c++">
var().loglasterror("main:");
// or
loglasterror("main:");</syntaxhighlight>
|}
===== Database Management =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|if||conn.<em>dbcreate</em>(new_dbname, old_dbname = "")||Create a named database on a particular connection.
The target database cannot already exist.
Optionally copies an existing database from the same connection and which cannot have any current connections.
<syntaxhighlight lang="c++">
var conn = "exodus";
if (not dbdelete("xo_gendoc_testdb")) {}; // Cleanup first
if (conn.dbcreate("xo_gendoc_testdb")) ... ok
// or
if (dbcreate("xo_gendoc_testdb")) ...</syntaxhighlight>
|-
|if||conn.<em>dbcopy</em>(from_dbname, to_dbname)||Create a named database as a copy of an existing database.
The target database cannot already exist.
The source database must exist on the same connection and cannot have any current connections.
<syntaxhighlight lang="c++">
var conn = "exodus";
if (not dbdelete("xo_gendoc_testdb2")) {}; // Cleanup first
if (conn.dbcopy("xo_gendoc_testdb", "xo_gendoc_testdb2")) ... ok
// or
if (dbcopy("xo_gendoc_testdb", "xo_gendoc_testdb2")) ...</syntaxhighlight>
|-
|var=||conn.<em>dblist</em>()||Returns: A list of available databases on a particular connection.
<syntaxhighlight lang="c++">
let v1 = conn.dblist();
// or
let v2 = dblist();</syntaxhighlight>
|-
|if||conn.<em>dbdelete</em>(dbname)||Delete (drop) a named database.
The target database must exist and cannot have any current connections.
<syntaxhighlight lang="c++">
var conn = "exodus";
if (conn.dbdelete("xo_gendoc_testdb2")) ... ok
// or
if (dbdelete("xo_gendoc_testdb2")) ...</syntaxhighlight>
|-
|if||conn.<em>createfile</em>(filename)||Create a named db file.
<syntaxhighlight lang="c++">
let filename = "xo_gendoc_temp", conn = "exodus";
if (conn.createfile(filename)) ... ok
// or
if (createfile(filename)) ...</syntaxhighlight>
|-
|if||conn.<em>renamefile</em>(filename, newfilename)||Rename a db file.
<syntaxhighlight lang="c++">
let conn = "exodus", filename = "xo_gendoc_temp", new_filename = "xo_gendoc_temp2";
if (conn.renamefile(filename, new_filename)) ... ok
// or
if (renamefile(filename, new_filename)) ...</syntaxhighlight>
|-
|var=||conn.<em>listfiles</em>()||Returns: A list of all files in a database
<syntaxhighlight lang="c++">
var conn = "exodus";
if (not conn.listfiles()) ...
// or
if (not listfiles()) ...</syntaxhighlight>
|-
|if||conn.<em>clearfile</em>(filename)||Delete all records in a db file
<syntaxhighlight lang="c++">
let conn = "exodus", filename = "xo_gendoc_temp2";
if (not conn.clearfile(filename)) ...
// or
if (not clearfile(filename)) ...</syntaxhighlight>
|-
|if||conn.<em>deletefile</em>(filename)||Delete a db file
<syntaxhighlight lang="c++">
let conn = "exodus", filename = "xo_gendoc_temp2";
if (conn.deletefile(filename)) ... ok
// or
if (deletefile(filename)) ...</syntaxhighlight>
|-
|var=||conn_or_file.<em>reccount</em>(filename = "")||Returns: The approx. number of records in a db file
<syntaxhighlight lang="c++">
let conn = "exodus", filename = "xo_clients";
var nrecs1 = conn.reccount(filename);
// or
var nrecs2 = reccount(filename);</syntaxhighlight>
|-
|if||conn_or_file.<em>flushindex</em>(filename = "")||Calls db maintenance function (vacuum)
This doesnt actually flush any indexes but does make sure that reccount() function is reasonably accurate.
|}
===== Database File I/O =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|if||file.<em>open</em>(dbfilename, connection = "")||Opens a db file to a var which can be used in subsequent functions to work on the specified file and database connection.
<syntaxhighlight lang="c++">
var file, filename = "xo_clients";
if (not file.open(filename)) ...
// or
if (not open(filename to file)) ...</syntaxhighlight>
|-
|cmd||file.<em>close</em>()||Closes db file var
Does nothing currently since database file vars consume no resources
<syntaxhighlight lang="c++">
var file = "xo_clients";
file.close();
// or
close(file);</syntaxhighlight>
|-
|if||file.<em>createindex</em>(fieldname, dictfile = "")||Creates a secondary index for a given db file and field name.
The fieldname must exist in a dictionary file. The default dictionary is "dict." ^ filename.
<em>Returns:</em> False if the index cannot be created for any reason.
* Index already exists
* File does not exist
* The dictionary file does not have a record with a key of the given field name.
* The dictionary file does not exist. Default is "dict." ^ filename.
* The dictionary field defines a calculated field that uses an exodus function. Using a psql function is OK.
<syntaxhighlight lang="c++">
var filename = "xo_clients", fieldname = "DATE_CREATED";
if (not deleteindex("xo_clients", "DATE_CREATED")) {}; // Cleanup first
if (filename.createindex(fieldname)) ... ok
// or
if (createindex(filename, fieldname)) ...</syntaxhighlight>
|-
|var=||file|conn.<em>listindex</em>(file_or_filename = "", fieldname = "")||Lists secondary indexes in a database or for a db file
<em>Returns:</em> False if the db file or fieldname are given and do not exist
<syntaxhighlight lang="c++">
var conn = "exodus";
if (conn.listindex()) ... ok // includes "xo_clients__date_created"
// or
if (listindex()) ... ok</syntaxhighlight>
|-
|if||file.<em>deleteindex</em>(fieldname)||Deletes a secondary index for a db file and field name.
<em>Returns:</em> False if the index cannot be deleted for any reason
* File does not exist
* Index does not already exists
<syntaxhighlight lang="c++">
var file = "xo_clients", fieldname = "DATE_CREATED";
if (file.deleteindex(fieldname)) ... ok
// or
if (deleteindex(file, fieldname)) ...</syntaxhighlight>
|-
|var=||file.<em>lock</em>(key)||Places a metaphorical db lock on a particular record given a db file and key.
This is a advisory lock, not a physical lock, since it makes no restriction on the access or modification of data by other connections.
Neither the db file nor the record key need to actually exist since a lock is just a hash of the db file name and key combined.
If another connection attempts to place an identical lock on the same database it will be denied.
Locks can be removed by unlock() or unlockall() or will be automatically removed at the end of a transaction or when the connection is closed.
If the same process attempts to place an identical lock more than once it may be denied (if not in a transaction) or succeed but be ignored (if in a transaction).
Locks can be used to avoid processing a transaction simultaneously with another connection only to have one of them fail due to mutually updating the same records.
Returns::
* 0: Failure: Another connection has already placed the same lock.
* "" Failure: The lock has already been placed.
* 1: Success: A new lock has been placed.
* 2: Success: The lock has already been placed and the connection is in a transaction.
<syntaxhighlight lang="c++">
var file = "xo_clients", key = "1000";
if (file.lock(key)) ... ok
// or
if (lock(file, key)) ...</syntaxhighlight>
|-
|if||file.<em>unlock</em>(key)||Removes a db lock placed by the lock function.
Only locks placed on the specified connection can be removed.
Locks cannot be removed while a connection is in a transaction.
<em>Returns:</em> False if the lock is not present in a connection.
<syntaxhighlight lang="c++">
var file = "xo_clients", key = "1000";
if (file.unlock(key)) ... ok
// or
if (unlock(file, key)) ...</syntaxhighlight>
|-
|if||file.<em>unlockall</em>()||Removes all db locks placed by the lock function in the specified connection.
Locks cannot be removed while in a transaction.
<syntaxhighlight lang="c++">
var conn = "exodus";
if (not conn.unlockall()) ...
// or
if (not unlockall(conn)) ...</syntaxhighlight>
|-
|cmd||record.<em>write</em>(file, key)||Writes a record into a db file given a unique primary key.
Either inserts a new record or updates an existing record.
It always succeeds so no result code is returned.
Any memory cached record is deleted.
<syntaxhighlight lang="c++">
let record = "Client GD^G^20855^30000^1001.00^20855.76539"_var;
let file = "xo_clients", key = "GD001";
if (not deleterecord("xo_clients", "GD001")) {}; // Cleanup first
record.write(file, key);
// or
write(record on file, key);</syntaxhighlight>
|-
|if||record.<em>read</em>(file, key)||Reads a record from a db file for a given key.
<em>Returns:</em> False if the key doesnt exist
<em>var:</em> Contains the record if it exists or is unassigned if not.
<syntaxhighlight lang="c++">
var record;
let file = "xo_clients", key = "GD001";
if (not record.read(file, key)) ... // record -> "Client GD^G^20855^30000^1001.00^20855.76539"_var
// or
if (not read(record from file, key)) ...</syntaxhighlight>
|-
|if||file.<em>deleterecord</em>(key)||Deletes a record from a db file given a key.
<em>Returns:</em> False if the key doesnt exist
Any memory cached record is deleted.
<syntaxhighlight lang="c++">
let file = "xo_clients", key = "GD001";
if (file.deleterecord(key)) ... ok
// or
if (deleterecord(file, key)) ...</syntaxhighlight>
|-
|if||record.<em>insertrecord</em>(file, key)||Inserts a new record in a db file.
<em>Returns:</em> False if the key already exists
Any memory cached record is deleted.
<syntaxhighlight lang="c++">
let record = "Client GD^G^20855^30000^1001.00^20855.76539"_var;
let file = "xo_clients", key = "GD001";
if (record.insertrecord(file, key)) ... ok
// or
if (insertrecord(record on file, key)) ...</syntaxhighlight>
|-
|if||record.<em>updaterecord</em>(file, key)||Updates an existing record in a db file.
<em>Returns:</em> False if the key doesnt already exist
Any memory cached record is deleted.
<syntaxhighlight lang="c++">
let record = "Client GD^G^20855^30000^1001.00^20855.76539"_var;
let file = "xo_clients", key = "GD001";
if (not record.updaterecord(file, key)) ...
// or
if (not updaterecord(record on file, key)) ...</syntaxhighlight>
|-
|if||strvar.<em>readf</em>(file, key, fieldno)||"Read field" Same as read() but only returns a specific field number from the record.
<syntaxhighlight lang="c++">
var field, file = "xo_clients", key = "GD001", fieldno = 2;
if (not field.readf(file, key, fieldno)) ... // field -> "G"
// or
if (not readf(field from file, key, fieldno)) ...</syntaxhighlight>
|-
|cmd||strvar.<em>writef</em>(file, key, fieldno)||"write field" Same as write() but only writes to a specific field number in the record
<syntaxhighlight lang="c++">
var field = "f3", file = "xo_clients", key = "1000", fieldno = 3;
field.writef(file, key, fieldno);
// or
writef(field on file, key, fieldno);</syntaxhighlight>
|-
|cmd||record.<em>writec</em>(file, key)||"Write cache" Writes a record and key into a memory cached "db file".
The actual database file is NOT updated.
writec() either updates an existing cache record if the key already exists or otherwise inserts a new record into the cache.
It always succeeds so no result code is returned.
Neither the db file nor the record key need to actually exist in the actual db.
<syntaxhighlight lang="c++">
let record = "Client XD^X^20855^30000^1001.00^20855.76539"_var;
let file = "xo_clients", key = "XD001";
record.writec(file, key);
// or
writec(record on file, key);</syntaxhighlight>
|-
|if||record.<em>readc</em>(file, key)||"Read cache" Same as "read() but first reads from a memory cache.
1. Tries to read from a memory cache. Returns true if successful.
2a. Tries to read from the actual db file and returns false if unsuccessful.
2b. Writes the record and key to the memory cache and returns true.
Cached db file data lives in exodus process memory and is lost when the process terminates or cleardbcache() is called.
<syntaxhighlight lang="c++">
var record;
let file = "xo_clients", key = "XD001";
if (record.readc(file, key)) ... ok
// or
if (readc(record from file, key)) ... ok
// Verify not in actual database file by using read() not readc()
if (read(record from file, key)) abort("Error: " ^ key ^ " should not be in the actual database file"); // error</syntaxhighlight>
|-
|if||dbfile.<em>deletec</em>(key)||Deletes a record and key from a memory cached "file".
The actual database file is NOT updated.
<em>Returns:</em> False if the key doesnt exist
<syntaxhighlight lang="c++">
var file = "xo_clients", key = "XD001";
if (file.deletec(key)) ... ok
// or
if (deletec(file, key)) ...</syntaxhighlight>
|-
|cmd||conn.<em>cleardbcache</em>()||Clears the memory cache of all records for the given connection
All future cache readc() function calls will be forced to obtain records from the actual database and refresh the cache.
<syntaxhighlight lang="c++">
conn.cleardbcache();
// or
cleardbcache(conn);</syntaxhighlight>
|-
|var=||strvar.<em>xlate</em>(filename, fieldno, mode)||The xlate ("translate") function is similar to readf() but, when called as an exodus program member function, it can be used efficiently with exodus file dictionaries using column names and functions and multivalued data.
<em>Arguments:</em>
<em>strvar:</em> Used as the primary key to lookup a field in a given file and field no or field name.
<em>filename:</em> The db file in which to look up data.
If var key is multivalued then a multivalued field is returned.
<em>fieldno:</em> Determines which field of the record is returned.
* Integer returns that field number
* 0 means return the key unchanged.
* "" means return the whole record.
<em>mode:</em> Determines what is returned if the record does not exist for the given key and file.
* "X" returns ""
* "C" returns the key unconverted.
<syntaxhighlight lang="c++">
let key = "SB001";
let client_name = key.xlate("xo_clients", 1, "X"); // "Client AAA"
// or
let name_and_type = xlate("xo_clients", key, "NAME_AND_TYPE", "X"); // "Client AAA (A)"</syntaxhighlight>
|}
===== Database Sort/Select =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|if||dbfile.<em>select</em>(sort_select_command = "")||Create an active select list of keys of a database file.
The select(command) function searches and orders database records for subsequent processing given an English language-like command.
The primary job of a database, beyond mere storage and retrieval of information, is to allow rapid searching and ordering of information on demand.
In Exodus, searching and ordering of information is known as "sort/select" and is performed by the select() function.
Executing the select() function creates an "active select list" which can then be consumed by the readnext() function.
<em>dbfile:</em> A opened database file or file name, or an open connection or an empty var for default connections. Subsequent readnext calls must use the same.
<em>sort_select_command:</em> A natural language command using dictionary field names. The command can be blank if a dbfile or filename is given in dbfile or just a file name and all keys will be selected in undefined order.
<em>Example:</em> "select xo_clients with type 'B' and with balance ge 100 by type by name"
<em>Option:</em> "(R)" appended to the sort_select_command acquires the database records as well.
<em>Returns:</em> True if any records are selected or false if none.
<em>Throws:</em> VarDBException in case of any syntax error in the command.
Active select lists created using var.select()'s member function syntax cannot be consumed by the free function form of readnext() and vice versa.
<syntaxhighlight lang="c++">
var clients = "xo_clients";
if (clients.select("with type 'B' and with balance ge 100 by type by name"))
    while (clients.readnext(ID))
        println("Client code is {}", ID);
// or
if (select("xo_clients with type 'B' and with balance ge 100 by type by name"))
    while (readnext(ID))
        println("Client code is {}", ID);</syntaxhighlight>
|-
|if||dbfile.<em>selectkeys</em>(keys)||Create an active select list from a string of keys.
Similar to select() but creates the list directly from a var.
<em>keys:</em> An FM separated list of keys or key^VM^valueno pairs.
<em>Returns:</em> True if any keys are provided or false if not.
<syntaxhighlight lang="c++">
var dbfile = "";
let keys = "A01^B02^C03"_var;
if (dbfile.selectkeys(keys)) ... ok
assert(dbfile.readnext(ID) and ID == "A01");
// or
if (selectkeys(keys)) ... ok
assert(readnext(ID) and ID == "A01");</syntaxhighlight>
|-
|if||dbfile.<em>hasnext</em>()||Checks if a select list is active.
<em>dbfile:</em> A file or connection var used in a prior select, selectkeys or getlist function call.
<em>Returns:</em> True if a select list is active and false if not.
If it returns true then a call to readnext() will return a database record key, otherwise not.
<syntaxhighlight lang="c++">
var clients = "xo_clients", key;
if (clients.select()) {
    assert(clients.hasnext());
}
// or
if (select("xo_clients")) {
    assert(hasnext());
}</syntaxhighlight>
|-
|if||dbfile.<em>readnext</em>(out key)||Acquires and consumes one key from an active select list of database record keys.
<em>dbfile:</em> A file or connection var used in a prior select, selectkeys or getlist function call.
<em>key:</em> Returns the first (next) key present in an active select list or "" if no select list is active.
<em>Returns:</em> True if a list is active and a key is available, false if not.
Each call to readnext consumes one key from the list.
Once all the keys in an active select list have been consumed by calls to readnext, the list becomes inactive.
See select() for example code.
|-
|if||dbfile.<em>readnext</em>(out key, out valueno)||Similar to readnext(key) but multivalued.
If the active list was ordered by multivalued database fields then pairs of key and multivalue number will be available to the readnext function.
|-
|if||dbfile.<em>readnext</em>(out record, out key, out valueno)||Similar to readnext(key) but acquires the database record as well.
<em>record:</em> Returns the next database record from the select list assuming that the select list was created with the (R) option otherwise "" if not.
<em>key:</em> Returns the next database record key in the select list.
<em>valueno:</em> The multivalue number if the select list was ordered on multivalued database record fields or 1 if not.
<syntaxhighlight lang="c++">
var clients = "xo_clients";
if (clients.select("with type 'B' and with balance ge 100 by type by name (R)"))
    while (clients.readnext(RECORD, ID, MV))
        println("Code is {}, Name is {}", ID, RECORD.f(1));
// or
DICT = "dict.xo_clients";
if (select("xo_clients with type 'B' and with balance ge 100 by type by name (R)"))
    while (readnext(RECORD, ID, MV))
        println("Code is {}, Name is {}", calculate("CODE"), calculate("NAME"));</syntaxhighlight>
|-
|cmd||dbfile.<em>clearselect</em>()||Deactivates an active select list.
<em>dbfile:</em> A file or connection var used in a prior select, selectkeys or getlist function call.
<em>Returns:</em> Nothing
Has no effect if no select list is active for dbfile.
<syntaxhighlight lang="c++">
var clients = "xo_clients";
clients.clearselect();
if (not clients.hasnext()) ... ok
// or
clearselect();
if (not hasnext()) ... ok</syntaxhighlight>
|-
|if||dbfile.<em>savelist</em>(listname)||Stores an active select list for later retrieval.
<em>dbfile:</em> A file or connection var used in a prior select, selectkeys or getlist function call.
<em>listname:</em> A suitable name that will be required for later retrieval.
<em>Returns:</em> True if saved successfully or false if there was no active list to be saved.
Any existing list with the same name will be overwritten.
Only the remaining unconsumed part of the active select list is saved.
Saved lists are stand-alone and are not tied to specific database files although they usually hold keys related to specific files.
Saved lists can be created from one file and used to access another.
savelist() merely writes an FM separated string of keys as a record in the "lists" database file using the list name as the key of the record.
If a saved list is very long, additional blocks of keys for the same list may be stored with keys like listname*2, listname*3 etc.
Select lists saved in the lists database file may be created, deleted and listed like database records in any other database file.
<syntaxhighlight lang="c++">
var clients = "xo_clients";
if (clients.select("with type 'B' by name")) {
}
// or
if (select("xo_clients with type 'B' by name")) {
    if (savelist("mylist")) ... ok
}</syntaxhighlight>
|-
|if||dbfile.<em>getlist</em>(listname)||Retrieve and reactivate a saved select list.
<em>dbfile:</em> A file or connection var to be used by subsequent readnext function calls.
<em>listname:</em> The name of an existing list in the "lists" database file, either created by savelist or manually.
<em>Returns:</em> True if the list was successfully retrieved and activated, or false if the list name doesnt exist.
Any currently active select list is replaced.
Retrieving a list does not delete it and a list can be retrieved more than once until specifically deleted.
<syntaxhighlight lang="c++">
var file = "";
if (file.getlist("mylist")) {
    while (file.readnext(ID))
        println("Key is {}", ID);
}
// or
if (getlist("mylist")) {
    while (readnext(ID))
        println("Key is {}", ID);
}</syntaxhighlight>
|-
|if||dbfile.<em>deletelist</em>(listname)||Delete a saved select list.
<em>dbfile:</em> A file or connection to the desired database.
<em>listname:</em> The name of an existing list in the "lists" database file.
<em>Returns:</em> True if successful or false if the list name doesnt exist.
<syntaxhighlight lang="c++">
var conn = "";
if (conn.deletelist("mylist")) ... ok
// or
if (deletelist("mylist")) ... ok</syntaxhighlight>
|}
===== OS Time/Date =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|var=||var().<em>date</em>()||Number of whole days since pick epoch 1967-12-31 00:00:00 UTC. Negative for dates before.
e.g. was 20821 from 2025-01-01 00:00:00 UTC for 24 hours
<syntaxhighlight lang="c++">
let today1 = var().date();
// or
let today2 = date();</syntaxhighlight>
|-
|var=||var().<em>time</em>()||Number of whole seconds since last 00:00:00 (UTC).
e.g. 43200 if time is 12:00
Range 0 - 86399 since there are 24*60*60 (86400) seconds in a day.
<syntaxhighlight lang="c++">
let now1 = var().time();
// or
let now2 = time();</syntaxhighlight>
|-
|var=||var().<em>ostime</em>()||Number of fractional seconds since last 00:00:00 (UTC).
A floating point with approx. nanosecond resolution depending on hardware.
e.g. 23343.704387955 approx. 06:29:03 UTC
<syntaxhighlight lang="c++">
let now1 = var().ostime();
// or
let now2 = ostime();</syntaxhighlight>
|-
|var=||var().<em>timestamp</em>()||Number of fractional days since pick epoch 1967-12-31 00:00:00 UTC. Negative for dates before.
A floating point with approx. nanosecond resolution depending on hardware.
e.g. Was 20821.99998842593 around 2025-01-01 23:59:59 UTC
<syntaxhighlight lang="c++">
let now1 = var().timestamp();
// or
let now2 = timestamp();</syntaxhighlight>
|-
|var=||var().<em>timestamp</em>(ostime)||Construct a timestamp from a date and time
<syntaxhighlight lang="c++">
let idate = iconv("2025-01-01", "D"), itime = iconv("23:59:59", "MT");
let ts1 = idate.timestamp(itime); // 20821.99998842593
// or
let ts2 = timestamp(idate, itime);</syntaxhighlight>
|-
|cmd||var().<em>ossleep</em>(milliseconds)||Sleep/pause/wait for a number of milliseconds
Releases the processor if not needed for a period of time or a delay is required.
<syntaxhighlight lang="c++">
var().ossleep(100); // sleep for 100ms
// or
ossleep(100);</syntaxhighlight>
|-
|var=||file_dir_list.<em>oswait</em>(milliseconds)||Sleep/pause/wait up to a given number of milliseconds or until any changes occur in an FM delimited list of directories and/or files.
Any terminal input (e.g. a key press) will also terminate the wait.
An FM array of event information is returned. See below.
Multiple events are returned in multivalues.
<syntaxhighlight lang="c++">
let v1 = ".^/etc/hosts"_var.oswait(100); /// e.g. "IN_CLOSE_WRITE^/etc^hosts^f"_var
// or
let v2 = oswait(".^/etc/hosts"_var, 100);</syntaxhighlight>
Returned array fields
1. Event type codes
2. dirpaths
3. filenames
4. d=dir, f=file
<pre>
Possible event type codes are as follows:
* IN_CLOSE_WRITE - A file opened for writing was closed
* IN_ACCESS      - Data was read from file
* IN_MODIFY      - Data was written to file
* IN_ATTRIB      - File attributes changed
* IN_CLOSE      - File was closed (read or write)
* IN_MOVED_FROM  - File was moved away from watched directory
* IN_MOVED_TO    - File was moved into watched directory
* IN_MOVE        - File was moved (in or out of directory)
* IN_CREATE      - A file was created in the directory
* IN_DELETE      - A file was deleted from the directory
* IN_DELETE_SELF - Directory or file under observation was deleted
* IN_MOVE_SELF  - Directory or file under observation was moved
</pre>
|}
===== OS File I/O =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|if||osfilevar.<em>osopen</em>(osfilename, utf8 = true)||Initialises an os file handle var that can be used in subsequent random access osbread and osbwrite functions.
<em>osfilename:</em> The name of an existing os file name including path.
<em>utf8:</em> Defaults to true which causes trimming of partial utf-8 Unicode byte sequences from the end of osbreads. For raw untrimmed osbreads pass tf8 = false;
<em>Returns:</em> True if successful or false if not possible for any reason. e.g. Target doesnt exist, permissions etc.
The file will be opened for writing if possible otherwise for reading.
<syntaxhighlight lang="c++">
let osfilename = ostempdirpath() ^ "xo_gendoc_test.conf";
if (oswrite("" on osfilename)) ... ok /// Create an empty os file
var ostempfile;
if (ostempfile.osopen(osfilename)) ... ok
// or
if (osopen(osfilename to ostempfile)) ... ok</syntaxhighlight>
|-
|if||osfilevar.<em>osbwrite</em>(osfilevar, io offset)||Writes data to an existing os file starting at a given byte offset (0 based).
See osbread for more info.
<syntaxhighlight lang="c++">
let osfilename = ostempdirpath() ^ "xo_gendoc_test.conf";
let text = "aaa=123\nbbb=456\n";
var offset = osfile(osfilename).f(1); /// Size of file therefore append
if (text.osbwrite(osfilename, offset)) ... ok // offset -> 16
// or
if (not osbwrite(text on osfilename, offset)) ...</syntaxhighlight>
|-
|if||osfilevar.<em>osbread</em>(osfilevar, io offset, length)||Reads length bytes from an existing os file starting at a given byte offset (0 based).
The osfilevar file handle may either be initialised by osopen or be just be a normal string variable holding the path and name of the os file.
After reading, the offset is updated to point to the correct offset for a subsequent sequential read.
If reading UTF8 data (the default) then the length of data actually returned may be a few bytes shorter than requested in order to be a complete number of UTF-8 code points.
<syntaxhighlight lang="c++">
let osfilename = ostempdirpath() ^ "xo_gendoc_test.conf";
var text, offset = 0;
if (text.osbread(osfilename, offset, 8)) ... ok // text -> "aaa=123\n" // offset -> 8
// or
if (osbread(text from osfilename, offset, 8)) ... ok // text -> "bbb=456\n" // offset -> 16</syntaxhighlight>
|-
|cmd||osfilevar.<em>osclose</em>()||Removes an osfilevar handle from the internal memory cache of os file handles. This frees up both exodus process memory and operating system resources.
It is advisable to osclose any file handles after use, regardless of whether they were specifically opened using osopen or not, especially in long running programs. Exodus performs caching of internal os file handles per thread and os file. If not closed, then the operating system will probably not flush deleted files from storage until the process is terminated. This can potentially create an memory issue or file system resource issue especially if osopening/osreading/oswriting many perhaps temporary files in a long running process.
<syntaxhighlight lang="c++">
osfilevar.osclose();
// or
osclose(osfilevar);</syntaxhighlight>
|-
|if||strvar.<em>oswrite</em>(osfilename, codepage = "")||Create a complete os file from a var.
Any existing os file is removed first.
<em>Returns:</em> True if successful or false if not possible for any reason.
e.g. Path is not writeable, permissions etc.
If codepage is specified then output is converted from utf-8 to that codepage. Otherwise no conversion is done.
<syntaxhighlight lang="c++">
let text = "aaa = 123\nbbb = 456";
let osfilename = ostempdirpath() ^ "xo_gendoc_test.conf";
if (text.oswrite(osfilename)) ... ok
// or
if (oswrite(text on osfilename)) ... ok</syntaxhighlight>
|-
|if||strvar.<em>osread</em>(osfilename, codepage = "")||Read a complete os file into a var.
If codepage is specified then input is converted from that codepage to utf-8 otherwise no conversion is done.
<em>Returns:</em> True if successful or false if not possible for any reason.
e.g. File doesnt exist, permissions etc.
<syntaxhighlight lang="c++">
var text;
let osfilename = ostempdirpath() ^ "xo_gendoc_test.conf";
if (text.osread(osfilename)) ... ok // text -> "aaa = 123\nbbb = 456"
// or
if (osread(text from osfilename)) ... ok</syntaxhighlight>
|-
|if||osfile_or_dirname.<em>osrename</em>(new_dirpath_or_filepath)||Renames an os file or dir in the OS file system.
Will not overwrite an existing os file or dir.
Source and target must exist in the same storage device.
<em>Returns:</em> True if successful or false if not possible for any reason.
e.g. Target already exists, path is not writeable, permissions etc.
Uses std::filesystem::rename internally.
<syntaxhighlight lang="c++">
let from_osfilename = ostempdirpath() ^ "xo_gendoc_test.conf";
let to_osfilename = from_osfilename ^ ".bak";
if (not osremove(ostempdirpath() ^ "xo_gendoc_test.conf.bak")) {}; // Cleanup first
if (from_osfilename.osrename(to_osfilename)) ... ok
// or
if (osrename(from_osfilename, to_osfilename)) ...</syntaxhighlight>
|-
|if||osfile_or_dirname.<em>osmove</em>(to_osfilename)||"Moves" an os file or dir within the os file system.
Will not overwrite an existing os file or dir.
<em>Returns:</em> True if successful or false if not possible for any reason.
e.g. Source doesnt exist or cannot be accessed, target already exists, source or target is not writeable, permissions etc.
Attempts osrename first then oscopy followed by osremove original.
<syntaxhighlight lang="c++">
let from_osfilename = ostempdirpath() ^ "xo_gendoc_test.conf.bak";
let to_osfilename = from_osfilename.cut(-4);
if (not osremove(ostempdirpath() ^ "xo_gendoc_test.conf")) {}; // Cleanup first
if (from_osfilename.osmove(to_osfilename)) ... ok
// or
if (osmove(from_osfilename, to_osfilename)) ...</syntaxhighlight>
|-
|if||osfile_or_dirname.<em>oscopy</em>(to_osfilename)||Copies an os file or directory recursively within the os file system.
Will overwrite an existing os file or dir.
Uses std::filesystem::copy internally with recursive and overwrite options
<syntaxhighlight lang="c++">
let from_osfilename = ostempdirpath() ^ "xo_gendoc_test.conf";
let to_osfilename = from_osfilename ^ ".bak";
if (from_osfilename.oscopy(to_osfilename)) ... ok;
// or
if (oscopy(from_osfilename, to_osfilename)) ... ok</syntaxhighlight>
|-
|if||osfilename.<em>osremove</em>()||Removes/deletes an os file from the OS file system given path and name.
Will not remove directories. Use osrmdir() to remove directories
<em>Returns:</em> True if successful or false if not possible for any reason.
e.g. Target doesnt exist, path is not writeable, permissions etc.
<syntaxhighlight lang="c++">
let osfilename = ostempdirpath() ^ "xo_gendoc_test.conf";
if (osfilename.osremove()) ... ok
// or
if (osremove(osfilename)) ...</syntaxhighlight>
|}
===== OS Directories =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|var=||dirpath.<em>oslist</em>(globpattern = "", mode = 0)||Returns: A FM delimited string containing all matching dir entries given a dir path
A glob pattern (e.g. *.conf) can be appended to the path or passed as argument.
<syntaxhighlight lang="c++">
var entries1 = "/etc/"_var.oslist("*.cfg"); /// e.g. "adduser.conf^ca-certificates.con^... etc."
// or
var entries2 = oslist("/etc/" "*.conf");</syntaxhighlight>
|-
|var=||dirpath.<em>oslistf</em>(globpattern = "")||Same as oslist for files only
|-
|var=||dirpath.<em>oslistd</em>(globpattern = "")||Same as oslist for files only
|-
|var=||osfile_or_dirpath.<em>osinfo</em>(mode = 0)||Returns: Dir info for any dir entry or "" if it doesnt exist
A short string containing size ^ FM ^ modified_time ^ FM ^ modified_time
mode 0 default
mode 1 returns "" if not an os file
mode 2 returns "" if not an os dir
See also osfile() and osdir()
<syntaxhighlight lang="c++">
var info1 = "/etc/hosts"_var.osinfo(); /// e.g. "221^20597^78309"_var
// or
var info2 = osinfo("/etc/hosts");</syntaxhighlight>
|-
|var=||osfilename.<em>osfile</em>()||Returns: Dir info for a os file
A short string containing size ^ FM ^ modified_time ^ FM ^ modified_time
Alias for osinfo(1)
<syntaxhighlight lang="c++">
var fileinfo1 = "/etc/hosts"_var.osfile(); /// e.g. "221^20597^78309"_var
// or
var fileinfo2 = osfile("/etc/hosts");</syntaxhighlight>
|-
|var=||dirpath.<em>osdir</em>()||Returns: Dir info for a dir.
A short string containing FM ^ modified_time ^ FM ^ modified_time
Alias for osinfo(2)
<syntaxhighlight lang="c++">
var dirinfo1 = "/etc/"_var.osdir(); /// e.g. "^20848^44464"_var
// or
var dirinfo2 = osfile("/etc/");</syntaxhighlight>
|-
|if||dirpath.<em>osmkdir</em>()||Makes a new directory and returns true if successful.
Including parent dirs if necessary.
<syntaxhighlight lang="c++">
let osdirname = "xo_test/aaa";
if (osrmdir("xo_test/aaa")) {}; // Cleanup first
if (osdirname.osmkdir()) ... ok
// or
if (osmkdir(osdirname)) ...</syntaxhighlight>
|-
|if||dirpath.<em>oscwd</em>(newpath)||Changes the current working dir and returns true if successful.
<syntaxhighlight lang="c++">
let osdirname = "xo_test/aaa";
if (osdirname.oscwd()) ... ok
// or
if (oscwd(osdirname)) ... ok
if (oscwd("../..")) ... ok /// Change back to avoid errors in following code.</syntaxhighlight>
|-
|var=||dirpath.<em>oscwd</em>()||Returns: The current working directory
e.g. "/root/exodus/cli/src/xo_test/aaa"
<syntaxhighlight lang="c++">
var cwd1 = var().oscwd();
// or
var cwd2 = oscwd();</syntaxhighlight>
|-
|if||dirpath.<em>osrmdir</em>(evenifnotempty = false)||Removes a os dir and returns true if successful.
Optionally even if not empty. Including subdirs.
<syntaxhighlight lang="c++">
let osdirname = "xo_test/aaa";
if (osdirname.osrmdir()) ... ok
// or
if (osrmdir(osdirname)) ...</syntaxhighlight>
|}
===== OS Shell/Environment =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|if||command.<em>osshell</em>()||Execute a shell command.
<em>Returns:</em> True if the process terminates with error status 0 and false otherwise.
Append "&>/dev/null" to the command to suppress terminal output.
<syntaxhighlight lang="c++">
let cmd = "echo $HOME";
if (cmd.osshell()) ... ok
// or
if (osshell(cmd)) ... ok</syntaxhighlight>
|-
|if||instr.<em>osshellread</em>(oscmd)||Same as osshell but captures and returns stdout
<em>Returns:</em> The stout of the shell command.
Append "2>&1" to the command to capture stderr/stdlog output as well.
<syntaxhighlight lang="c++">
let cmd = "echo $HOME";
var text;
if (text.osshellread(cmd)) ... ok
// or capturing stdout but ignoring exit status
text = osshellread(cmd);</syntaxhighlight>
|-
|if||outstr.<em>osshellwrite</em>(oscmd)||Same as osshell but provides stdin to the process
<em>Returns:</em> True if the process terminates with error status 0 and false otherwise.
Append "&> somefile" to the command to suppress and/or capture output.
<syntaxhighlight lang="c++">
let outtext = "abc xyz";
if (outtext.osshellwrite("grep xyz")) ... ok
// or
if (osshellwrite(outtext, "grep xyz")) ... ok</syntaxhighlight>
|-
|var=||var().<em>ostempdirpath</em>()||Returns: The path of the tmp dir
e.g. "/tmp/"
<syntaxhighlight lang="c++">
let v1 = var().ostempdirpath();
// or
let v2 = ostempdirpath();</syntaxhighlight>
|-
|var=||var().<em>ostempfilename</em>()||Returns: The name of a new temporary file
e.g. Something like "/tmp/~exoEcLj3C"
<syntaxhighlight lang="c++">
var temposfilename1 = var().ostempfilename();
// or
var temposfilename2 = ostempfilename();</syntaxhighlight>
|-
|cmd||envvalue.<em>ossetenv</em>(envcode)||Set the value of an environment variable code
<syntaxhighlight lang="c++">
let envcode = "EXO_ABC", envvalue = "XYZ";
envvalue.ossetenv(envcode);
// or
ossetenv(envcode, envvalue);</syntaxhighlight>
|-
|if||envvalue.<em>osgetenv</em>(envcode)||Get the value of an environment variable.
<em>envcode:</em> The code of the desired environment variable or "" for all.
<em>Returns:</em> True if set or false if not.
<em>var:</em> If envcode exists: var is set to the value of the environment variable
<em>var:</em> If envcode doesnt exist: var is set to ""
<em>var:</em> If envcode is "": var is set to an dynamic array of all environment variables LIKE CODE1=VALUE1^CODE2=VALUE2...
osgetenv and ossetenv work with a per thread copy of the process environment. This avoids multithreading issues but not actually changing the process environment.
For the actual system environment, see "man environ". extern char **environ; // environ is a pointer to an array of pointers to char* env pairs like xxx=yyy and the last pointer in the array is nullptr.
<syntaxhighlight lang="c++">
var envvalue1;
if (envvalue1.osgetenv("HOME")) ... ok // e.g. "/home/exodus"
// or
var envvalue2 = osgetenv("EXO_ABC"); // "XYZ"</syntaxhighlight>
|-
|var=||var().<em>ospid</em>()||Get the os process id
<syntaxhighlight lang="c++">
let pid1 = var().ospid(); /// e.g. 663237
// or
let pid2 = ospid();</syntaxhighlight>
|-
|var=||var().<em>ostid</em>()||Get the os thread process id
<syntaxhighlight lang="c++">
let tid1 = var().ostid(); /// e.g. 663237
// or
let tid2 = ostid();</syntaxhighlight>
|-
|var=||var().<em>version</em>()||Get the libexodus build date and time
<syntaxhighlight lang="c++">
let v1 = var().version(); /// e.g. "29 JAN 2025 14:56:52"</syntaxhighlight>
|-
|if||strvar.<em>setxlocale</em>()||Sets the current thread's default locale codepage code
True if successful
<syntaxhighlight lang="c++">
if ("en_US.utf8"_var.setxlocale()) ... ok
// or
if (setxlocale("en_US.utf8")) ... ok</syntaxhighlight>
|-
|var=||var.<em>getxlocale</em>()||Returns: The current thread's default locale codepage code
<syntaxhighlight lang="c++">
let v1 = var().getxlocale(); // "en_US.utf8"
// or
let v2 = getxlocale();</syntaxhighlight>
|}
===== Output =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|expr||varstr.<em>outputl</em>(prefix = "")||Output to stdout with optional prefix.
Appends an NL char.
Is FLUSHED, not buffered.
The raw string bytes are output. No character or byte conversion is performed.
<syntaxhighlight lang="c++">
"abc"_var.outputl("xyz = "); /// Sends "xyz = abc\n" to stdout and flushes.
// or
outputl("xyz = ", "abc"); /// Any number of arguments is allowed. All will be output.</syntaxhighlight>
|-
|expr||varstr.<em>output</em>(prefix = "")|| Same as outputl() but doesnt append an NL char and is BUFFERED, not flushed.
|-
|expr||varstr.<em>outputt</em>(prefix = "")|| Same as outputl() but appends a tab char instead of an NL char and is BUFFERED, not flushed.
|-
|expr||varstr.<em>logputl</em>(prefix = "")||Output to stdlog with optional prefix.
Appends an NL char.
Is BUFFERED not flushed.
Any of the six types of field mark chars present are converted to their visible versions,
<syntaxhighlight lang="c++">
"abc"_var.logputl("xyz = "); /// Sends "xyz = abc\n" to stdlog buffer and is not flushed.
// or
logputl("xyz = ", "abc");; /// Any number of arguments is allowed. All will be output.</syntaxhighlight>
|-
|expr||varstr.<em>logput</em>(prefix = "")|| Same as logputl() but doesnt append an NL char.
|-
|expr||varstr.<em>errputl</em>(prefix = "")||Output to stderr with optional prefix.
Appends an NL char.
Is FLUSHED not buffered.
Any of the six types of field mark chars present are converted to their visible versions,
<syntaxhighlight lang="c++">
"abc"_var.errputl("xyz = "); /// Sends "xyz = abc\n" to stderr
// or
errputl("xyz = ", "abc"); /// Any number of arguments is allowed. All will be output.</syntaxhighlight>
|-
|expr||varstr.<em>errput</em>(prefix = "")|| Same as errputl() but doesnt append an NL char and is BUFFERED not flushed.
|-
|expr||varstr.<em>put</em>(std::ostream& ostream1)||Output to a given stream.
Is BUFFERED not flushed.
The raw string bytes are output. No character or byte conversion is performed.
|-
|cmd||var().<em>osflush</em>()||Flush any and all buffered output to stdout and stdlog.
<syntaxhighlight lang="c++">
var().osflush();
// or
osflush();</syntaxhighlight>
|}
===== Input =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|if||var.<em>input</em>(prompt = "")||Returns one line of input from stdin.
<em>Returns:</em> True if successful or false if EOF or user pressed Esc or Ctrl+X in a terminal.
<em>var:</em> [in] The default value for terminal input and editing. Ignored if not a terminal.
<em>var:</em> [out] Raw bytes up to but excluding the first new line char. In case of EOF or user pressed Esc or Ctrl+X in a terminal it will be changed to "".
<em>Prompt:</em> If provided, it will be displayed on the terminal.
Multibyte/UTF8 friendly.
<syntaxhighlight lang="c++">
// var v1 = "defaultvalue";
// if (v1.input("Prompt:")) ... ok
// or
// var v2 = input();</syntaxhighlight>
|-
|expr||var.<em>keypressed</em>(wait = false)||Return the code of the current terminal key pressed.
<em>wait:</em> Defaults to false. True means wait for a key to be pressed if not already pressed.
<em>Returns:</em> ASCII or key code defined according to terminal protocol.
<em>Returns:</em> "" if stdin is not a terminal.
e.g. The PgDn key if pressed might return an escape sequence like "\x1b[6~"
It only takes a few µsecs to return false if no key is pressed.
<syntaxhighlight lang="c++">
var v1; v1.keypressed();
// or
var v2 = keypressed();</syntaxhighlight>
|-
|if||var().<em>isterminal</em>(arg = 1)||Checks if one of stdin, stdout, stderr is a terminal or a file/pipe.
<em>arg:</em> 0 - stdin, 1 - stdout (Default), 2 - stderr.
<em>Returns:</em> True if it is a terminal or false if it is a file or pipe.
Note that if the process is at the start or end of a pipeline, then only stdin or stdout will be a terminal.
The type of stdout terminal can be obtained from the TERM environment variable.
<syntaxhighlight lang="c++">
var v1 = var().isterminal(); /// 1 or 0
// or
var v2 = isterminal();</syntaxhighlight>
|-
|if||var().<em>hasinput</em>(milliseconds = 0)||Checks if stdin has any bytes available for input.
If no bytes are immediately available, the process sleeps for up to the given number of milliseconds, returning true immediately any bytes become available or false if the period expires without any bytes becoming available.
<em>Returns:</em> True if any bytes are available otherwise false.
It only takes a few µsecs to return false if no bytes are available and no wait time has been requested.
|-
|if||var().<em>eof</em>()||True if stdin is at end of file
|-
|if||var().<em>echo</em>(on_off = true)||Sets terminal echo on or off.
"On" causes all stdin data to be reflected to stdout if stdin is a terminal.
Turning terminal echo off can be used to prevent display of confidential information.
<em>Returns:</em> True if successful.
|-
|cmd||var().<em>breakon</em>()||Install various interrupt handlers.
Automatically called in program/thread initialisation by exodus_main.
SIGINT - Ctrl+C -> "Interrupted. (C)ontinue (Q)uit (B)acktrace (D)ebug (A)bort ?"
SIGHUP - Sets a static variable "RELOAD_req" which may be handled or ignored by the program.
SIGTERM - Sets a static variable "TERMINATE_req" which may be handled or ignored by the program.
|-
|cmd||var().<em>breakoff</em>()||Disable keyboard interrupt.
Ctrl+C becomes inactive in terminal.
|}
===== Math/Boolean =====
{|class="wikitable"
!Usage!!Function!!Description
|-
|var=||varnum.<em>abs</em>()||Absolute value
<syntaxhighlight lang="c++">
let v1 = -12.34;
let v2 = v1.abs(); // 12.34
// or
let v3 = abs(v1);</syntaxhighlight>
|-
|var=||varnum.<em>pwr</em>(exponent)||Power
<syntaxhighlight lang="c++">
let v1 = var(2).pwr(8); // 256
// or
let v2 = pwr(2, 8);</syntaxhighlight>
|-
|cmd||varnum.<em>initrnd</em>()||Initialise the seed for rnd()
Allows the stream of pseudo random numbers generated by rnd() to be reproduced.
Seeded from std::chrono::high_resolution_clock::now() if the argument is 0;
<syntaxhighlight lang="c++">
var(123).initrnd(); /// Set seed to 123
// or
initrnd(123);</syntaxhighlight>
|-
|var=||varnum.<em>rnd</em>()||Pseudo random number generator
<em>Returns:</em> a pseudo random integer between 0 and the provided maximum minus 1.
Uses std::mt19937 and std::uniform_int_distribution<int>
<syntaxhighlight lang="c++">
let v1 = var(100).rnd(); /// Random 0 to 99
// or
let v2 = rnd(100);</syntaxhighlight>
|-
|var=||varnum.<em>exp</em>()||Power of e
<syntaxhighlight lang="c++">
let v1 = var(1).exp(); // 2.718281828459045
// or
let v2 = exp(1);</syntaxhighlight>
|-
|var=||varnum.<em>sqrt</em>()||Square root
<syntaxhighlight lang="c++">
let v1 = var(100).sqrt(); // 10
// or
let v2 = sqrt(100);</syntaxhighlight>
|-
|var=||varnum.<em>sin</em>()||Sine of degrees
<syntaxhighlight lang="c++">
let v1 = var(30).sin(); // 0.5
// or
let v2 = sin(30);</syntaxhighlight>
|-
|var=||varnum.<em>cos</em>()||Cosine of degrees
<syntaxhighlight lang="c++">
let v1 = var(60).cos(); // 0.5
// or
let v2 = cos(60);</syntaxhighlight>
|-
|var=||varnum.<em>tan</em>()||Tangent of degrees
<syntaxhighlight lang="c++">
let v1 = var(45).tan(); // 1
// or
let v2 = tan(45);</syntaxhighlight>
|-
|var=||varnum.<em>atan</em>()||Arctangent of degrees
<syntaxhighlight lang="c++">
let v1 = var(1).atan(); // 45
// or
let v2 = atan(1);</syntaxhighlight>
|-
|var=||varnum.<em>loge</em>()||Natural logarithm
<em>Returns:</em> Floating point ver (double)
<syntaxhighlight lang="c++">
let v1 = var(2.718281828459045).loge(); // 1
// or
let v2 = loge(2.718281828459045);</syntaxhighlight>
|-
|var=||varnum.<em>integer</em>()||Truncate decimal numbers towards zero
<em>Returns:</em> An integer var
<syntaxhighlight lang="c++">
let v1 = var(2.9).integer(); // 2
// or
let v2 = integer(2.9);
var v3 = var(-2.9).integer(); // -2
// or
var v4 = integer(-2.9);</syntaxhighlight>
|-
|var=||varnum.<em>floor</em>()||Truncate decimal numbers towards negative
<em>Returns:</em> An integer var
<syntaxhighlight lang="c++">
let v1 = var(2.9).floor(); // 2
// or
let v2 = floor(2.9);
var v3 = var(-2.9).floor(); // -3
// or
var v4 = floor(-2.9);</syntaxhighlight>
|-
|var=||varnum.<em>mod</em>(modulus)||Modulus function
Identical to C++ % operator only for positive numbers and modulus
Negative denominators are considered as periodic with positiive numbers
Result is between [0, modulus) if modulus is positive
Result is between (modulus, 0] if modulus is negative (symmetric)
<em>Throws:</em> VarDivideByZero if modulus is zero.
Floating point works.
<syntaxhighlight lang="c++">
let v1 = var(11).mod(5); // 1
// or
let v2 = mod(11, 5); // 1
let v3 = mod(-11, 5); // 4
let v4 = mod(11, -5); // -4
let v5 = mod(-11, -5); // -1</syntaxhighlight>
|}
=== I/O Conversion Codes  ===
{|class="wikitable"
!Usage!!Function!!Description
|-
|var=||vardate.<em>oconv_D</em>(conversion)||Date output: Convert internal date format to human readable date or calendar info in text format.
<em>Returns:</em> Human readable date or calendar info, or the original value unconverted if non-numeric.
<em>Flags:</em> See examples below.
Any multifield/multivalue structure is preserved.
<syntaxhighlight lang="c++">
let v1 = 12345;
assert( v1.oconv( "D"  ) == "18 OCT 2001"  ); // Default
assert( v1.oconv( "D/"  ) == "10/18/2001"  ); // / separator
assert( v1.oconv( "D-"  ) == "10-18-2001"  ); // - separator
assert( v1.oconv( "D2"  ) == "18 OCT 01"    ); // 2 digit year
assert( v1.oconv( "D/E" ) == "18/10/2001"  ); // International order with /
assert( v1.oconv( "DS"  ) == "2001 OCT 18"  ); // ISO Year first
assert( v1.oconv( "DS-" ) == "2001-10-18"  ); // ISO Year first with -
assert( v1.oconv( "DM"  ) == "10"          ); // Month number
assert( v1.oconv( "DMA" ) == "OCTOBER"      ); // Month name
assert( v1.oconv( "DY"  ) == "2001"        ); // Year number
assert( v1.oconv( "DY2" ) == "01"          ); // Year 2 digits
assert( v1.oconv( "DD"  ) == "18"          ); // Day number in month (1-31)
assert( v1.oconv( "DW"  ) == "4"            ); // Weekday number (1-7)
assert( v1.oconv( "DWA" ) == "THURSDAY"    ); // Weekday name
assert( v1.oconv( "DQ"  ) == "4"            ); // Quarter number
assert( v1.oconv( "DJ"  ) == "291"          ); // Day number in year
assert( v1.oconv( "DL"  ) == "31"          ); // Last day number of month (28-31)
// Multifield/multivalue
var v2 = "12345^12346]12347"_var;
assert(v2.oconv("D") == "18 OCT 2001^19 OCT 2001]20 OCT 2001"_var);
  // or
  assert( oconv(v1, "D"  ) == "18 OCT 2001"  );</syntaxhighlight>
|-
|var=||varstr.<em>iconv_D</em>(conversion)||Date input: Convert human readable date to internal date format.
<em>Returns:</em> Internal date or "" if the input is an invalid date.
Internal date format is whole days since 1967-12-31 00:00:00 which is day 0.
Any multifield/multivalue structure is preserved.
<syntaxhighlight lang="c++">
// International order "DE"
assert(            oconv(19005, "DE") == "12 JAN 2020");
assert(  "12/1/2020"_var.iconv("DE") == 19005);
assert(  "12 1 2020"_var.iconv("DE") == 19005);
assert(  "12-1-2020"_var.iconv("DE") == 19005);
assert( "12 JAN 2020"_var.iconv("DE") == 19005);
assert( "jan 12 2020"_var.iconv("DE") == 19005);
// American order "D"
assert(            oconv(19329, "D") == "01 DEC 2020");
assert(  "12/1/2020"_var.iconv("D") == 19329);
assert(  "DEC 1 2020"_var.iconv("D") == 19329);
assert(  "1 dec 2020"_var.iconv("D") == 19329);
// Reverse order
assert(  "2020/12/1"_var.iconv("DE") == 19329);
assert(  "2020-12-1"_var.iconv("D") == 19329);
assert(  "2020 1 dec"_var.iconv("D") == 19329);
//Invalid date
assert(  "2/29/2021"_var.iconv("D") == "");
assert(  "29/2/2021"_var.iconv("DE") == "");
// or
assert(iconv("12/1/2020"_var, "DE") == 19005);</syntaxhighlight>
|-
|var=||vartime.<em>oconv_MT</em>(conversion)||Time output: Convert internal time format to human readable time e.g. "10:30:59".
<em>Returns:</em> Human readable time or the original value unconverted if non-numeric.
Conversion code (e.g. "MTHS") is "MT" + flags ...
<em>Flags:</em>
"H" - Show AM/PM otherwise 24 hour clock is used.
"S" - Output seconds
"2" = Ignored (used in iconv)
":" - Any other flag is used as the separator char instead of ":"
Any multifield/multivalue structure is preserved.
<syntaxhighlight lang="c++">
var v1 = 234800;
assert( v1.oconv( "MT"  ) == "17:13"      ); // Default
assert( v1.oconv( "MTH"  ) == "05:13PM"    ); // 'H' flag for AM/PM
assert( v1.oconv( "MTS"  ) == "17:13:20"  ); // 'S' flag for seconds
assert( v1.oconv( "MTHS" ) == "05:13:20PM" ); // Both flags
var v2 = 0;
assert( v2.oconv( "MT"  ) == "00:00"      );
assert( v2.oconv( "MTH"  ) == "12:00AM"    );
assert( v2.oconv( "MTS"  ) == "00:00:00"  );
assert( v2.oconv( "MTHS" ) == "12:00:00AM" );
// Multifield/multivalue
var v3 = "234800^234860]234920"_var;
assert(v3.oconv("MT") == "17:13^17:14]17:15"_var);
// or
assert( oconv(v1, "MT"  ) == "17:13"      );</syntaxhighlight>
|-
|var=||varstr.<em>iconv_MT</em>(strict)||Time input: Convert human readable time (e.g. "10:30:59") to internal time format.
<em>Returns:</em> Internal time or "" if the input is an invalid time.
Internal time format is whole seconds since midnight.
<em>Accepts:</em> Two or three groups of digits surrounded and separated by any non-digits char(s).
Any multifield/multivalue structure is preserved.
<syntaxhighlight lang="c++">
assert(      "17:13"_var.iconv( "MT" ) == 61980);
assert(    "05:13PM"_var.iconv( "MT" ) == 61980);
assert(  "17:13:20"_var.iconv( "MT" ) == 62000);
assert( "05:13:20PM"_var.iconv( "MT" ) == 62000);
assert(      "00:00"_var.iconv( "MT" ) == 0);
assert(    "12:00AM"_var.iconv( "MT" ) == 0);    // Midnight
assert(    "12:00PM"_var.iconv( "MT" ) == 43200); // Noon
assert(  "00:00:00"_var.iconv( "MT" ) == 0);
assert( "12:00:00AM"_var.iconv( "MT" ) == 0);
// Multifield/multivalue
assert("17:13^05:13PM]17:13:20"_var.iconv("MT") == "61980^61980]62000"_var);
// or
assert(iconv("17:13", "MT") == 61980);</syntaxhighlight>
|-
|var=||varnum.<em>oconv_MD</em>(conversion)||Number output: Convert internal numbers to external text format after rounding and optional scaling.
<em>Returns:</em> A string or, if the value is not numeric, then no conversion is performed and the original value is returned.
Conversion code (e.g. "MD20") is "MD" or "MC", 1st digit, 2nd digit, flags ...
MD outputs like 123.45 (International)
MC outputs like 123,45 (European)
1st digit = Decimal places to display. Also decimal places to move if 2nd digit not present and no P flag present.
2nd digit = Optional decimal places to move left if P flag not present.
<em>Flags:</em>
"P" - Preserve decimal places. Same as 2nd digit = 0;
"Z" - Zero flag - return "" if zero.
"X" - No conversion - return as is.
"." or "," - Separate thousands depending on MD or MC.
"-" means suffix negatives with "-" and positives with " " (space).
"<" means wrap negatives in "<" and ">" chars.
"C" means suffix negatives with "CR" and positives or zero with "DB".
"D" means suffix negatives with "DB" and positives or zero with "CR".
Any multifield/multivalue structure is preserved.
<syntaxhighlight lang="c++">
var v1 = -1234.567;
assert( v1.oconv( "MD20"  ) ==  "-1234.57"  );
assert( v1.oconv( "MD20,"  ) == "-1,234.57"  ); // , flag
assert( v1.oconv( "MC20,"  ) == "-1.234,57"  ); // MC code
assert( v1.oconv( "MD20,-" ) ==  "1,234.57-"  ); // - flag
assert( v1.oconv( "MD20,<" ) == "<1,234.57>"  ); // < flag
assert( v1.oconv( "MD20,C" ) ==  "1,234.57CR" ); // C flag
assert( v1.oconv( "MD20,D" ) ==  "1,234.57DB" ); // D flag
// Multifield/multivalue
var v2 = "1.1^2.1]2.2"_var;
assert( v2.oconv( "MD20"  ) == "1.10^2.10]2.20"_var);
// or
assert( oconv(v1, "MD20"  ) ==  "-1234.57"  );</syntaxhighlight>
|-
|var=||var.<em>oconv_LRC</em>(format)||Text justification: Left, right and center. Padding and truncating. See Procrustes.
e.g. "L#10", "R#10", "C#10"
Useful when outputting to terminal devices where spaces are used for alignment.
Multifield/multivalue structure is preserved.
ASCII only.
<syntaxhighlight lang="c++">
assert(    "abcde"_var.oconv( "L#3" ) == "abc" ); // Truncating
assert(    "abcde"_var.oconv( "R#3" ) == "cde" );
assert(    "abcde"_var.oconv( "C#3" ) == "abc" );
assert(    "ab"_var.oconv( "L#6" ) == "ab␣␣␣␣" ); // Padding
assert(    "ab"_var.oconv( "R#6" ) == "␣␣␣␣ab" );
assert(    "ab"_var.oconv( "C#6" ) == "␣␣ab␣␣" );
assert(      var(42).oconv( "L(0)#5" ) == "42000" ); // Padding char (x)
assert(      var(42).oconv( "R(0)#5" ) == "00042" );
assert(      var(42).oconv( "C(0)#5" ) == "04200" );
assert(      var(42).oconv( "C(0)#5" ) == "04200" );
// Multifield/multivalue
assert(      "f1^v1]v2"_var.oconv("L(_)#5") == "f1___^v1___]v2___"_var);
// Fail for non-ASCII (Should be 5)
assert(    "🐱"_var.oconv("L#5").textwidth() == 3);
// or
assert(    oconv("abcd", "L#3" ) == "abc" );</syntaxhighlight>
|-
|var=||varstr.<em>oconv_T</em>(format)||Text folding and justification.
e.g. T#20
Useful when outputting to terminal devices where spaces are used for alignment.
Splits text into multiple fixed length lines by inserting spaces and TM chars.
ASCII only.
<syntaxhighlight lang="c++">
var v1 = "Have a nice day";
assert(  v1.oconv("T#10") == "Have a␣␣␣␣|nice day␣␣"_var);
// or
assert( oconv(v1, "T#10") == "Have a␣␣␣␣|nice day␣␣"_var );</syntaxhighlight>
|-
|var=||varstr.<em>oconv_HEX</em>(ioratio)||Convert a string of bytes to a string of hexadecimal digits. The size of the output is precisely double that of the input.
Multifield/multivalue structure is not preserved. Field marks are converted to HEX as for all other bytes.
<syntaxhighlight lang="c++">
assert(    "ab01"_var.oconv( "HEX" ) == "61" "62" "30" "31" );
assert( "\xff\x00"_var.oconv( "HEX" ) == "FF" "00"          ); // Any bytes are ok.
assert(        var(10).oconv( "HEX" ) == "31" "30"          ); // Uses ASCII string equivalent of 10 i.e. "10".
assert(  "\u0393"_var.oconv( "HEX" ) == "CE" "93"          ); // Greek capital Gamma in UTF8 bytes.
assert(    "a^]b"_var.oconv( "HEX" ) == "61" "1E" "1D" "62" ); // Field and value marks.
// or
assert(      oconv("ab01"_var, "HEX") == "61" "62" "30" "31");</syntaxhighlight>
|-
|var=||varstr.<em>iconv_HEX</em>(ioratio)||Convert a string of hexadecimal digits to a string of bytes. After prefixing a "0" to an odd sized input, the size of the output is precisely half that of the input.
Reverse of oconv("HEX") above.
|-
|var=||varnum.<em>oconv_MX</em>()||Number to hex format: Convert number to hexadecimal string
If the value is not numeric then no conversion is performed and the original value is returned.
<syntaxhighlight lang="c++">
assert( var("255").oconv("MX") == "FF");
// or
assert( oconv(var("255"), "MX") == "FF");</syntaxhighlight>
|-
|var=||varnum.<em>oconv_MB</em>()||Number to binary format: Convert number to strings of 1s and 0s
If the value is not numeric then no conversion is performed and the original value is returned.
<syntaxhighlight lang="c++">
assert( var(255).oconv("MB") == 1111'1111);
// or
assert( oconv(var(255), "MB") == 1111'1111);</syntaxhighlight>
|-
|var=||varstr.<em>oconv_TX</em>(conversion)||Convert dynamic arrays to standard text format.
Useful for using text editors on dynamic arrays.
FMs -> NL after escaping any embedded NL
<syntaxhighlight lang="c++">
  // backslash in text remains backslash
  assert(var(_BS).oconv("TX") == _BS);
  // 1. Double escape any _BS "n" -> _BS _BS "n"
  assert(var(_BS "n").oconv("TX") == _BS _BS "n");
  // 2. Single escape any _NL -> _BS "n"
  assert(var(_NL).oconv("TX") == _BS "n");
  // 3. FMs -> _NL (⏎)
  assert("🌍^🌍"_var.oconv("TX") == "🌍" _NL "🌍");
  // 4. VMs -> _BS _NL (\⏎)
  assert("🌍]🌍"_var.oconv("TX") == "🌍" _BS _NL "🌍");
  // 5. SMs -> _BS _BS _NL (\\⏎)
  assert("🌍}🌍"_var.oconv("TX") == "🌍" _BS _BS _NL "🌍");
  // 6. TMs -> _BS _BS _BS _NL (\\\⏎)
  assert("🌍|🌍"_var.oconv("TX") == "🌍" _BS _BS _BS _NL "🌍");
  // 7. STs -> _BS _BS _BS _BS _NL (\\\\⏎)
  assert("🌍~🌍"_var.oconv("TX") == "🌍" _BS _BS _BS _BS _NL "🌍");</syntaxhighlight>
|-
|var=||varstr.<em>iconv_TX</em>(conversion)||Convert standard text format to dynamic array.
Reverse of oconv("TX") above.
|}
=== Dimensioned Array Construction  ===
{|class="wikitable"
!Usage!!Function!!Description
|-
|dim()||dim <1;||Create an undimensioned array of var.
|-
|dim(const||dim <1 = <2; // Copy||Copy an array.
|-
|dim(dim&&||dim <1 = dim(); // Move||Save an array created elsewhere.
|-
|dim(const||dim <1(nrows, ncols = 1); // Constructor||Create an array of vars with a fixed number of columns and rows. All vars are unassigned.
|-
|dim(std::initializer_list<T>||dim <1 = {"a", "b", "c" ...}; // Initializer list||Create an array from a list. All elements must be the same type. var, string, double, int, etc..
|-
|cmd||<em>operator=</em>(v1)||Initialise all elements of an array to some single value or constant. A var, "", 0 etc.
|-
|cmd||d1.<em>redim</em>(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".
|-
|cmd||d1.<em>swap</em>(dim& d2) ||Swap one array with another.
Either or both may be undimensioned.
|}
=== Array Access ===
{|class="wikitable"
!Usage!!Function!!Description
|-
|VARREF||dim.<em>operator[]</em>(rowno)||Access and update elements of a one dimensional array using [] brackets
|-
|VARREF||dim.<em>operator[]</em>(rowno, colno)||Access and update elements of an two dimensional array using [] brackets
|-
|var=||d1.<em>rows</em>()||Get the number of rows in the dimensioned array
<em>Returns:</em> A count. Can be zero, indicating an empty array.
|-
|var=||d1.<em>cols</em>()||Get the number of columns in the dimensioned array
<em>Returns:</em> A count.  0 if the array is undimensioned.
|-
|var=||d1.<em>join</em>(delimiter = FM)||Joins all elements into a single delimited string
<em>Returns:</em> A string var.
|}
=== Array Mutation ===
{|class="wikitable"
!Usage!!Function!!Description
|-
|dim2||d1.<em>splitter</em>(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>
|-
|dim2||d1.<em>sorter</em>(reverse = false)||Sort the elements of the array. In place.
<em>reverse:</em> Defaults to false. If true, then the order is reversed.
|-
|dim2||d1.<em>reverser</em>()||Reverse the elements of the array. In place.
|-
|dim2||d1.<em>shuffler</em>()||Randomly shuffle the order of the elements of the array in place.
|}
=== Array Conversion ===
{|class="wikitable"
!Usage!!Function!!Description
|-
|dim||d1.<em>sort</em>(reverse = false)||Same as sorter() but returns a new array leaving the original untouched.
|-
|dim||d1.<em>reverse</em>()||Same as reverser() but returns a new array leaving the original untouched.
|-
|dim||d1.<em>shuffle</em>()||Same as shuffler() but returns a new array leaving the original untouched.
|}
=== Array Db I/O ===
{|class="wikitable"
!Usage!!Function!!Description
|-
|cmd||d1.<em>write</em>(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.<em>read</em>(dbfile, key)||Read a db file record into an array.
Each field in the database record becomes a single element in the array.
<em>Returns:</em> 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"
!Usage!!Function!!Description
|-
|if||d1.<em>oswrite</em>(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.
<em>codepage:</em> Optional: Data is converted from UTF8 to the required codepage/encoding before output. If the conversion cannot be performed then return false.
<em>Returns:</em> 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.<em>osread</em>(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.
<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>Returns:</em> 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>
|}:

Revision as of 10:06, 1 March 2025

ICONV/OCONV PATTERNS

Decimal (MD/MC)

input conversion (string) output
1234 MD2 12.34
1234 MD20 1234.00
1234 MD20, 1,234.00
1234.5678 MD2 12.35
1234.5678 MD20 1234.57
1234.5678 MD20, 1,234.57
1234 MC2 12,34
1234 MC20 1234,00
1234 MC20, 1.234,00
1234 MD20- 1234.00

Date (D)

input conversion (string) output
12345 D 18 OCT 2001
12345 D/ 10/18/2001
12345 D- 10-18-2001
12345 D2 18 OCT 01
12345 D/E 18/10/2001
12345 DS 2001 OCT 18
12345 DS/ 2001/10/18
12345 DM 10
12345 DMA OCTOBER
12345 DY 2001
12345 DY2 01
12345 DD 18
12345 DW 4
12345 DWA THURSDAY
12345 DQ 4
12345 DJ 291
12345 DL 31

Time (MT)

input conversion (string) output
234800 MT 17:13
234800 MTH 05:13PM
234800 MTS 17:13:20
234800 MTHS 05:13:20PM
0 MT 00:00
0 MTH 12:00AM
0 MTS 00:00:00
0 MTHS 12:00:00AM

Hex (HEX/MX)

input conversion (string) output
ab HEX (same as HEX8 or HEX4 depending on platform)
ab HEX8 0000006100000062
ab HEX4 00610062
ab HEX2 6162
15 MX F
254 MX FE
255 MX FF
256 MX 100
27354234 MX 1A1647A

Text (L/R/T)

input conversion (string)output
abcd L#3 abc
ab L#3 ab␣
abcd R#3 bcd
ab R#3 ␣ab
ab T#3 ab␣
abcd T#3 abc™d␣␣
42 L(0)#5 42000
42 R(0)#5 00042
42 T(0)#5 42000

Dictionaries

Exodus dictionaries enable classic multivalue database data definition. Dictionaries are just normal Exodus multivalue files that contain one record for each data column definition. You can use Exodus's edir program to manually edit dictionaries.

Dictionary file names must start with the word "dict_". For example, if you have a "books" file, then you will probably have a "dict_books" file.

You can list the contents of a dictionary by typing "list dict_filename".

Exodus Dictionary Format

0 DICTID Field/Column Code
1 DICTTYPE "F" or "S" : "F" means use Field No (i.e. raw data) and "S" means use Source Code (i.e. a function).
2 FIELDNO Field number (0=key, 1=field 1 etc for "Fields"
3 TITLE Title on reports
4 SM S or M or Mnn : "Single Value" or "Multivalue" or "Multivalue Group nn"
5 KEYPARTNO Multipart keys are separated by * characters.
6
7 CONVERSION Conversion (MD/MT/D etc.)
8 SOURCE Source Code of a subroutine to calculate the field. Multivalues are lines and the result must be placed in a variable "ANS".
9 JUST "L" or "R" or "T" requesting left, right or text justification
10 WIDTH Column Width on fixed width reports

Sort/Select Command

Exodus provides the classic multivalue sort/select command within any Exodus program followed by readnext().

Classic multivalue select/readnext functions only provide the keys of the selected records. Exodus provides the classic select/readnext and also selectrecords/readnextrecord which provides complete records instead of just keys.

The format of the select/sselect command is as follows: 

 SELECT|SSELECT

 {max_number_of_records}

 {using filename}

 filename

 {datakeyvalue} ...

 {BY|BY-DSND fieldname} ...
 
 {

  WITH

  {NO|ALL|ANY}

  dict_field_id

  {
   CONTAINING|STARTING|ENDING|LIKE|EQ|NE|NOT|GT|LT|GE|LE=|<>|>|<|>=|<= value(s)
   |
   BETWEEN value AND value
  }

  {AND|OR}

 } ...

Functions and Commands

String Commands

Most string functions like trim() that return a new modified string have a corresponding modify in place command like function like trimmer() that is is usually much faster. So we have convert and converter, replace and replacer, insert and inserter and so on.

Therefore by preference use 

trimmer(v1);
// or
v1.trimmer()

instead of 

v1 = trim(v1);
// or
v1 = v1.trim();

Function Types

TYPE FUNCTION TYPE
var= traditional functions that return values and can be used in expressions and be on the right hand side of assignments
if traditional conditional statements that started with "if" or ended with "then/else" (or could have)
cmd traditional commands with no outputs
expr traditional commands that now have outputs and can be used in expressions

Parameters/Argument Types

in Parameters that provide data to the function. Can be variables or raw data like 1 or "X"
unspecified Same as "in". Omission of the most common type de-clutters the documentation. NB When defining your own subroutines and functions "in" cannot be omitted from the source code.
io Parameters that may provide and/or return data. Must be variables. Cannot be raw data like 1 or "X"
out Parameters that return data. Must be variables. Cannot be raw data like 1 or "X"

Optional Parameters

Key Default
= "" ""
= " " " "
= "." "."
= 1 1
= 0 0
= true true
= false false

Field mark characters

Exodus implements a PICK OS data structure called a "dynamic array". This is simply any string which uses six specific unprintable ASCII delimiter characters (\x1A to \x1F) to separate its various parts. The parts are referred to as records, fields, values, subvalues, text, and subtext and fall within each other.

Dynamic arrays therefore implement sparse six dimensional arrays.

Typical CPU caching architecture favours similar values being adjacent in memory therefore implementing them as strings of values separated by delimiter characters can have performance advantages over more complex structures.

In practice the vast majority of dynamic arrays consist of "fields" separated by the FM character (\x1E) but it is very common for fields to have values separated by the VM character (\x1D) and values to have subvalues using SM (\x1D).

Since the six delimiter characters fall in the unprintable character range certain other characters have been designated as usable for coding and printing. For example the FM character is represented as ^ and can be entered in source code appended with _var to indicate that the string must be converted to internal format. 

var v1 = "f1^f2^f3"_var; // Three fields

var v2 = "f1^v1]v2]v3^f3"_var; // Three fields, 2nd field has 3 values. It is "multivalued".

Anything which contains a collection of fields can be considered as a "record" and records can be stored in files with a unique primary key. The fields might represent different columns of a traditional database table. So anonymous field number 1 might be a contact name, field 2 the contact address, field 3 a multivalued list of contact points. etc.

Delimiter
name		 var Hex Display cstr " " char ' '
Record Mark RM \x1F ` _RM RM_
Field Mark FM \x1E ^ _FM FM_
Value Mark VM \x1D ] _VM VM_
Subvalue Mark SM \x1C } _SM SM_
Text Mark TM \x1B | _TM TM_
Subtext Mark STM \x1A ~ _STM STM_
Delimiter Name : Record Mark Field Mark Value Mark Subvalue Mark Text Mark Subtext Mark
var : RM FM VM SM TM STM
Display : ` ^ ] } | ~
Hex : \x1F \x1E \x1D \x1C \x1B \x1A
cstr " " : _RM _FM _VM _SM _TM _STM
char ' ' : RM_ FM_ VM_ SM_ TM_ STM_

Complete List of Functions

Retrieved from "https://devwiki.neosys.com/index.php?title=Manual&oldid=1600"