Functions wikifmt

Complete List of Functions

Generated by cli/gendoc from var.h

String Creation

Usage	Function	Description
var=	varnum.round(ndecimals = 0)	Returns: A var containing an ASCII string with the number of decimal places requested. .5 always rounds away from zero. 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" Negative number of decimals rounds to the left of the decimal point let v1 = round(123456.789, 0); // "123457" let v2 = round(123456.789, -1); // "123460" let v3 = round(123456.789, -2); // "123500"
var=	var().chr(num)	Returns: A string containing a single char (byte) given an integer 0-255. 0-127 -> ASCII, 128-255 -> invalid UTF-8 which cannot be written to the database or used in many exodus string operations let v1 = var().chr(0x61); // "a" // or let v2 = chr(0x61);
var=	var().textchr(num)	Returns: A string of a single unicode code point in utf8 encoding. To get utf codepoints > 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. let v1 = var().textchr(171416); // "𩶘" // or "\xF0A9B698" // or let v2 = textchr(171416);
var=	var().str(num)	Returns: A string of repeating characters or strings let v1 = "ab"_var.str(3); // "ababab" // or let v2 = str("ab", 3);
var=	varnum.space()	Returns: A string of space characters. let v1 = var(3).space(); // "␣␣␣" // or let v2 = space(3);
var=	varnum.numberinwords(languagename_or_locale_id = "")	Returns: A string representing a given number written in words instead of digits. locale: Something like en_GB, ar_AE, el_CY, es_US, fr_FR etc. let softhyphen = "\xc2\xad"; let v1 = var(123.45).numberinwords("de_DE").replace(softhyphen, " "); // "ein␣hundert␣drei␣und␣zwanzig␣Komma␣vier␣fünf"

String Scanning

Usage	Function	Description
var=	var().seq()	Returns: The character number of the first char. let v1 = "abc"_var.seq(); // 0x61 // decimal 97 // or let v2 = seq("abc");
var=	var().textseq()	Returns: The Unicode character number of the first unicode code point. let v1 = "Γ"_var.textseq(); // 915 // U+0393: Greek Capital Letter Gamma (Unicode Character) // or let v2 = textseq("Γ");
var=	var().len()	Returns: The length of a string in number of chars let v1 = "abc"_var.len(); // 3 // or let v2 = len("abc");
if	var().empty()	Returns: true if the var is an empty string. 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. let v1 = "0"; if (not v1.empty()) ... ok /// true // or if (not empty(v1)) ... ok // true
var=	var().textwidth()	Returns: The number of output columns. Allows multi column unicode and reduces combining characters etc. like e followed by grave accent Possibly does not properly calculate combining sequences of graphemes e.g. face followed by colour let v1 = "🤡x🤡"_var.textwidth(); // 5 // or let v2 = textwidth("🤡x🤡");
var=	var().textlen()	Returns: The number of Unicode code points let v1 = "Γιάννης"_var.textlen(); // 7 // or let v2 = textlen("Γιάννης");
var=	var().fcount(sepstr)	Returns: The count of the number of fields separated by a given sepstr. It is the same as var.count(sepstr) + 1 except that it returns 0 for an empty string. let v1 = "aa**cc"_var.fcount("*"); // 3 // or let v2 = fcount("aa**cc", "*");
var=	var().count(sepstr)	Returns: The count of the number of sepstr found. let v1 = "aa**cc"_var.count("*"); // 2 // or let v2 = count("aa**cc", "*");
if	var().starts(prefix)	Returns: True if starts with prefix if ("abc"_var.starts("ab")) ... true // or if (starts("abc", "ab")) ... true
if	var().ends(suffix)	Returns: True if ends with suffix if ("abc"_var.ends("bc")) ... true // or if (ends("abc", "bc")) ... true
if	var().contains(substr)	Returns: True if starts, ends or contains substr if ("abcd"_var.contains("bc")) ... true // or if (contains("abcd", "bc")) ... true
var=	var().index(substr, startchar1 = 1)	Returns: The index (1 based position) of a given substr on or after a given starting char number if present Returns: 0 if not present. let v1 = "abcd"_var.index("bc"); // 2 // or let v2 = index("abcd", "bc");
var=	var().indexn(substr, occurrence)	Returns: The index (1 based position) of the nth occurrence of a given substr if present Returns: 0 if not present. let v1 = "abcabc"_var.index("bc", 2); // 2 // or let v2 = index("abcabc", "bc", 2);
var=	var().indexr(substr, startchar1 = -1)	Reverse substr search. Returns: The index (1 based position) of the substr on or before a given starting char number if present startchar1 defaults to -1 meaning start searching from the last char (towards the first char). let v1 = "abcabc"_var.indexr("bc"); // 5 // or let v2 = indexr("abcabc", "bc");
var=	var().match(regex_str, regex_options = "")	Returns: All results of regex matching Multiple matches are returned separated by FMs. Groups are in VMs. let v1 = "abc1abc2"_var.match("BC(\\d)", "i"); // "bc1]1^bc2]2"_var // or let v2 = match("abc1abc2", "BC(\\d)", "i"); regex_options: 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().
var=	var().match(regex)	Ditto
var=	var().search(regex_str, io startchar1, regex_options = "")	Search for first match of a regular expression starting at startchar1 Updates startchar1 ready to search for the next match regex_options as for match() 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");
var=	var().search(regex_str)	Ditto starting from first char
var=	var().search(regex, io startchar1)	Ditto given a rex
var=	var().search(regex)	Ditto starting from first char.
var=	var().hash(std::uint64_t modulus = 0)	Hash by default returns a 64 bit signed integer as a var. If a modulus is provided then the result is limited to [0, modulus) MurmurHash3 is used. let v1 = "abc"_var.hash(); assert(v1 == var(6'715'211'243'465'481'821)); // or let v2 = hash("abc");

String Conversion - Non-Mutating - Chainable

