Manual

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
exp	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

Complete List of Functions

Generated by cli/gendoc from var.h at 29JAN2025 8:13PM

Math/Boolean

Usage	Function	Comment
var=	num.abs()	Absolute value var(-12.34).abs(); // 12.34
var=	num.pwr(exponent)	Power var(2).pwr(8); // 256
var=	num.rnd()	Pseudo random number generator var(100).rnd(); // 0 to 99 pseudo random
cmd	num.initrnd()	Initialise the seed for rnd() var(123).initrnd(); // Set seed to 123
var=	num.exp()	Power of e var(1).exp(); // 2.718281828459045
var=	num.sqrt()	Square root var(100).sqrt(); // 10
var=	num.sin()	Sine of degrees var(30).sin(); // 0.5
var=	num.cos()	Cosine of degrees var(60).cos(); // 0.5
var=	num.tan()	Tangent of degrees var(45).tan(); // 1
var=	num.atan()	Arctangent of degrees var(1).atan(); // 45
var=	num.loge()	Natural logarithm var(2.718281828459045).loge(); // 1
var=	num.integer()	Truncate decimal numbers towards zero. var(2.9).integer(); // 2 var(-2.9).integer(); // -2
var=	num.floor()	Truncate decimal numbers towards negative var(2.9).floor(); // 2 var(-2.9).floor(); // -3
var=	num.round(ndecimals = 0)	Round decimal numbers to a desired number of decimal places .5 always rounds away from zero. var(0.455).round(2); // "0.46" var(-0.455).round(2); // "-0.46" var(1.455).round(2); // "1.46" var(-1.455).round(2); // "-1.46"
var=	num.mod(divisor)

Locale

Usage	Function	Comment
expr	var.getxlocale()	Gets the current thread's default locale codepage code var().getxlocale(); // e.g. "en_US.utf8" getxlocale(); // ditto
if	str.setxlocale()	Sets the current thread's default locale codepage code if (not "de_DE.utf8"_var.setxlocale()) ... // true if successful if (setxlocale("de_DE.utf8")) ... // ditto

String Creation

Usage	Function	Comment
var=	var.chr(num)	Create a string of a single char (byte) given an integer 0-255. 0-127 -> ASCII, 128-255 -> invalid UTF-8 so cannot be written to database or used various exodus string operations var().chr(0x61); // "a" chr(0x61); // ditto
var=	var.textchr(num)	Create a string of a single unicode code point in utf8 encoding. To get utf codepoints > 2^63 you must provide negative ints Not providing implicit constructor from var to unsigned int due to getting ambigious conversions since int and unsigned int are parallel priority in c++ implicit conversions var().textchr(171416); // "𩶘" or "\xF0A9B698" textchr(171416); // ditto
var=	var.str(num)	Create a string by repeating a given character or string "ab"_var.str(3); // "ababab" str("ab"_var, 3); // ditto
var=	num.space()	Create string of space characters. var(3).space(); // "␣␣␣" space(3); // ditto
var=	num.numberinwords(languagename_or_locale_id = "")	Create a string describing a given number in words var(123.45).numberinwords("de_DE"); //"ein­hundert­drei­und­zwanzig Komma vier fünf"

String Scanning