Usage	Function	Description
var=	var().ucase()	To upper case let v1 = "Γιάννης"_var.ucase(); // "ΓΙΆΝΝΗΣ" // or let v2 = ucase("Γιάννης");
var=	var().lcase()	To lower case let v1 = "ΓΙΆΝΝΗΣ"_var.lcase(); // "γιάννης" // or let v2 = lcase("ΓΙΆΝΝΗΣ");
var=	var().tcase()	To title case. The first letter of each word is capitalised. let v1 = "γιάννης παππάς"_var.tcase(); // "Γιάννης Παππάς" // or let v2 = tcase("γιάννης παππάς");
var=	var().fcase()	To folded case to enable standardised indexing and searching, Case folding is a process of converting a text to 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. let v1 = "Grüßen"_var.fcase(); // "grüssen" // or let v2 = tcase("Grüßen");
var=	var().normalize()	Normalises unicode code points sequences to their standardised NFC form making them binary comparable. Unicode normalization is the process of converting strings to a standard form, suitable for text processing and comparison, and is an important part of Unicode text processing. For example, character "é" can be represented by a single code point "\u00E9" (Latin Small Letter E with Acute) or a combination of the character "e" and the combining acute accent "\u0301". Normalization is not locale-dependent. let v1 = "cafe\u0301"_var.normalize(); // "café" // or let v2 = normalize("cafe\u0301");
var=	var().invert()	Simple reversible disguising of text invert(invert()) returns to the original text. Flips bit 8 of unicode code points. Note that ASCII bytes become multibyte UTF-8 so string sizes change. let v1 = "abc"_var.invert(); // "\xC2" "\x9E" "\xC2" "\x9D" "\xC2" "\x9C" // or let v2 = invert("abc");
var=	var().lower()	Convert all FM to VM, VM to SM etc. let v1 = "a1^b2^c3"_var.lower(); // "a1]b2]c3"_var // or let v2 = lower("a1^b2^c3"_var);
var=	var().raise()	Convert all VM to FM, SM to VM etc. let v1 = "a1]b2]c3"_var.raise(); // "a1^b2^c3"_var // or let v2 = "a1]b2]c3"_var;
var=	var().crop()	Remove any redundant FM, VM etc. characters (Trailing FM; VM before FM etc.) let v1 = "a1^b2]]^c3^^"_var.crop(); // "a1^b2^c3"_var // or let v2 = crop("a1^b2]]^c3^^"_var);
var=	var().quote()	Wrap in double quotes let v1 = "abc"_var.quote(); // "\"abc\"" // or let v2 = quote("abc");
var=	var().squote()	Wrap in single quotes let v1 = "abc"_var.squote(); // "'abc'" // or let v2 = squote("abc");
var=	var().unquote()	Remove one pair of double or single quotes let v1 = "'abc'"_var.unquote(); // "abc" // or let v2 = unquote("'abc'");
var=	var().trim(trimchars = " ")	Remove leading, trailing and excessive inner bytes let v1 = "␣␣a1␣␣b2␣c3␣␣"_var.trim(); // "a1␣b2␣c3" // or let v2 = trim("␣␣a1␣␣b2␣c3␣␣");
var=	var().trimfirst(trimchars = " ")	Ditto leading let v1 = "␣␣a1␣␣b2␣c3␣␣"_var.trimfirst(); // "a1␣␣b2␣c3␣␣" // or let v2 = trimfirst("␣␣a1␣␣b2␣c3␣␣");
var=	var().trimlast(trimchars = " ")	Ditto trailing let v1 = "␣␣a1␣␣b2␣c3␣␣"_var.trimlast(); // "␣␣a1␣␣b2␣c3" // or let v2 = trimlast("␣␣a1␣␣b2␣c3␣␣");
var=	var().trimboth(trimchars = " ")	Ditto leading, trailing but not inner let v1 = "␣␣a1␣␣b2␣c3␣␣"_var.trimboth(); // "a1␣␣b2␣c3" // or let v2 = trimboth("␣␣a1␣␣b2␣c3␣␣");
var=	var().first()	Extract first char or "" if empty let v1 = "abc"_var.first(); // "a" // or let v2 = first("abc");
var=	var().last()	Extract last char or "" if empty let v1 = "abc"_var.last(); // "c" // or let v2 = last("abc");
var=	var().first(std::size_t length)	Extract up to length leading chars let v1 = "abc"_var.first(2); // "ab" // or let v2 = first("abc", 2);
var=	var().last(std::size_t length)	Extract up to length trailing chars let v1 = "abc"_var.last(2); // "bc" // or let v2 = last("abc", 2);
var=	var().cut(length)	Remove length leading chars let v1 = "abcd"_var.cut(2); // "cd" // or let v2 = cut("abcd", 2);
var=	var().paste(pos1, length, insertstr)	Insert text at char position overwriting length chars let v1 = "abcd"_var.paste(2, 2, "XYZ"); // "aXYZd" // or let v2 = paste("abcd", 2, 2, "XYZ");
var=	var().paste(pos1, insertstr)	Insert text at char position without overwriting any following characters let v1 = "abcd"_var.paste(2, "XYZ"); // "aXYZbcd" // or let v2 = paste("abcd", 2, "XYZ");
var=	var().prefix(insertstr)	Insert text at the beginning let v1 = "abc"_var.prefix("XYZ"); // "XYZabc" // or let v2 = prefix("abc", "XYZ");
var=	var().append(appendable, ...)	Append text at the end let v1 = "abc"_var.append(" is ", 10, " ok", '.'); // "abc is 10 ok." // or let v2 = append("abc", " is ", 10, " ok", '.');
var=	var().pop()	Remove one trailing char let v1 = "abc"_var.pop(); // "ab" // or let v2 = pop("abc");
var=	var().field(strx, fieldnx = 1, nfieldsx = 1)	Extract one or more consecutive fields given a delimiter char or substr. let v1 = "aa*bb*cc"_var.field("*", 2); // "bb" // or let v2 = field("aa*bb*cc", "*", 2);
var=	var().field2(separator, fieldno, nfields = 1)	field2 is a version that treats fieldn -1 as the last field, -2 the penultimate field etc. - TODO Should probably make field() do this (since -1 is basically an erroneous call) and remove field2 Same as var.field() but negative fieldnos work backwards from the last field. let v1 = "aa*bb*cc"_var.field2("*", -1); // "cc" // or let v2 = field2("aa*bb*cc", "*", -1);
var=	var().fieldstore(separator, fieldno, nfields, replacement)	fieldstore() replaces n fields of subfield(s) in a string. let v1 = "aa*bb*cc*dd"_var.fieldstore("*", 2, 3, "X*Y"); // "aa*X*Y*" // or let v2 = fieldstore("aa*bb*cc*dd", "*", 2, 3, "X*Y"); If nfields is 0 then insert fields before fieldno let v1 = "a1*b2*c3*d4"_var.fieldstore("*", 2, 0, "X*Y"); // "a1*X*Y*b2*c3*d4" // or let v2 = fieldstore("a1*b2*c3*d4", "*", 2, 0, "X*Y"); If nfields is negative then delete abs(n) fields before inserting. let v1 = "a1*b2*c3*d4"_var.fieldstore("*", 2, -3, "X*Y"); // "a1*X*Y" // or let v2 = fieldstore("a1*b2*c3*d4", "*", 2, -3, "X*Y");
var=	var().substr(pos1, length)	substr version 1. Extract length chars starting at pos1 let v1 = "abcd"_var.substr(2, 2); // "bc" // or let v2 = substr("abcd", 2, 2); If length is negative then work backwards and return chars reversed let v1 = "abcd"_var.substr(3, -2); // "cb" // or let v2 = substr("abcd", 3, -2);
var=	var().b(pos1, length)	Same as substr version 1.
var=	var().substr(pos1)	substr version 2. Extract all chars from pos1 up to the end let v1 = "abcd"_var.substr(2); // "bcd" // or let v2 = substr("abcd", 2);
var=	var().b(pos1)	Same as substr version 2.
var=	var().substr(pos1, delimiterchars, io pos2)	substr version 3. Extract a substr starting from pos1 up to any one of some given delimiter chars Also returns in pos2 the pos of the following delimiter or one past the end of the string if not found. Add 1 to pos2 start the next search if continuing. var pos1a = 4, pos2a; let v1 = "aa,bb,cc"_var.substr(pos1a, ",", pos2a); // "bb" // pos2a -> 6 // or var pos1b = 4, pos2b; let v2 = substr("aa,bb,cc", pos1b, ",", pos2b);
var=	var().b(pos1, delimiterchars, io pos2)	Alias of substr version 3.
var=	var().substr2(io pos1, out delimiterno)	substr version 4. Returns: A substr from a given pos1 up to the next RM/FM/VM/SM/TM/ST delimiter char. Also returns the next index/offset and the delimiter no. found (1-6) or 0 if not found. var pos1a = 4, delim1; let v1 = "aa^bb^cc"_var.substr2(pos1a, delim1); // "bb" // pos1a -> 7 // delim1 -> 2 // or var pos1b = 4, delim2; let v2 = substr2("aa^bb^cc"_var, pos1b, delim2);
var=	var().b2(io pos1, out delimiterno)	Alias of substr version 4
var=	var().convert(fromchars, tochars)	Convert chars to other chars one for one or delete where tochars is shorter. let v1 = "abcde"_var.convert("aZd", "XY"); // "Xbce" // a is replaced and d is removed // or let v2 = convert("abcde", "aZd", "XY");
var=	var().textconvert(fromchars, tochars)	Ditto for Unicode code points. let v1 = "a🤡b😀c🌍d"_var.textconvert("🤡😀", "👋"); // "a👋bc🌍d" // or let v2 = textconvert("a🤡b😀c🌍d", "🤡😀", "👋");
var=	var().replace(fromstr, tostr)	Replace all occurrences of a substr with another. Case sensitive let v1 = "Abc.Abc"_var.replace("bc", "X"); // "AX.AX" // or let v2 = replace("Abc Abc", "bc", "X");
var=	var().replace(regex, tostr)	Replace substring(s) using a regular expression. Use $0, $1, $2 in tostr to refer to groups defined in the regex. 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'");
var=	var().unique()	Remove duplicate fields in an FM or VM etc. separated list let v1 = "a1^b2^a1^c2"_var.unique(); // "a1^b2^c2"_var // or let v2 = unique("a1^b2^a1^c2"_var);
var=	var().sort(sepchar = FM)	Reorder fields in an FM or VM etc. separated list in ascending order Numerical: 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); Alphabetical: 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);
var=	var().reverse(sepchar = FM)	Reorder fields in an FM or VM etc. separated list in descending order 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);
var=	var().shuffle(sepchar = FM)	Randomise the order of fields in an FM, VM separated list 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);
var=	var().parse(char sepchar = ' ')	Replace separator characters with FM char except inside double or single quotes ignoring escaped quotes \" \' 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", ',');

String Conversion - Mutating - Standalone Commands

Usage	Function	Description
cmd	var().ucaser()	Upper case All string mutators follow the same pattern as ucaser. See the non-mutating functions for details. var v1 = "abc"; v1.ucaser(); // "ABC" // or ucaser(v1);
cmd	var().lcaser()
cmd	var().tcaser()
cmd	var().fcaser()
cmd	var().normalizer()
cmd	var().inverter()
cmd	var().quoter()
cmd	var().squoter()
cmd	var().unquoter()
cmd	var().lowerer()
cmd	var().raiser()
cmd	var().cropper()
cmd	var().trimmer(trimchars = " ")
cmd	var().trimmerfirst(trimchars = " ")
cmd	var().trimmerlast(trimchars = " ")
cmd	var().trimmerboth(trimchars = " ")
cmd	var().firster()
cmd	var().laster()
cmd	var().firster(std::size_t length)
cmd	var().laster(std::size_t length)
cmd	var().cutter(length)
cmd	var().paster(pos1, length, insertstr)
cmd	var().paster(pos1, insertstr)
cmd	var().prefixer(insertstr)
cmd	var().appender(appendable, ...)
cmd	var().popper()
cmd	var().fieldstorer(sepchar, fieldno, nfields, replacement)
cmd	var().substrer(pos1, length)
cmd	var().substrer(pos1)
cmd	var().converter(fromchars, tochars)
cmd	var().textconverter(fromchars, tochars)
cmd	var().replacer(regex, tostr)
cmd	var().replacer(fromstr, tostr)
cmd	var().uniquer()
cmd	var().sorter(sepchar = FM)
cmd	var().reverser(sepchar = FM)
cmd	var().shuffler(sepchar = FM)
cmd	var().parser(char sepchar = ' ')