Usage	Function	Comment
var=	str.seq()	Returns the character number of the first char. "abc"_var.seq(); // 0x61 97 seq("abc"_var); // 0x61 97
var=	str.textseq()	Returns the Unicode character number of the first unicode code point. "Γ"_var.textseq(); // 915 U+0393: Greek Capital Letter Gamma (Unicode Character) textseq("Γ"); // ditto
var=	str.len()	Returns the length of a string in number of chars "abc"_var.len(); // 3 len("abc"_var); // ditto
var=	str.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 "🤡x🤡"_var.textwidth(); // 5 textwidth("🤡x🤡"_var); // ditto
var=	str.textlen()	Returns the number of Unicode code points "Γιάννης"_var.textlen(); // 7 textlen("Γιάννης"_var); // ditto
var=	str.fcount(sepstr)	Returns the number of fields separated by sepstr present. It is the same as var.count(sepstr) + 1 except that and empty string returns 0 "a1**c3"_var.fcount("*"); // 3 fcount("a1**c3"_var, "*"); // ditto
var=	str.count(sepstr)	Return the number of sepstr found "a1*b2*c3"_var.count("*"); // 3 count("a1*b2*c3"_var, "*"); // ditto
if	str.starts(prefix)	Returns true if starts with prefix "abc"_var.starts("ab"); // true
if	str.ends(suffix)	Returns true if ends with suffix "abc"_var.ends("bc"); // true
if	str.contains(substr)	Returns true if starts, ends or contains substr "abcd"_var.contains("bc"); // true
var=	str.index(substr, startchar1 = 1)	Returns char no if found or 0 if not. startchar1 is byte no to start at. "abcd"_var.index("bc"); // 2
var=	str.indexn(substr, occurrence)	ditto. Occurrence 1 = find first occurrence "abcabc"_var.index("bc", 2); // 5
var=	str.indexr(substr, startchar1 = -1)	ditto. Reverse search. startchar1 defaults to -1 meaning start searching from the last byte "abcabc"_var.indexr("bc"); // 5
var=	str.match(regex, regex_options = "")	Returns all results of regex matching Multiple matches are in fields. Groups are in values "abc1abc2"_var.match("bc(\\d)"); // "bc1]1^bc2]2" 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=	str.match(regex)	Ditto
var=	str.search(regex, 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; "abc1abc2"_var.search("bc(\\d)", startchar1); // returns "bc1]1" // startchar1 becomes 5 ready for the next search
var=	str.search(regex)	Ditto starting from first char
var=	str.search(regex, io startchar1)	Ditto given a rex
var=	str.search(regex)	Ditto starting from first char.

String Conversion - Chainable. Non-Mutating

Usage	Function	Comment
var=	str.ucase()	Upper case "Γιάννης"_var.ucase(); // "ΓΙΆΝΝΗΣ"
var=	str.lcase()	Lower case "ΓΙΆΝΝΗΣ"_var.lcase(); // "γιάννης"
var=	str.tcase()	Title case (first letters) "γιάννης"_var.tcase(); // "Γιάννης"
var=	str.fcase()	Fold case (lower case and remove accents for indexing)
var=	str.normalize()	Normalise Unicode to NFC to eliminate different code combinations of the same character
var=	str.invert()	Simple reversible disguising of text "abc"_var.invert(); // "\x{C29EC29DC29C}"
var=	str.lower()	Convert all FM to VM, VM to SM etc. "a1^b2^c3"_var.lower(); // "a1]b2]c3"
var=	str.raise()	Convert all VM to FM, SM to VM etc. "a1]b2]c3"_var.raise(); // "a1^b2^c3"
var=	str.crop()	Remove any redundant FM, VM etc. characters (Trailing FM; VM before FM etc.) "a1^b2]]^c3^^"_var.crop(); // "a1^b2^c3"
var=	str.quote()	Wrap in double quotes "abc"_var.quote(); // ""abc""
var=	str.squote()	Wrap in single quotes "abc"_var.squote(); // "'abc'"
var=	str.unquote()	Remove one pair of double or single quotes "'abc'"_var.unquote(); // "abc"
var=	str.trim(trimchars = " ")	Remove leading, trailing and excessive inner bytes "␣␣a1␣␣b2␣c3␣␣"_var.trim(); // "a1␣b2␣c3"
var=	str.trimfirst(trimchars = " ")	Ditto leading "␣␣a1␣␣b2␣c3␣␣"_var.trimfirst(); // "a1␣␣b2␣c3␣␣"
var=	str.trimlast(trimchars = " ")	Ditto trailing "␣␣a1␣␣b2␣c3␣␣"_var.trimlast(); // "␣␣a1␣␣b2␣c3"
var=	str.trimboth(trimchars = " ")	Ditto leading, trailing but not inner "␣␣a1␣␣b2␣c3␣␣"_var.trimboth(); // "a1␣␣b2␣c3"
var=	str.first()	Extract first char or "" if empty "abc"_var.first(); // "a"
var=	str.last()	Extract last char or "" if empty "abc"_var.last(); // "c"
var=	str.first(std::size_t length)	Extract up to length leading chars "abc"_var.first(2); // "ab"
var=	str.last(std::size_t length)	Extract up to length trailing chars "abc"_var.last(2); // "bc"
var=	str.cut(length)	Remove length leading chars "abcd"_var.cut(2); // "cd"
var=	str.paste(pos1, length, insertstr)	Insert text at char position overwriting length chars "abcd"_var.paste(2, 2, "XYZ"); // "aXYZd"
var=	str.paste(pos1, insertstr)	Insert text at char position without overwriting any following characters "abcd"_var.paste(2, "XYZ"); // "aXYbcd"
var=	str.prefix(insertstr)	Insert text at the beginning "abc"_var.prefix("XY"); // "XYabc"
var=	str.pop()	Remove one trailing char "abc"_var.pop(); // "ab"
var=	str.fieldstore(separator, fieldno, nfields, replacement)	fieldstore() replaces nfields of subfield(s) in a string. "aa*bb*cc*dd"_var.fieldstore("*", 2, 3, "X*Y"); // "aa*X*Y*" If nfields is 0 then insert fields before fieldno "a1*b2*c3*d4"_var.fieldstore("*", 2, 0, "X*Y"); // "a1*X*Y*b2*c3*d4" If nfields is negative then delete nfields before inserting. "a1*b2*c3*d4"_var.fieldstore("*", 2, -3, "X*Y"); // "a1*X*Y"
var=	str.substr(pos1, length)	substr version 1. Extract length chars starting at pos1 "abcd"_var.substr(2, 2); // "bc" If length is negative then work backwards and return chars reversed "abcd"_var.substr(3, -2); // "cb"
var=	str.substr(pos1)	substr version 2. Extract all chars from pos1 up to the end "abcd"_var.substr(2); // "bcd"
var=	str.b(pos1, length)	Same as substr version 1.
var=	str.b(pos1)	Same as substr version 2.
var=	str.convert(fromchars, tochars)	Convert chars to other chars one for one or delete where tochars is shorter. "abcde"_var.convert("aZd", "XY"); // "Xbce" (a is replaced and d is removed)
var=	str.textconvert(fromchars, tochars)	Ditto for Unicode code points. "a🤡b😀c🌍d"_var.textconvert("🤡😀", "👋"); // "a👋bc🌍d"
var=	str.replace(fromstr, tostr)	Replace all occurrences of a substr with another. Case sensitive "Abc Abc"_var.replace("bc", "X"); // "AX AX"
var=	str.replace(regex, tostr)	Replace substring(s) using a regular expression. Use $0, $1, $2 in tostr to refer to groups defined in the regex. "A a B b"_var.replace("[A-Z]"_rex, "'$0'"); // "'A' a 'B' b"
var=	str.unique()	Remove duplicate fields in an FM or VM etc. separated list "a1^b2^a1^c2"_var.unique(); // "a1^b2^c2"
var=	str.sort(sepchar = FM)	Reorder fields in an FM or VM etc. separated list in ascending order "20^10^2^1^1.1"_var.sort(); // "1^1.1^2^10^20" "b1^a1^c20^c10^c2^c1^b2"_var.sort(); // "a1^b1^b2^c1^c10^c2^c20"
var=	str.reverse(sepchar = FM)	Reorder fields in an FM or VM etc. separated list in descending order "20^10^2^1^1.1"_var.reverse(); // "1.1^1^2^10^20"
var=	str.shuffle(sepchar = FM)	Randomise the order of fields in an FM, VM separated list "20^10^2^1^1.1"_var.shuffle(); // "2^1^20^1.1^10" (random order depending on initrand())
var=	str.parse(char sepchar = ' ')	Replace separator characters with FM char except inside double or single quotes ignoring escaped quotes \\" \&squot; "abc,\"def,\"123\" fgh\",12.34"_var.parse(','); // "abc^"def,"123" fgh"^12.34"

String Mutators Not Chainable. All Similar To Non-Mutators

Usage	Function	Comment
cmd	str.ucaser()
cmd	str.lcaser()
cmd	str.tcaser()
cmd	str.fcaser()
cmd	str.normalizer()
cmd	str.inverter()
cmd	str.quoter()
cmd	str.squoter()
cmd	str.unquoter()
cmd	str.lowerer()
cmd	str.raiser()
cmd	str.cropper()
cmd	str.trimmer(trimchars = " ")
cmd	str.trimmerfirst(trimchars = " ")
cmd	str.trimmerlast(trimchars = " ")
cmd	str.trimmerboth(trimchars = " ")
cmd	str.firster()
cmd	str.laster()
cmd	str.firster(std::size_t length)
cmd	str.laster(std::size_t length)
cmd	str.cutter(length)
cmd	str.paster(pos1, length, insertstr)
cmd	str.paster(pos1, insertstr)
cmd	str.prefixer(insertstr)
cmd	str.popper()
cmd	str.fieldstorer(sepchar, fieldno, nfields, replacement)
cmd	str.substrer(pos1, length)
cmd	str.substrer(pos1)
cmd	str.converter(fromchars, tochars)
cmd	str.textconverter(fromchars, tochars)
cmd	str.replacer(regex, tostr)
cmd	str.replacer(fromstr, tostr)
cmd	str.uniquer()
cmd	str.sorter(sepchar = FM)
cmd	str.reverser(sepchar = FM)
cmd	str.shuffler(sepchar = FM)
cmd	str.parser(char sepchar = ' ')

Other String Access

Usage	Function	Comment
var=	str.hash(std::uint64_t modulus = 0)	MurmurHash3 hashing. "abc"_var.hash(); // 6715211243465481821
var=	str.substr(pos1, delimiterchars, out pos2)	substr version 3. Extract a substr starting from pos1 up to any one of the given delimiter chars also returning the next pos1 after the delimiter found
var=	str.b(pos1, delimiterchars, out pos2)	Alias of substr version 3.
var=	str.substr2(io pos1, io delimiterno)	substr version 4. Returns a substr from a given pos1 up to the next RM/FM/VM/SM/TM/STM delimiter char. Also returns the next index/offset and the delimiter no. found 1-6 or 0 if not found.
var=	str.b2(io pos1, io delimiterno)	Alias of substr version 4
var=	str.field(strx, fieldnx = 1, nfieldsx = 1)	Extract one or more consecutive fields given a delimiter char or substr. "aa*bb*cc"_var.field("*", 2);m // "bb"
var=	str.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. "aa*bb*cc"_var.field("*", -1); // "cc"

I/O Conversion

Usage	Function	Comment
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 var(30123).oconv("D/E"); // "21/06/2050"
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 "21 JUN 2050"_var.iconv("D/E"); // 30123
var=	var.format(fmt_str, Args&&... 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. var(12.345).format("'{:_>8.2f}' should match '{::MD20P|R(_)#8}'", var(12.345)); // -> "'___12.35' should match '___12.35'" // or format("'{:_>8.2f}' should match '{::MD20P|R(_)#8}'", var(12.345), var(12.345));
var=	str.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. "\xa4"_var.from_codepage("CP1124"); // "Є" // U+0404 Cyrillic Capital Letter Ukrainian Ie Unicode Character
var=	str.to_codepage(codepage)	Converts to codepage encoded text from UTF-8 encoded text "Є"_var.to_codepage("CP1124").oconv("HEX"); // "A4"

Basic Dynamic Array Functions

Usage	Function	Comment
var=	str.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. "f1^f2v1]f2v2]f2v3^f2"_var.f(2, 2); // "f2v2"
var=	str.extract(fieldno, valueno = 0, subvalueno = 0)	Extract a specific field, value or subvalue from a dynamic array. The alias "f" is usually used instead
var=	str.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=	str.pickreplace(fieldno, valueno, replacement)	Ditto for a specific multivalue
var=	str.pickreplace(fieldno, replacement)	Ditto for a specific field
var=	str.insert(fieldno, valueno, subvalueno, insertion)	Same as var.inserter() function but returns a new string instead of updating a variable in place.
var=	str.insert(fieldno, valueno, insertion)	Ditto for a specific multivalue
var=	str.insert(fieldno, insertion)	Ditto for a specific field
var=	str.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	Comment
var=	str.sum()	Sum up multiple values into one higher level "1]2]3^4]5]6"_var.sum(); // "6^15"
var=	str.sumall()	Sum up all levels into a single figure "1]2]3^4]5]6"_var.sumall(); // "21"
var=	str.sum(sepchar)	Ditto allowing commas etc. "10,20,33"_var.sum(","); // "60"
var=	str.mv(opcode, var2)	Binary ops (+, -, *, /) in parallel on multiple values "10]20]30"_var.mv("+","2]3]4"); // "12]23]34"

Dynamic Array Mutators (Standalone And Cannot Be Chained)

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

Dynamic Array Search

Usage	Function	Comment
if	str.locate(target)	locate() with only the target substr argument provided searches unordered values separated by VM chars. Returns true if found and false if not. if ("UK]US]UA"_var.locate("US")) ... // true
if	str.locate(target, out valueno)	locate() with only the target substr and valueno arguments provided searches unordered values separated by VM chars. Returns true if found and with the value number in valueno. Returns false if not found and with the max value number + 1 in setting. Suitable for additiom of new values var valueno; if ("UK]US]UA"_var.locate("US", valueno)) ... // returns true and valueno = 2
if	str.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)) ... // returns true and setting = 4
if	str.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)) ... // returns false and valueno = 2 where it could be correctly inserted.
if	str.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)) ... // returns false and setting = 2 where it could be correctly inserted.
if	str.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")) ... // true
if	str.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)) ... // returns true and setting = 2
if	str.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	Comment
if	conn.connect(conninfo = "")	For all db operations, var() can be db connection created with dbconnect() or any var will perform a default connection. 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 defaults "host=127.0.0.1 port=5432 dbname=exodus user=exodus password=somesillysecret connect_timeout=10" var db="mydb"; if (not db.connect()) abort(db.lasterror()); db.version().outputl(); db.disconnect();
cmd	conn.disconnect()	Removes a db connection and frees resources.
cmd	conn.disconnectall()	Removes all db connection and frees resources.
if	conn.attach(filenames)	Attach (connect) specific files by name to specific connections. For the remainder of the session, opening the file by name will automatically use the specified connection.
cmd	conn.detach(filenames)	Detach (disconnect) files that have been attached using attach().
if	conn.begintrans()	Begin a db transaction.
if	conn.rollbacktrans()	Rollback a db transaction.
if	conn.committrans()	Commit a db transaction.
if	conn.statustrans()	Check if a db transaction is in progress.
if	conn.sqlexec(sqlcmd)	Execute an sql command.
if	conn.sqlexec(sqlcmd, io response)	Execute an SQL command and capture the response.
var=	conn.lasterror()	Get the last os or db error message.
var=	conn.loglasterror(source = "")	Log the last os or db error message.