I/O Conversion

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 let v1 = var(30123).oconv("D/E"); // "21/06/2050" // or let v2 = oconv(30123, "D/E");
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 let v1 = "21 JUN 2050"_var.iconv("D/E"); // 30123 // or let v2 = iconv("21 JUN 2050", "D/E");
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. 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));
var=	var.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. let v1 = "\xa4"_var.from_codepage("CP1124"); // "Є" // or let v2 = from_codepage("\xa4", "CP1124"); // U+0404 Cyrillic Capital Letter Ukrainian Ie Unicode Character
var=	var.to_codepage(codepage)	Converts to codepage encoded text from UTF-8 encoded text let v1 = "Є"_var.to_codepage("CP1124").oconv("HEX"); // "A4" // or let v2 = to_codepage("Є", "CP1124").oconv("HEX");

Dynamic Array Functions

Usage	Function	Description
var=	var.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. let v1 = "f1^f2v1]f2v2]f2v3^f2"_var; let v2 = v1.f(2, 2); // "f2v2"
var=	var.extract(fieldno, valueno = 0, subvalueno = 0)	Extract a specific field, value or subvalue from a dynamic array. 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);
var=	var.pickreplace(fieldno, valueno, subvalueno, replacement)	Same as var.r() function but returns a new string instead of updating a variable in place. Rarely used.
var=	var.pickreplace(fieldno, valueno, replacement)	Ditto for a specific multivalue
var=	var.pickreplace(fieldno, replacement)	Ditto for a specific field
var=	var.insert(fieldno, valueno, subvalueno, insertion)	Same as var.inserter() function but returns a new string instead of updating a variable in place.
var=	var.insert(fieldno, valueno, insertion)	Ditto for a specific multivalue
var=	var.insert(fieldno, insertion)	Ditto for a specific field
var=	var.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

Usage	Function	Description
var=	var.sum()	Sum up multiple values into one higher level let v1 = "1]2]3^4]5]6"_var.sum(); // "6^15"_var // or let v2 = sum("1]2]3^4]5]6"_var);
var=	var.sumall()	Sum up all levels into a single figure let v1 = "1]2]3^4]5]6"_var.sumall(); // 21 // or let v2 = sumall("1]2]3^4]5]6"_var);
var=	var.sum(sepchar)	Ditto allowing commas etc. let v1 = "10,20,30"_var.sum(","); // 60 // or let v2 = sum("10,20,30", ",");
var=	var.mv(opcode, var2)	Binary ops (+, -, *, /) in parallel on multiple values let v1 = "10]20]30"_var.mv("+","2]3]4"_var); // "12]23]34"_var

Dynamic Array Mutators Standalone Commands

Usage	Function	Description
cmd	var.r(fieldno, replacement)	Replaces a specific field in a dynamic array var v1 = "f1^v1]v2}s2}s3^f3"_var; v1.r(2, "X"); // "f1^X^f3"_var
cmd	var.r(fieldno, valueno, replacement)	Ditto for specific value in a specific field. var v1 = "f1^v1]v2}s2}s3^f3"_var; v1.r(2, 2, "X"); // "f1^v1]X^f3"_var
cmd	var.r(fieldno, valueno, subvalueno, replacement)	Ditto for a specific subvalue in a specific value of a specific field var v1 = "f1^v1]v2}s2}s3^f3"_var; v1.r(2, 2, 2, "X"); // "f1^v1]v2}X}s3^f3"_var
cmd	var.inserter(fieldno, insertion)	Insert a specific field in a dynamic array, moving all other fields up. 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");
cmd	var.inserter(fieldno, valueno, insertion)	Ditto for a specific value in a specific field, moving all other values up. 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");
cmd	var.inserter(fieldno, valueno, subvalueno, insertion)	Ditto for a specific subvalue in a dynamic array, moving all other subvalues up. 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");
cmd	var.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. var v1 = "f1^v1]v2}s2}s3^f3"_var; v1.remover(2, 2); // "f1^v1^f3"_var // or remover(v1, 2, 2);

Dynamic Array Search

Usage	Function	Description
var=	var.locate(target)	locate() with only the target substr argument provided searches unordered values separated by any of the field mark chars. Returns: The field, value, subvalue etc. number if found or 0 if not. if ("UK^US^UA"_var.locate("US")) ... ok // 2 // or if (locate("US", "UK^US^UA"_var)) ... ok
if	var.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. Returns: True if found Setting: Field, value, subvalue etc. number if found or the max number + 1 if not. Suitable for additiom of new values var setting; if ("UK]US]UA"_var.locate("US", setting)) ... ok // setting -> 2 // or if (locate("US", "UK]US]UA"_var, setting)) ... ok
if	var.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. Returns: True if found and with the field, value or subvalue number in setting. Returns: 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. var setting; if ("f1^f2v1]f2v2]s1}s2}s3}s4^f3^f4"_var.locate("s4", setting, 2, 3)) ... ok // setting -> 4 // returns true
if	var.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. Returns: True if found. In case the target is not exactly found then the correct value no for inserting the target is returned in setting. var valueno; if ("aaa]bbb]ccc"_var.locateby("AL", "bb", valueno)) ... // valueno -> 2 // returns false and valueno = where it could be correctly inserted.
if	var.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. 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.
if	var.locateusing(usingchar, target)	locate() a target substr in the whole unordered string using a given delimiter char returning true if found. if ("AB,EF,CD"_var.locateusing(",", "EF")) ... ok
if	var.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 Returns: True If found and returns in setting the number of the delimited field found. Returns: 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. var setting; if ("f1^f2^f3c1,f3c2,f3c3^f4"_var.locateusing(",", "f3c2", setting, 3)) ... ok // setting -> 2 // returns true
if	var.locatebyusing(ordercode, usingchar, target, out setting, fieldno = 0, valueno = 0, subvalueno = 0)	locatebyusing() supports all the above features in a single function. Returns: True if found.

Database Access

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. let conninfo = "dbname=exodus user=exodus password=somesillysecret"; if (not conn.connect(conninfo)) ...; // or if (not connect()) ... // or if (not connect("exodus")) ...
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 let filenames = "definitions^dict.definitions"_var, conn = "exodus"; if (conn.attach(filenames)) ... ok // or if (attach(filenames)) ... ok
cmd	conn.detach(filenames)	Detach (disconnect) files that have been attached using attach().
if	conn.begintrans()	Begin a db transaction. if (not conn.begintrans()) ... // or if (not begintrans()) ...
if	conn.statustrans()	Check if a db transaction is in progress. if (conn.statustrans()) ... ok // or if (statustrans()) ... ok
if	conn.rollbacktrans()	Rollback a db transaction. if (conn.rollbacktrans()) ... ok // or if (rollbacktrans()) ... ok
if	conn.committrans()	Commit a db transaction. Returns: True if successfully committed or if there was no transaction in progress, otherwise false. if (conn.committrans()) ... ok // or if (committrans()) ... ok
if	conn.sqlexec(sqlcmd)	Execute an sql command. Returns: True if there was no sql error otherwise lasterror() returns a detailed error message. if (conn.sqlexec("vacuum")) ... ok // or if (sqlexec("vacuum")) ... ok
if	conn.sqlexec(sqlcmd, io response)	Execute an SQL command and capture the response. Returns: True if there was no sql error otherwise response contains a detailed error message. response: Any rows and columns returned are separated by RM and FM respectively. The first row is the column names. Recommended: Don't use sql directly unless you must to manage or configure a database. 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) character. The backtick character is used here by gendoc to deliminate source code. // or if (sqlexec(sqlcmd, response)) ... ok
cmd	conn.disconnect()	Closes db connection and frees process resources both locally and in the database server. conn.disconnect(); // or disconnect();
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. conn.disconnectall(); // or disconnectall();
var=	conn.lasterror()	Returns: The last os or db error message. var v1 = var().lasterror(); // or var v2 = lasterror();
var=	conn.loglasterror(source = "")	Log the last os or db error message. Output: to stdlog Prefixes the output with source if provided. var().loglasterror("main:"); // or loglasterror("main:");

Database Management

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. var conn = "exodus"; if (not dbdelete("xo_gendoc_testdb")) {}; // Cleanup first if (conn.dbcreate("xo_gendoc_testdb")) ... ok // or if (dbcreate("xo_gendoc_testdb")) ...
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. 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")) ...
var=	conn.dblist()	Returns: A list of available databases on a particular connection. let v1 = conn.dblist(); // or let v2 = dblist();
if	conn.dbdelete(dbname)	Delete (drop) a named database. The target database must exist and cannot have any current connections. var conn = "exodus"; if (conn.dbdelete("xo_gendoc_testdb2")) ... ok // or if (dbdelete("xo_gendoc_testdb2")) ...
if	conn.createfile(filename)	Create a named db file. let filename = "xo_gendoc_temp", conn = "exodus"; if (conn.createfile(filename)) ... ok // or if (createfile(filename)) ...
if	conn.renamefile(filename, newfilename)	Rename a db file. 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)) ...
var=	conn.listfiles()	Returns: A list of all files in a database var conn = "exodus"; if (not conn.listfiles()) ... // or if (not listfiles()) ...
if	conn.clearfile(filename)	Delete all records in a db file let conn = "exodus", filename = "xo_gendoc_temp2"; if (not conn.clearfile(filename)) ... // or if (not clearfile(filename)) ...
if	conn.deletefile(filename)	Delete a db file let conn = "exodus", filename = "xo_gendoc_temp2"; if (conn.deletefile(filename)) ... ok // or if (deletefile(filename)) ...
var=	conn_or_file.reccount(filename = "")	Returns: The approx. number of records in a db file let conn = "exodus", filename = "xo_clients"; var nrecs1 = conn.reccount(filename); // or var nrecs2 = reccount(filename);
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

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. var file, filename = "definitions"; if (not file.open(filename)) ... // or if (not open(filename to file)) ...
cmd	file.close()	Closes db file var Does nothing currently since database file vars consume no resources var file = "definitions"; file.close(); // or close(file);
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. Returns: 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. var filename = "definitions", fieldname = "DATE_TIME"; if (not deleteindex("definitions", "DATE_TIME")) {}; // Cleanup first if (filename.createindex(fieldname)) ... ok // or if (createindex(filename, fieldname)) ...
var=	conn.listindex(file_or_filename = "", fieldname = "")	Lists secondary indexes in a database or for a db file Returns: False if the db file or fieldname are given and do not exist var conn = "exodus"; if (conn.listindex()) ... ok // includes "xo_clients__date_time" // or if (listindex()) ... ok
if	file.deleteindex(fieldname)	Deletes a secondary index for a db file and field name. Returns: False if the index cannot be deleted for any reason File does not exist Index does not already exists var file = "definitions", fieldname = "DATE_TIME"; if (file.deleteindex(fieldname)) ... ok // or if (deleteindex(file, fieldname)) ...
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. var file = "xo_clients", key = "1000"; if (file.lock(key)) ... ok // or if (lock(file, key)) ...
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. Returns: False if the lock is not present in a connection. var file = "xo_clients", key = "1000"; if (file.unlock(key)) ... ok // or if (unlock(file, key)) ...
if	file.unlockall()	Removes all db locks placed by the lock function in the specified connection. Locks cannot be removed while in a transaction. var conn = "exodus"; if (not conn.unlockall()) ... // or if (not unlockall(conn)) ...
cmd	rec.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. let rec = "Client GD^G^20855^30000^1001.00^20855.76539"_var; let file = "xo_clients", key = "GD001"; if (not deleterecord("xo_clients", "GD001")) {}; // Cleanup first rec.write(file, key); // or write(rec on file, key);
if	rec.read(file, key)	Reads a record from a db file for a given key. Returns: False if the key doesnt exist var rec; let file = "xo_clients", key = "GD001"; if (not rec.read(file, key)) ... // rec -> "Client GD^G^20855^30000^1001.00^20855.76539"_var // or if (not read(rec from file, key)) ...
if	file.deleterecord(key)	Deletes a record from a db file given a key. Returns: False if the key doesnt exist Any memory cached record is deleted. let file = "xo_clients", key = "GD001"; if (file.deleterecord(key)) ... ok // or if (deleterecord(file, key)) ...
if	rec.insertrecord(file, key)	Inserts a new record in a db file. Returns: False if the key already exists Any memory cached record is deleted. let rec = "Client GD^G^20855^30000^1001.00^20855.76539"_var; let file = "xo_clients", key = "GD001"; if (rec.insertrecord(file, key)) ... ok // or if (insertrecord(rec on file, key)) ...
if	rec.updaterecord(file, key)	Updates an existing record in a db file. Returns: False if the key doesnt already exist Any memory cached record is deleted. let rec = "Client GD^G^20855^30000^1001.00^20855.76539"_var; let file = "xo_clients", key = "GD001"; if (not rec.updaterecord(file, key)) ... // or if (not updaterecord(rec on file, key)) ...
if	rec.readf(file, key, fieldno)	"Read field" Same as read() but only returns a specific field from the record 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)) ...
cmd	rec.writef(file, key, fieldno)	"write field" Same as write() but only writes to a specific field in the record var field = "f3", file = "definitions", key = "1000", fieldno = 3; field.writef(file, key, fieldno); // or writef(field on file, key, fieldno);
cmd	rec.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. let rec = "Client XD^X^20855^30000^1001.00^20855.76539"_var; let file = "xo_clients", key = "XD001"; rec.writec(file, key); // or writec(rec on file, key);
if	rec.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. var rec; let file = "xo_clients", key = "XD001"; if (rec.readc(file, key)) ... ok // or if (readc(rec from file, key)) ... ok // Verify not in actual database file by using read() not readc() if (read(rec from file, key)) abort("Error: " ^ key ^ " should not be in the actual database file"); // error
if	dbfile.deletec(key)	Deletes a record and key from a memory cached "file". The actual database file is NOT updated. Returns: False if the key doesnt exist var file = "xo_clients", key = "XD001"; if (file.deletec(key)) ... ok // or if (deletec(file, key)) ...
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. conn.cleardbcache(); // or cleardbcache(conn);
var=	conn.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. Arguments: strvar: Used as the primary key to lookup a field in a given file and field no or field name. filename: The db file in which to look up data. If var key is multivalued then a multivalued field is returned. fieldno: Determines which field of the record is returned. Integer returns that field number 0 means return the key unchanged. "" means return the whole record. mode: Determines what is returned if the record does not exist for the given key and file. "X" returns "" "C" returns the key unconverted. 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)"