Database Management

Usage	Function	Comment
if	conn.dbcreate(dbname)	Create a named database on a particular connection.
var=	conn.dblist()	Return a list of available databases on a particular connection.
if	conn.dbcopy(from_dbname, to_dbname)	Create a named database from an existing database.
if	conn.dbdelete(dbname)	Delete (drop) a named database.
if	conn.createfile(filename)	Create a named db file.
if	conn.renamefile(filename, newfilename)	Rename a db file.
if	conn.deletefile(filename)	Delete (drop) a db file
if	conn.clearfile(filename)	Delete all records in a db file
var=	conn.listfiles()	Return a list of all files in a database
var=	conn.reccount(filename = "")	Returns the approx. number of records in a file
if	conn.flushindex(filename = "")	Calls db maintenance function (vacuum) This doesnt flush any indexes any longer but does make sure that reccount() function is reasonably accurate.

Database File I/O

Usage	Function	Comment
if	file.open(dbfilename, connection = "")
cmd	file.close()
if	file.createindex(fieldname, dictfile = "")
if	file.deleteindex(fieldname)
var=	file.listindex(filename = "", fieldname = "")
var=	file.lock(key)	Returns 1=ok, 0=failed, ""=already locked
if	file.unlock(key)
if	file.unlockall()
if	rec.read(file, key)	Reads a record from a file given its unique primary key. Returns false if the key doesnt exist var rec; if (not rec.read(file, key)) ...
cmd	rec.write(file, key)	Writes a record to a file. It updates an existing record if the key already exists or inserts a new record. It always succeeds so no result code is returned. Any memory cached record is deleted. rec.write(file, key);
if	rec.updaterecord(file, key)	Updates an existing record in a file. Returns false if the key doesnt already exist Any memory cached record is deleted. if (not rec.updaterecord(file, key)) ...
if	rec.insertrecord(file, key)	Inserts a new record in a file. Returns false if the key already exists Any memory cached record is deleted. if (not rec.insertrecord(file, key)) ...
if	file.deleterecord(key)	Deletes a record from a file given its key. Returns false if the key doesnt exist Any memory cached record is deleted. if (not file.deleterecord(key)) ...
if	str.readf(file, key, fieldno)	Same as read() but only returns a specific field no from the record var field; if (not field.readf(file, key, fieldno)) ...
cmd	str.writef(file, key, fieldno)	Same as write() but only writes a specific field no to the record field.writef(file, key, fieldno);
if	rec.readc(file, key)	Cache read a record from a memory cache "file" given its key. 1. Tries to read from a memory cache and returns true if successful. 2. Reads to read from the actual file and returns false if unsuccessful. 3. Writes the record and key to the memory cache and returns true. Cached db file data lives in exodus process memory not the database. var rec; if (not rec.readc(file, key)) ...
cmd	rec.writec(file, key)	Cache write a record and key into a memory cached "file". The actual file is NOT updated. It either updates an existing record if the key already exists or otherwise inserts a new record. It always succeeds so no result code is returned. rec.writec(file, key);
if	dbfile.deletec(key)	Deletes a record and key from a memory cached "file". The actual file is NOT updated. Returns false if the key doesnt exist if (not file.deletec(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();
var=	str.xlate(filename, fieldno, mode)

Database Sort/Select

Usage	Function	Comment
if	file.select(sortselectclause = "")
cmd	file.clearselect()
if	file.hasnext()
if	file.readnext(out key)
if	file.readnext(out key, out valueno)
if	file.readnext(out record, out key, out valueno)
if	file.savelist(listname)
if	file.getlist(listname)
if	file.makelist(listname, keys)
if	file.deletelist(listname)
if	file.formlist(keys, fieldno = 0)

OS Time/Date

Usage	Function	Comment
var=	var.date()	Number of whole days since pick epoch 1967-12-31 00:00:00 UTC. Negative for dates before. var today1 = var().date(); // e.g. was 20821 from 2025-01-01 00:00:00 UTC // or just var today2 = date();
var=	var.time()	Number of whole seconds since last 00:00:00 (UTC). var now1 = var().time(); // range 0 - 86399 since there are 24*60*60 (86400) seconds in a day. // or just var 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. var now1 = var().ostime(); // e.g. 23343.704387955 approx. 06:29:03 UTC // or just var 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. var now1 = var().timestamp(); // was 20821.99998842593 around 2025-01-01 23:59:59 UTC // or just var now2 = ostimestamp();
var=	var.timestamp(ostime)	Construct a timestamp from a date and time var ts1 = var().timestamp(iconv("2025-01-01", "D"), iconv("23:59:59", "MT")); // 20821.99998842593 // or just var ts2 = timestamp(somedate, sometime);
cmd	var.ossleep(milliseconds)	Sleep/pause/wait for a number of milliseconds var().ossleep(3000); // sleep for 3 seconds // or just ossleep(3000);
var=	var.oswait(milliseconds, directory)	Sleep/pause/wait for any activity in a file system directory for a number of milliseconds var().oswait(3000, "."); // max 3 seconds // or just oswait(3000, ".");

OS File Io

Usage	Function	Comment
if	osfilevar.osopen(osfilename, locale = "")	Given the name of an existing file name including path, initialises a var that can be used in random access osbread and osbwrite functions. Optionally allows specifying a locale/codepage to which and from which all writes and reads will be converted (?) from a assumed internal UTF8 encoding. 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. var hostsfile; if (not hostsfile.osopen("/etc/hosts") ... // or if (not osopen("/etc/hosts" to hostsfile) ...
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 (optionally with a locale/codepage) or be just 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 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. var text, hostsfile = "/etc/hosts", offset = 0; if (not text.osbread(hostsfile, offset, 1024) ... // or if (not osbread(text from hostsfile, offset, 1024) ...
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 text = "\n#comment", xyzfile = "../xyz.conf"; var offset = osfile(xyzfile).f(1); // size of file -> append if (not text.osbwrite(xyzfile, offset)) abort(lasterror()); // or if (not osbwrite(text on xyzfile, offset) ...
cmd	osfilevar.osclose()	Removes an osfilevar handle from the internal memory cache of os file handles freeing 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	str.osread(osfilename, codepage = "")	Read a complete os file into a var Returns true if successful or false if not possible for any reason. e.g. File doesnt exist, permissions etc. var text; if (not text.osread("/etc/hosts")) ... // or if (not osread(text from "/etc/hosts")) ...
if	str.oswrite(osfilename, codepage = "")	Create a complete os file from a var. Any existing file is removed first. Returns true if successful or false if not possible for any reason. e.g. Path is not writeable, permissions etc. let text = "xyz = 123\n", osfilename="../xyz.conf"; if (not text.oswrite(osfilename)) abort(lasterror()); // or if (not oswrite(text on osfilename)) ...
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. if (not "../xyz.conf"_var.osfilevar.osremove()) abort(lasterror()); // or if (not osremove("../xyz.conf") ...
if	osfileordirname.osrename(new_dirpath_or_filepath)	Renames an os file or dir in the OS file system. Will not overwrite an existing 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. if (not "../xyz.conf"_var.osfilevar.osrename("../abc.conf")) abort(lasterror()); // or if (not osrename("../xyz.conf", "../abc.conf") ...
if	osfileordirname.oscopy(to_osfilename)	Copies a file or directory recursively within the file system. Uses std::filesystem::copy internally with recursive and overwrite options if (not "../xyz.conf"_var.osfilevar.oscopy("../abc.conf")) abort(lasterror()); // or if (not oscopy("../xyz.conf", "../abc.conf") ...
if	osfileordirname.osmove(to_osfilename)	"Moves" a file or dir within the os file system. Will not overwrite an existing 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. if (not "../xyz.conf"_var.osfilevar.osmove("../abc.conf")) abort(lasterror()); // or if (not osmove("../xyz.conf", "../abc.conf") ...

OS Directories

Usage	Function	Comment
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"); // "adduser.conf^ca-certificates.conf^ ..." // or just 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=	osfileordirpath.osinfo(mode = 0)	Return 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 a file mode 2 returns "" if not a dir See also osfile() and osdir() var info1 = "/etc/hosts"_var.osinfo(); // "221^20597^78309" // or just var info2 = osinfo("/etc/hosts");
var=	osfilename.osfile()	Return dir info for a file A short string containing size ^ FM ^ modified_time ^ FM ^ modified_time Alias for osinfo(1) var fileinfo1 = "/etc/hosts"_var.osfile(); // "221^20597^78309" // or just var fileinfo2 = osfile("/etc/hosts");
var=	dirpath.osdir()	Return dir info for a dir. A short string containing FM ^ modified_time ^ FM ^ modified_time Alias for osinfo(2) var dirinfo1 = "/etc/"_var.osdir(); // "^20848^44464" // or just var dirinfo2 = osfile("/etc/");
if	dirpath.osmkdir()	Makes a new directory and returns true if successful. Including parent dirs if necessary. if (not "abc/def"_var.osmkdir()) ... // or just if (not osmkdir("abc/def")) ...
if	dirpath.osrmdir(evenifnotempty = false)	Removes a os dir and returns true if successful. Optionally even if not empty. Including subdirs. if (not "abc/def"_var.osrmdir()) ... // or just if (not osrmdir("abc/def")) ...
var=	var.oscwd()	Returns the current working directory var cwd1 = var().oscwd(); // "/home/exodus" // or just var cwd2 = oscwd();
if	var.oscwd(newpath)	Changes the current working dir and returns true if successful. if (not "abc/def"_var.oscwd()) ... // or just if (not oscwd("abc/def")) ...

OS Shell/Environment

Usage	Function	Comment
if	command.osshell()	Execute a shell command Returns true if the process terminates with error status 0 and false otherwise. let cmd = "ls -l xyz"; if (not cmd.osshell()) ... // or if (not osshell(cmd)) ...
if	instr.osshellread(oscmd)	Same as osshell but captures stdout var intext; if (not intext.osshellread("ls -l xyz")) ... // or just capturing stdout but ignoring exit status intext = osshellread("ls -l xyz");
if	outstr.osshellwrite(oscmd)	Same as osshell but provides stdin to the process var outtext = ... if (not outtext.osshellwrite("grep xyz")) ... // or if (not osshellwrite(outtext, "grep xyz")) ...
var=	var.ostempdirpath()	Get the path of the tmp dir var v1 = var().ostempdirpath(); // "/tmp/" // or just var v1 = ostempdirpath(); ()
var=	var.ostempfilename()	Create and get a temporary file var tempfilename1 = var().ostempfilename(); // "/tmp/~exoEcLj3C" // or just var tempfilename2 = ostempfilename(); ()
if	envvalue.osgetenv(envcode)	Get the value of an environment variable var envvalue1; if (not envvalue1.osgetenv("HOME")) ... // "/home/exodus" // or just var envvalue2 = osgetenv("HOME");
cmd	envvalue.ossetenv(envcode)	Set the value of an environment variable code envvalue.ossetenv(envcode); // or just ossetenv(envcode, envvalue);
var=	var.ospid()	Get the os process id let pid = var().ospid(); // 663237 // or just let pid = ospid();
var=	var.ostid()	Get the os thread process id let tid = var().ostid(); // 663237 // or just let tid = ostid();
var=	var.version()	Get the libexodus build date and time var().version(); // "29 JAN 2025 14:56:52"

Output

Usage	Function	Comment
expr	var.output()	stdout no new line, buffered
expr	var.outputl()	stdout starts a new line, flushed
expr	var.outputt()	stdout adds a tab, buffered
expr	var.logput()	stdlog no new line, buffered
expr	var.logputl()	stdlog starts a new line, flushed
expr	var.errput()	stderr no new line, flushed
expr	var.errputl()	stderr starts a new line, flushed
expr	var.output(prefix)	stdout with a prefix, no new line, buffered
expr	var.outputl(prefix)	stdout with a prefix, starts a new line, flushed
expr	var.outputt(prefix)	stdout with a prefix, adds a tab, buffered
expr	var.logput(prefix)	stdlog with a prefix, no new line, buffered
expr	var.logputl(prefix)	stdlog with a prefix, starts a new line, flushed
expr	var.errput(prefix)	stderr with a prefix, no new line, flushed
expr	var.errputl(prefix)	stderr with a prefix, starts a new line, flushed
expr	var.put(std::ostream& ostream1)	Output to a given stream
cmd	var.osflush()	Flushes any buffered output to stdout/cout var().osflush(); // or just osflush(); ()

Standard Input

Usage	Function	Comment
expr	var.input()	Wait for stdin until cr or eof
expr	var.input(prompt)	Ditto after outputting prompt to stdout
expr	var.inputn(nchars)	Wait for nbytes from stdin
if	var.isterminal()	true if terminal is available
if	var.hasinput(milliseconds = 0)	true if stdin bytes available within milliseconds
if	var.eof()	true if stdin is at end of file
if	var.echo(on_off)	Reflect all stdin to stdout if terminal available
cmd	var.breakon()	Allow interrupt Ctrl+C
cmd	var.breakoff()	Prevent interrupt Ctr+C