Database Sort/Select

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. dbfile: 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. sort_select_command: 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. Example: "select xo_clients with type 'B' and with balance ge 100 by type by name" Option: "(R)" appended to the sort_select_command acquires the database records as well. Returns: True if any records are selected or false if none. Throws: 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. 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);
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. keys: An FM separated list of keys or key^VM^valueno pairs. Returns: True if any keys are provided or false if not. 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");
if	dbfile.hasnext()	Checks if a select list is active. dbfile: A file or connection var used in a prior select, selectkeys or getlist function call. Returns: 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. var clients = "xo_clients", key; if (clients.select()) { assert(clients.hasnext()); } // or if (select("xo_clients")) { assert(hasnext()); }
if	dbfile.readnext(out key)	Acquires and consumes one key from an active select list of database record keys. dbfile: A file or connection var used in a prior select, selectkeys or getlist function call. key: Returns the first (next) key present in an active select list or "" if no select list is active. Returns: 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. record: Returns the next database record from the select list assuming that the select list was created with the (R) option otherwise "" if not. key: Returns the next database record key in the select list. valueno: The multivalue number if the select list was ordered on multivalued database record fields or 1 if not. 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"));
cmd	dbfile.clearselect()	Deactivates an active select list. dbfile: A file or connection var used in a prior select, selectkeys or getlist function call. Returns: Nothing Has no effect if no select list is active for dbfile. var clients = "xo_clients"; clients.clearselect(); if (not clients.hasnext()) ... ok // or clearselect(); if (not hasnext()) ... ok
if	dbfile.savelist(listname)	Stores an active select list for later retrieval. dbfile: A file or connection var used in a prior select, selectkeys or getlist function call. listname: A suitable name that will be required for later retrieval. Returns: 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. 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 }
if	dbfile.getlist(listname)	Retrieve and reactivate a saved select list. dbfile: A file or connection var to be used by subsequent readnext function calls. listname: The name of an existing list in the "lists" database file, either created by savelist or manually. Returns: 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. 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); }
if	dbfile.deletelist(listname)	Delete a saved select list. dbfile: A file or connection to the desired database. listname: The name of an existing list in the "lists" database file. Returns: True if successful or false if the list name doesnt exist. var conn = ""; if (conn.deletelist("mylist")) ... ok // or if (deletelist("mylist")) ... ok

OS Time/Date

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 let today1 = var().date(); // or let today2 = date();
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. let now1 = var().time(); // or let now2 = time();
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 let now1 = var().ostime(); // or let now2 = ostime();
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 let now1 = var().timestamp(); // or let now2 = timestamp();
var=	var().timestamp(ostime)	Construct a timestamp from a date and time 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);
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. var().ossleep(100); // sleep for 100ms // or ossleep(100);
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. let v1 = ".^/etc/hosts"_var.oswait(100); /// e.g. "IN_CLOSE_WRITE^/etc^hosts^f"_var // or let v2 = oswait(".^/etc/hosts"_var, 100); Returned array fields 1. Event type codes 2. dirpaths 3. filenames 4. d=dir, f=file 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

OS File I/O

Usage	Function	Description
if	osfilevar.osopen(osfilename, utf8 = true)	Given the name of an existing os file name including path, initialises an os file handle var that can be used in random access osbread and osbwrite functions. The utf8 option defaults to true which causes trimming of partial utf-8 unicode byte sequences from the end of osbreads. For raw untrimmed osbreads pass utf8 = false; File will be opened for writing if possible otherwise for reading. Returns: True if successful or false if not possible for any reason. e.g. Target doesnt exist, permissions etc. 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
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. 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)) ...
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. 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
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. osfilevar.osclose(); // or osclose(osfilevar);
if	osfilevar.oswrite(osfilename, codepage = "")	Create a complete os file from a var. Any existing os file is removed first. Returns: 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. 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
if	osfilevar.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. Returns: True if successful or false if not possible for any reason. e.g. File doesnt exist, permissions etc. 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
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. Returns: 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. 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)) ...
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. Returns: 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. 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)) ...
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 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
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 Returns: True if successful or false if not possible for any reason. e.g. Target doesnt exist, path is not writeable, permissions etc. let osfilename = ostempdirpath() ^ "xo_gendoc_test.conf"; if (osfilename.osremove()) ... ok // or if (osremove(osfilename)) ...

OS Directories

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. var entries1 = "/etc/"_var.oslist("*.cfg"); /// e.g. "adduser.conf^ca-certificates.con^... etc." // or var entries2 = oslist("/etc/" "*.conf");
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() var info1 = "/etc/hosts"_var.osinfo(); /// e.g. "221^20597^78309"_var // or var info2 = osinfo("/etc/hosts");
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) var fileinfo1 = "/etc/hosts"_var.osfile(); /// e.g. "221^20597^78309"_var // or var fileinfo2 = osfile("/etc/hosts");
var=	dirpath.osdir()	Returns: Dir info for a dir. A short string containing FM ^ modified_time ^ FM ^ modified_time Alias for osinfo(2) var dirinfo1 = "/etc/"_var.osdir(); /// e.g. "^20848^44464"_var // or var dirinfo2 = osfile("/etc/");
if	dirpath.osmkdir()	Makes a new directory and returns true if successful. Including parent dirs if necessary. let osdirname = "xo_test/aaa"; if (osrmdir("xo_test/aaa")) {}; // Cleanup first if (osdirname.osmkdir()) ... ok // or if (osmkdir(osdirname)) ...
if	dirpath.oscwd(newpath)	Changes the current working dir and returns true if successful. let osdirname = "xo_test/aaa"; if (osdirname.oscwd()) ... ok // or if (oscwd(osdirname)) ... ok
var=	dirpath.oscwd()	Returns: The current working directory e.g. "/root/exodus/cli/src/xo_test/aaa" var cwd1 = var().oscwd(); // or var cwd2 = oscwd();
if	dirpath.osrmdir(evenifnotempty = false)	Removes a os dir and returns true if successful. Optionally even if not empty. Including subdirs. let osdirname = "xo_test/aaa"; if (oscwd("../..")) ... ok /// Change up before removing because cannot remove dir while it is current if (osdirname.osrmdir()) ... ok // or if (osrmdir(osdirname)) ...

OS Shell/Environment

Usage	Function	Description
if	command.osshell()	Execute a shell command. Returns: True if the process terminates with error status 0 and false otherwise. Append "&>/dev/null" to the command to suppress terminal output. let cmd = "echo $HOME"; if (cmd.osshell()) ... ok // or if (osshell(cmd)) ... ok
if	instr.osshellread(oscmd)	Same as osshell but captures and returns stdout Returns: The stout of the shell command. Append "2>&1" to the command to capture stderr/stdlog output as well. let cmd = "echo $HOME"; var text; if (text.osshellread(cmd)) ... ok // or capturing stdout but ignoring exit status text = osshellread(cmd);
if	outstr.osshellwrite(oscmd)	Same as osshell but provides stdin to the process Returns: True if the process terminates with error status 0 and false otherwise. Append "&> somefile" to the command to suppress and/or capture output. let outtext = "abc xyz"; if (outtext.osshellwrite("grep xyz")) ... ok // or if (osshellwrite(outtext, "grep xyz")) ... ok
var=	var().ostempdirpath()	Returns: The path of the tmp dir e.g. "/tmp/" let v1 = var().ostempdirpath(); // or let v2 = ostempdirpath();
var=	var().ostempfilename()	Returns: The name of a new temporary file e.g. Something like "/tmp/~exoEcLj3C" var temposfilename1 = var().ostempfilename(); // or var temposfilename2 = ostempfilename();
cmd	envvalue.ossetenv(envcode)	Set the value of an environment variable code let envcode = "EXO_ABC", envvalue = "XYZ"; envvalue.ossetenv(envcode); // or ossetenv(envcode, envvalue);
if	envvalue.osgetenv(envcode)	Get the value of an environment variable var envvalue1; if (envvalue1.osgetenv("HOME")) ... ok // e.g. "/home/exodus" // or var envvalue2 = osgetenv("EXO_ABC"); // "XYZ"
var=	var().ospid()	Get the os process id let pid1 = var().ospid(); /// e.g. 663237 // or let pid2 = ospid();
var=	var().ostid()	Get the os thread process id let tid1 = var().ostid(); /// e.g. 663237 // or let tid2 = ostid();
var=	var().version()	Get the libexodus build date and time let v1 = var().version(); /// e.g. "29 JAN 2025 14:56:52"
if	strvar.setxlocale()	Sets the current thread's default locale codepage code True if successful if ("en_US.utf8"_var.setxlocale()) ... ok // or if (setxlocale("en_US.utf8")) ... ok
var=	var.getxlocale()	Returns: The current thread's default locale codepage code let v1 = var().getxlocale(); // "en_US.utf8" // or let v2 = getxlocale();

Output

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. "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.
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 characters present are converted to their visible versions, "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.
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 characters present are converted to their visible versions, "abc"_var.errputl("xyz = "); /// Sends "xyz = abc\n" to stderr // or errputl("xyz = ", "abc"); /// Any number of arguments is allowed. All will be output.
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. var().osflush(); // or osflush();

Input

Usage	Function	Description
expr	var.input(prompt = "")	Returns one line of input from stdin. Returns raw bytes up to but excluding the first new line character. Prompt: Optional. Will be displayed before the input field if provided. If stdin is a terminal then the initial value of the var, if any, is the default value and can be edited with cursor keys like an OS command line. Pressing Enter or Ctrl+D will complete the input. // var v1 = "default"; v1.input("Prompt:"); // or // var v2 = input();
expr	var.inputn(nchars)	Get raw bytes from standard input. Any new line characters are treated like any other bytes. Care must be taken to handle incomplete UTF8 byte sequences at the end of one block and the beginning of the next block. Returns: The requested number of bytes or fewer if not available. nchars: 99 : Get up to 99 bytes or fewer if not available. Caution required with UTF8. ⋅0 : Get all bytes presently available. ⋅1 : Same as keypressed(true). Deprecated. -1 : Same as keypressed(). Deprecated.
expr	var.keypressed(wait = false)	Return the code of the current terminal key pressed. wait: Defaults to false. True means wait for a key to be pressed if not already pressed. Returns: ASCII or key code defined according to terminal protocol. Returns: "" 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. var v1; v1.keypressed(); // or var v2 = keypressed();
if	var().isterminal(arg = 1)	Checks if one of stdin, stdout, stderr is a terminal or a file/pipe. arg: 0 - stdin, 1 - stdout (Default), 2 - stderr. Returns: 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. var v1 = var().isterminal(); /// 1 or 0 // or var v2 = isterminal();
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. Returns: 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 characters to be reflected to stdout if stdin is a terminal. Turning terminal echo off can be used to prevent display of confidential information. Returns: 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

Usage	Function	Description
var=	varnum.abs()	Absolute value let v1 = var(-12.34).abs(); // 12.34 // or let v2 = abs(-12.34);
var=	varnum.pwr(exponent)	Power let v1 = var(2).pwr(8); // 256 // or let v2 = pwr(2, 8);
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; var(123).initrnd(); /// Set seed to 123 // or initrnd(123);
var=	varnum.rnd()	Pseudo random number generator Returns: a pseudo random integer between 0 and the provided maximum minus 1. Uses std::mt19937 and std::uniform_int_distribution<int> let v1 = var(100).rnd(); /// Random 0 to 99 // or let v2 = rnd(100);
var=	varnum.exp()	Power of e let v1 = var(1).exp(); // 2.718281828459045 // or let v2 = exp(1);
var=	varnum.sqrt()	Square root let v1 = var(100).sqrt(); // 10 // or let v2 = sqrt(100);
var=	varnum.sin()	Sine of degrees let v1 = var(30).sin(); // 0.5 // or let v2 = sin(30);
var=	varnum.cos()	Cosine of degrees let v1 = var(60).cos(); // 0.5 // or let v2 = cos(60);
var=	varnum.tan()	Tangent of degrees let v1 = var(45).tan(); // 1 // or let v2 = tan(45);
var=	varnum.atan()	Arctangent of degrees let v1 = var(1).atan(); // 45 // or let v2 = atan(1);
var=	varnum.loge()	Natural logarithm Returns: Floating point ver (double) let v1 = var(2.718281828459045).loge(); // 1 // or let v2 = loge(2.718281828459045);
var=	varnum.integer()	Truncate decimal numbers towards zero Returns: An integer var 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);
var=	varnum.floor()	Truncate decimal numbers towards negative Returns: An integer var 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);
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) Throws: VarDivideByZero if modulus is zero. Floating point works. 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

I/O Conversion Codes

Usage	Function	Description
var=	vardate.oconv_D(conversion)	Date output: Convert internal date format to human readable date or calendar info in text format. Returns: Human readable date or calendar info, or the original value unconverted if non-numeric. Flags: See examples below. Any multifield/multivalue structure is preserved. 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" );
var=	varstr.iconv_D(conversion)	Date input: Convert human readable date to internal date format. Returns: 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. // 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);
var=	vartime.oconv_MT(conversion)	Time output: Convert internal time format to human readable time e.g. "10:30:59". Returns: Human readable time or the original value unconverted if non-numeric. Conversion code (e.g. "MTHS") is "MT" + flags ... Flags: "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 character instead of ":" Any multifield/multivalue structure is preserved. 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" );
var=	varstr.iconv_MT(strict)	Time input: Convert human readable time (e.g. "10:30:59") to internal time format. Returns: Internal time or "" if the input is an invalid time. Internal time format is whole seconds since midnight. Accepts: Two or three groups of digits surrounded and separated by any non-digits character(s). Any multifield/multivalue structure is preserved. 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);
var=	varnum.oconv_MD(conversion)	Number output: Convert internal numbers to external text format after rounding and optional scaling. Returns: 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. Flags: "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 ">" characters. "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. 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" );
var=	var.oconv_LRC(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. 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 character (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" );
var=	varstr.oconv_T(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 characters. ASCII only. 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 );
var=	varstr.oconv_HEX(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. 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");
var=	varstr.iconv_HEX(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.oconv_MX()	Numeric hex format: Convert number to hexadecimal string If the value is not numeric then no conversion is performed and the original value is returned. assert( var("255").oconv("MX") == "FF"); // or assert( oconv(var("255"), "MX") == "FF");
var=	varnum.oconv_MB()	Numeric 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. assert( var(255).oconv("MB") == 1111'1111); // or assert( oconv(var(255), "MB") == 1111'1111);
var=	varstr.oconv_TX(conversion)	Convert dynamic arrays to standard text format. Useful for using text editors on dynamic arrays. FMs -> NL after escaping any embedded NL // 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 "🌍");
var=	varstr.iconv_TX(conversion)	Convert standard text format to dynamic array. Reverse of oconv("TX") above.