Functions wikifmt

From NEOSYS Dev Wiki
Revision as of 04:20, 3 February 2025 by Steve (talk | contribs)
Jump to navigationJump to search

Complete List of Functions

Generated by cli/gendoc from var.h 03 FEB 2025 04:18:39

Math/Boolean
Usage Function Description
var= num.abs() Absolute value 
let v1 = var(-12.34).abs(); // 12.34
// or
let v2 = abs(-12.34);
var= num.pwr(exponent) Power 
let v1 = var(2).pwr(8); // 256
// or
let v2 = pwr(2, 8);
var= num.rnd() Pseudo random number generator 
let v1 = var(100).rnd(); // 0 to 99 pseudo random
// or
let v2 = rnd(100);
cmd num.initrnd() Initialise the seed for rnd() 
var(123).initrnd(); // Set seed to 123
// or
initrnd(123);
var= num.exp() Power of e 
let v1 = var(1).exp(); // 2.718281828459045
// or
let v2 = exp(1);
var= num.sqrt() Square root 
let v1 = var(100).sqrt(); // 10
// or
let v2 = sqrt(100);
var= num.sin() Sine of degrees 
let v1 = var(30).sin(); // 0.5
// or
let v2 = sin(30);
var= num.cos() Cosine of degrees 
let v1 = var(60).cos(); // 0.5
// or
let v2 = cos(60);
var= num.tan() Tangent of degrees 
let v1 = var(45).tan(); // 1
// or
let v2 = tan(45);
var= num.atan() Arctangent of degrees 
let v1 = var(1).atan(); // 45
// or
let v2 = atan(1);
var= num.loge() Natural logarithm 
let v1 = var(2.718281828459045).loge(); // 1
// or
let v2 = loge(2.718281828459045);
var= num.integer() Truncate decimal numbers towards zero 
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= num.floor() Truncate decimal numbers towards negative 
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= num.round(ndecimals = 0) Round decimal numbers to a desired number of decimal places

.5 always rounds away from zero. 

let v1 = var(0.455).round(2); // 0.46
// or
let v2 = round(1.455, 2);

var v3 = var(-0.455).round(2); // -0.46
// or
var v4 = round(-1.455, 2);
var= num.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)
mod(11, 5); // "1"
mod(-11, 5); // "4"
mod(11, -5); // "-4"
mod(-11, -5); // "-1" 

let v1 = var(11).mod(5); // 1
// or
let v2 = mod(11, 5);


Locale
Usage Function Description
expr var.getxlocale() Gets the current thread's default locale codepage code 
let v1 = var().getxlocale(); // e.g. "en_US.utf8"
// or
let v2 = getxlocale();
if strvar.setxlocale() Sets the current thread's default locale codepage code

obj is strvar 

if (not "de_DE.utf8"_var.setxlocale()) ... // true if successful
// or
if (setxlocale("de_DE.utf8")) ...


String Creation
Usage Function Description
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 

let v1 = var().chr(0x61); // "a"
// or
let v2 = chr(0x61);
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 

let v1 = var().textchr(171416); // "𩶘" or "\xF0A9B698"
// or
let v2 = textchr(171416);
var= var().str(num) Create a string by repeating a given character or string 
let v1 = "ab"_var.str(3); // "ababab"
// or
let v2 = str("ab", 3);
var= num.space() Create string of space characters.

obj is num 

let v1 = var(3).space(); // "␣␣␣"
// or
let v2 = space(3);
var= num.numberinwords(languagename_or_locale_id = "") Create a string describing a given number in words

obj is num 

let v1 = var(123.45).numberinwords("de_DE"); // "ein­hundert­drei­und­zwanzig Komma vier fünf"


String Scanning
Usage Function Description
var= strvar.seq() Returns: The character number of the first char. 
let v1 = "abc"_var.seq(); // 0x61 97
// or
let v2 = seq("abc");
var= strvar.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= strvar.len() Returns: The length of a string in number of chars 
let v1 = "abc"_var.len(); // 3
// or
let v2 = len("abc");
var= strvar.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= strvar.textlen() Returns: The number of Unicode code points 
let v1 = "Γιάννης"_var.textlen(); // 7
// or
let v2 = textlen("Γιάννης");
var= strvar.fcount(sepstr) Returns: The number of fields determined by presence of sepstr.

It is the same as var.count(sepstr) + 1 except that fcount returns 0 for an empty string. 

let v1 = "aa**cc"_var.fcount("*"); // 3
// or
let v2 = fcount("aa**cc", "*");
var= strvar.count(sepstr) Return the number of sepstr found 
let v1 = "aa**cc"_var.count("*"); // 2
// or
let v2 = count("aa**cc", "*");
if strvar.starts(prefix) Returns: True if starts with prefix 
let v1 = "abc"_var.starts("ab"); // true
// or
let v2 = starts("abc", "ab");
if strvar.ends(suffix) Returns: True if ends with suffix 
let v1 = "abc"_var.ends("bc"); // true
// or
let v2 = ends("abc", "bc");
if strvar.contains(substr) Returns: True if starts, ends or contains substr 
let v1 = "abcd"_var.contains("bc"); // true
// or
let v2 = contains("abcd", "bc");
var= strvar.index(substr, startchar1 = 1) Returns: Char no if found or 0 if not. startchar1 is byte no to start at. 
let v1 = "abcd"_var.index("bc"); // 2
// or
let v2 = index("abcd", "bc");
var= strvar.indexn(substr, occurrence) ditto. Occurrence 1 = find first occurrence 
let v1 = "abcabc"_var.index("bc", 2); // 5
// or
let v2 = index("abcabc", "bc", 2);
var= strvar.indexr(substr, startchar1 = -1) ditto. Reverse search.

startchar1 defaults to -1 meaning start searching from the last byte (towards the first byte). 

let v1 = "abcabc"_var.indexr("bc"); // 5
// or
let v2 = indexr("abcabc", "bc");
var= strvar.match(regex_str, regex_options = "") Returns: All results of regex matching

Multiple matches are in fields. Groups are in values 

let v1 = "abc1abc2"_var.match("BC(\\d)", "i"); // "bc1]1^bc2]2"
// 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= strvar.match(regex) Ditto
var= strvar.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"); // returns "bc1]1" and startchar1 is updated to 5 ready for the next search
// or
startchar1 = 1;
let v2 = search("abc1abc2", "BC(\\d)", startchar1, "i");
var= strvar.search(regex_str) Ditto starting from first char
var= strvar.search(regex, io startchar1) Ditto given a rex
var= strvar.search(regex) Ditto starting from first char.


String Conversion - Chainable. Non-Mutating
Usage Function Description
var= strvar.ucase() Upper case 
let v1 = "Γιάννης"_var.ucase(); // "ΓΙΆΝΝΗΣ"
// or
let v2 = ucase("Γιάννης");
var= strvar.lcase() Lower case 
let v1 = "ΓΙΆΝΝΗΣ"_var.lcase(); // "γιάννης"
// or
let v2 = lcase("ΓΙΆΝΝΗΣ");
var= strvar.tcase() Title case (first letters) 
let v1 = "γιάννης"_var.tcase(); // "Γιάννης"
// or
let v2 = tcase("γιάννης");
var= strvar.fcase() Fold case (lower case and remove accents for indexing)
var= strvar.normalize() Normalise Unicode to NFC to eliminate different code combinations of the same character
var= strvar.invert() Simple reversible disguising of text 
let v1 = "abc"_var.invert(); // "\x{C29EC29DC29C}"
// or
let v2 = invert("abc");
var= strvar.lower() Convert all FM to VM, VM to SM etc. 
let v1 = "a1^b2^c3"_var.lower(); // "a1]b2]c3"
// or
let v2 = lower("a1^b2^c3"_var);
var= strvar.raise() Convert all VM to FM, SM to VM etc. 
let v1 = "a1]b2]c3"_var.raise(); // "a1^b2^c3"
// or
let v2 = "a1]b2]c3"_var;
var= strvar.crop() Remove any redundant FM, VM etc. characters (Trailing FM; VM before FM etc.) 
let v1 = "a1^b2]]^c3^^"_var.crop(); // "a1^b2^c3"
// or
let v2 = crop("a1^b2]]^c3^^"_var);
var= strvar.quote() Wrap in double quotes 
let v1 = "abc"_var.quote(); // ""abc""
// or
let v2 = quote("abc");
var= strvar.squote() Wrap in single quotes 
let v1 = "abc"_var.squote(); // "'abc'"
// or
let v2 = squote("abc");
var= strvar.unquote() Remove one pair of double or single quotes 
let v1 = "'abc'"_var.unquote(); // "abc"
// or
let v2 = unquote("'abc'");
var= strvar.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= strvar.trimfirst(trimchars = " ") Ditto leading 
let v1 = "␣␣a1␣␣b2␣c3␣␣"_var.trimfirst(); // "a1␣␣b2␣c3␣␣"
// or
let v2 = trimfirst("␣␣a1␣␣b2␣c3␣␣");
var= strvar.trimlast(trimchars = " ") Ditto trailing 
let v1 = "␣␣a1␣␣b2␣c3␣␣"_var.trimlast(); // "␣␣a1␣␣b2␣c3"
// or
let v2 = trimlast("␣␣a1␣␣b2␣c3␣␣");
var= strvar.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= strvar.first() Extract first char or "" if empty 
let v1 = "abc"_var.first(); // "a"
// or
let v2 = first("abc");
var= strvar.last() Extract last char or "" if empty 
let v1 = "abc"_var.last(); // "c"
// or
let v2 = last("abc");
var= strvar.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= strvar.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= strvar.cut(length) Remove length leading chars 
let v1 = "abcd"_var.cut(2); // "cd"
// or
let v2 = cut("abcd", 2);
var= strvar.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= strvar.paste(pos1, insertstr) Insert text at char position without overwriting any following characters 
let v1 = "abcd"_var.paste(2, "XYZ"); // "aXYbcd"
// or
let v2 = paste("abcd", 2, "XYZ");
var= strvar.prefix(insertstr) Insert text at the beginning 
let v1 = "abc"_var.prefix("XY"); // "XYabc"
// or
let v2 = prefix("abc", "XY");
var= strvar.pop() Remove one trailing char 
let v1 = "abc"_var.pop(); // "ab"
// or
let v2 = pop("abc");
var= strvar.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= strvar.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= strvar.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= strvar.b(pos1, length) Same as substr version 1.
var= strvar.b(pos1) Same as substr version 2.
var= strvar.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= strvar.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= strvar.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= strvar.replace(regex, tostr) Replace substring(s) using a regular expression.

Use $0, $1, $2 in tostr to refer to groups defined in the regex. 

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= strvar.unique() Remove duplicate fields in an FM or VM etc. separated list 
let v1 = "a1^b2^a1^c2"_var.unique(); // "a1^b2^c2"
// or
let v2 = unique("a1^b2^a1^c2"_var);
var= strvar.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"
// 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"
// or
let v2 = sort("b1^a1^c20^c10^c2^c1^b2"_var);
var= strvar.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"
// or
let v2 = reverse("20^10^2^1^1.1"_var);
var= strvar.shuffle(sepchar = FM) Randomise the order of fields in an FM, VM separated list 
let v1 = "20^10^2^1^1.1"_var.shuffle(); // "2^1^20^1.1^10" (random order depending on initrand())

// or

let v2 = shuffle("20^10^2^1^1.1"_var);
var= strvar.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"
// or
let v2 = parse("abc,\"def,\"123\" fgh\",12.34", ',');


String Mutator Standalone Commands. All Similar To Non-Mutators
Usage Function Description
cmd strvar.ucaser() Upper case

All following string mutators follow the same pattern. See the non-mutating functions for details. 

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


Other String Access
Usage Function Description
var= strvar.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(); // 6715211243465481821
// or
let v2 = hash("abc");
var= strvar.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" and pos2 -> 6
// or
var pos1b = 4, pos2b; let v2 = substr("aa,bb,cc", pos1b, ",", pos2b);
var= strvar.b(pos1, delimiterchars, io pos2) Alias of substr version 3.
var= strvar.substr2(io pos1, out 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 pos1a = 4, delim1;
let v1 = "aa^bb^cc"_var.substr2(pos1a, delim1); // "bb", pos1a -> 7, delim -> 2 (FM)
// or
var pos1b = 4, delim2;
let v2 = substr2("aa^bb^cc"_var, pos1b, delim2);
var= strvar.b2(io pos1, out delimiterno) Alias of substr version 4
var= strvar.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= strvar.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);


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&&... 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= strvar.from_codepage(codepage) Converts from codepage encoded text to UTF-8 encoded text

e.g. Codepage "CP1124" (Ukrainian).
Use Linux command "iconv -l" for complete list of code pages and encodings. 

let v1 = "\xa4"_var.from_codepage("CP1124"); // "Є"
// or
let v2 = from_codepage("\xa4", "CP1124");
// U+0404 Cyrillic Capital Letter Ukrainian Ie Unicode Character
var= strvar.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");


Basic Dynamic Array Functions
Usage Function Description
var= strvar.f(fieldno, valueno = 0, subvalueno = 0) f() is a highly abbreviated alias for the PICK OS field/value/subvalue extract() function.

"f()" can be thought of as "field" although the function can extract values and subvalues as well.
The convenient PICK OS angle bracket syntax for field extraction (e.g. xxx<20>) is not available in C++.
The abbreviated exodus field extraction function (e.g. xxx.f(20)) is provided instead since field access is extremely heavily used in source code. 

let v1 = "f1^f2v1]f2v2]f2v3^f2"_var;
let v2 = v1.f(2, 2); // "f2v2"
var= strvar.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"
//
// The alias "f" is normally used instead for brevity
var v3 = v1.f(2, 2);
var= strvar.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= strvar.pickreplace(fieldno, valueno, replacement) Ditto for a specific multivalue
var= strvar.pickreplace(fieldno, replacement) Ditto for a specific field
var= strvar.insert(fieldno, valueno, subvalueno, insertion) Same as var.inserter() function but returns a new string instead of updating a variable in place.
var= strvar.insert(fieldno, valueno, insertion) Ditto for a specific multivalue
var= strvar.insert(fieldno, insertion) Ditto for a specific field
var= strvar.remove(fieldno, valueno = 0, subvalueno = 0) Same as var.remover() function but returns a new string instead of updating a variable in place.

"remove" was called "delete" in Pick OS.


Dynamic Array Filters
Usage Function Description
var= strvar.sum() Sum up multiple values into one higher level 
let v1 = "1]2]3^4]5]6"_var.sum(); // "6^15"
// or
let v2 = sum("1]2]3^4]5]6"_var);
var= strvar.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= strvar.sum(sepchar) Ditto allowing commas etc. 
let v1 = "10,20,33"_var.sum(","); // "60"
// or
let v2 = sum("10,20,33");
var= strvar.mv(opcode, var2) Binary ops (+, -, *, /) in parallel on multiple values 
let v1 = "10]20]30"_var.mv("+","2]3]4"); // "12]23]34"


Dynamic Array Mutators Standalone Commands
Usage Function Description
cmd strvar.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 strvar.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 strvar.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 strvar.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"
// or
inserter(v1, 2, "X");
cmd strvar.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"); // v1 -> "f1^v1]X]v2}s2}s3^f3"
// or
inserter(v1, 2, 2, "X");
cmd strvar.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"
// or
v1.inserter(2, 2, 2, "X");
cmd strvar.remover(fieldno, valueno = 0, subvalueno = 0) Remove a specific field (or value, or subvalue) from a dynamic array, moving all other fields (or values, or subvalues) down. 
var v1 = "f1^v1]v2}s2}s3^f3"_var;
v1.remover(2, 2); // v1 -> "f1^v1^f3"
// or
remover(v1, 2, 2);


Dynamic Array Search
Usage Function Description
if strvar.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
// or
if (locate("US", "UK]US]UA"_var)) ...
if strvar.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 strvar.locate(target, out setting, fieldno, valueno = 0) locate() the target in unordered fields if fieldno is 0, or values if a fieldno is specified, or subvalues if the valueno argument is provided.

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 strvar.locateby(ordercode, target, out valueno) locateby() without fieldno or valueno arguments searches ordered values separated by VM chars.

The order code can be AL, DL, AR, DR meaning Ascending Left, Descending Right, Ascending Right, Ascending Left.
Left is used to indicate alphabetic order where 10 < 2.
Right is used to indicate numeric order where 10 > 2.
Data must be in the correct order for searching to work properly.
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 strvar.locateby(ordercode, target, out setting, fieldno, valueno = 0) locateby() ordered as above but in fields if fieldno is 0, or values in a specific fieldno, or subvalues in a specific valueno. 
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 strvar.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 strvar.locateusing(usingchar, target, out setting, fieldno = 0, valueno = 0, subvalueno = 0) locate() the target in a specific field, value or subvalue using a specified delimiter and unordered data

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 strvar.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";
var db;
if (not db.connect(conninfo)) abort(lasterror());
db.disconnect();
// or
if (not connect("exodus")) ...
// or
if (not connect()) ...
disconnect();
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();
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 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;
if (not conn.attach(filenames)) ...
// or
if (not attach(filenames)) ...
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.rollbacktrans() Rollback a db transaction. 
if (not conn.rollbacktrans()) ...
// or
if (not rollbacktrans()) ...
if conn.committrans() Commit a db transaction. 
if (not conn.committrans()) ...
// or
if (not committrans()) ...
if conn.statustrans() Check if a db transaction is in progress. 
if (not conn.statustrans()) ...
// or
if (not statustrans()) ...
if conn.sqlexec(sqlcmd) Execute an sql command. 
var sqlcmd = "select 2 + 2;", response;
if (not conn.sqlexec("select 2 + 2;")) ... // True
// or
if (not sqlexec(sqlcmd)) ...
if conn.sqlexec(sqlcmd, io response) Execute an SQL command and capture the response. 
var sqlcmd = "select 2 + 2;", response;
if (not conn.sqlexec(sqlcmd, response)) ... // True and response = 4
// or
if (not sqlexec(sqlcmd, 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 Description
if conn.dbcreate(dbname) Create a named database on a particular connection. 
if (not conn.dbcreate("mydb")) ...
// or
if (not dbcreate("mydb")) ...
var= conn.dblist() Return a list of available databases on a particular connection. 
let v1 = conn.dblist();
// or
let v2 = dblist();
if conn.dbcopy(from_dbname, to_dbname) Create a named database from an existing database.

The source database cannot have any current connections. 

if (not conn.dbcopy("mydb", "mydb2")) ...
// or
if (not dbcopy("mydb", "mydb2")) ...
if conn.dbdelete(dbname) Delete (drop) a named database.

The target database cannot have any current connections. 

if (not conn.dbdelete("mydb")) ...
// or
if (not dbdelete("mydb")) ...
if conn.createfile(filename) Create a named db file. 
if (not conn.createfile("myfile")) ...
// or
if (not createfile("myfile")) ...
if conn.renamefile(filename, newfilename) Rename a db file. 
if (not conn.renamefile("myfile", "myfile2")) ...
// or
if (not renamefile("myfile", "myfile2")) ...
if conn.deletefile(filename) Delete (drop) a db file 
if (not conn.deletefile("myfile")) ...
// or
if (not deletefile("myfile")) ...
if conn.clearfile(filename) Delete all records in a db file 
if (not conn.clearfile("myfile")) ...
// or
if (not clearfile("myfile")) ...
var= conn.listfiles() Return a list of all files in a database 
if (not conn.listfiles()) ...
// or
if (not listfiles()) ...
var= conn_or_file.reccount(filename = "") Returns: The approx. number of records in a file 
let file = "definitions";
var nrecs1 = file.reccount();
// or
var nrecs2 = reccount("myfile");
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 database 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 database file var

Does nothing since database file vars consume no resources 

file.close();
// or
close(file);
if file.createindex(fieldname, dictfile = "") Creates a secondary index for a given 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;
if (not file.createindex(fieldname)) ...
// or
if (not createindex(filename, fieldname)) ...
if file.deleteindex(fieldname) Deletes a secondary index for a 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 = "some_name";
if (not file.deleteindex(fieldname)) ...
// or
if (not deleteindex(file, fieldname)) ...
var= conn.listindex(file_or_filename = "", fieldname = "") Lists secondary indexes in a database or file

Returns: False if the file or fieldname are given and do not exist
obj is file|conn 

if (not conn.listindex()) ...
// or
if (not listindex()) ...
var= file.lock(key) Places a metaphorical lock on a particular file and key in a database.

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 file nor the record key need to actually exist since a lock is just a hash of the filename 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 = "definitions", key = "1000";
if (not file.lock(key)) ...
// or
if (not lock(file, key)) ...
if file.unlock(key) Removes a 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 = "definitions", key = "1000";
if (not file.unlock(key)) ...
// or
if (not unlock(file, key)) ...
if file.unlockall() Removes all locks placed by the lock function in the specified connection.

Locks cannot be removed while in a transaction. 

if (not conn.unlockall()) ...
// or
if (not unlockall(conn)) ...
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, file = "definitions", key = "1000";
if (not rec.read(file, key)) ...
// or
if (not read(rec from file, key)) ...
cmd rec.write(file, key) Writes a record to a file.

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. 

var rec = "f1^f2^f3"_var, file = "definitions", key = "1000";
rec.write(file, key);

// or

write(rec on 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. 

var rec = "f1^f2^f3"_var, file = "definitions", key = "1000";
if (not rec.updaterecord(file, key)) ...
// or
if (not updaterecord(rec on 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. 

var rec = "f1^f2^f3"_var, file = "definitions", key = "1000";
if (not rec.insertrecord(file, key)) ...
// or
if (not insertrecord(rec on 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.
obj is file 

var file = "definitions", key = "1000";
if (not file.deleterecord(key)) ...
// or
if (not deleterecord(file, key)) ...
if strvar.readf(file, key, fieldno) Same as read() but only returns a specific field no from the record 
var field, file = "definitions", key = "1000", fieldno = 3;
if (not field.readf(file, key, fieldno)) ...
// or
if (not readf(field from file, key, fieldno)) ...
cmd strvar.writef(file, key, fieldno) Same as write() but only writes a specific field no to the record 
var field = "f3", file = "definitions", key = "1000", fieldno = 3;
field.writef(file, key, fieldno);
// or
writef(field on 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, file = "definitions", key = "1000";
if (not rec.readc(file, key)) ...
// or
if (not readc(rec from 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. 

var rec = "f1^f2^f3"_var, file = "definitions", key = "1000";
rec.writec(file, key);
// or
writec(rec on 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 

var file = "definitions", key = "1000";
if (not file.deletec(key)) ...
// or
if (not 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= strvar.xlate(filename, fieldno, mode) The xlate ("translate") function is similar to readf() but, when called as an exodus program member function, it can be used efficiently with exodus file dictionaries using column names and functions and multivalued data.

Arguments:
str: Used as the primary key to lookup a field in a given file and field no or field name.
filename: The 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.
var partno = "A1000-1";
var partname1 = partno.xlate("PARTS", 3, "X");
// or
var partname2 = xlate(partno, "PARTS", "PART_NAME", "X");


Database Sort/Select
Usage Function Description
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 Description
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
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
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
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
var now2 = timestamp();
var= var().timestamp(ostime) Construct a timestamp from a date and time 
var idate = iconv("2025-01-01", "D"), itime = iconv("23:59:59", "MT");
var ts1 = idate.timestamp(itime); // 20821.99998842593
// or
var ts2 = timestamp(idate, itime);
cmd var().ossleep(milliseconds) Sleep/pause/wait for a number of milliseconds 
var().ossleep(3000); // sleep for 3 seconds
// or
ossleep(3000);
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.
obj is file_dir_list 

let v1 = ".^/etc/hosts"_var.oswait(3000); // e.g. "IN_CLOSE_WRITE^/etc^hosts^f"_var
// or
let v2 = oswait(".^/etc/hosts"_var, 3000);

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 file name including path, initialises a 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. 

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

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. 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 strvar.osread(osfilename, codepage = "") Read a complete os file into a var.

If codepage is specified then input is converted from that codepage to utf-8 otherwise no conversion is done.
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 strvar.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.
If codepage is specified then output is converted from utf-8 to that codepage. Otherwise no conversion is done. 

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.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.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.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.osmove("../abc.conf")) abort(lasterror());
// or
if (not osmove("../xyz.conf", "../abc.conf")) ...


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"); // "adduser.conf^ca-certificates.conf^ ..."
// 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= 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
var info2 = osinfo("/etc/hosts");

obj is osfileordirpath

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
var fileinfo2 = osfile("/etc/hosts");

obj is osfilename

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
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
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
if (not osrmdir("abc/def")) ...
var= var().oscwd() Returns: The current working directory 
var cwd1 = var().oscwd(); // "/home/exodus"
// or
var cwd2 = oscwd();
if var().oscwd(newpath) Changes the current working dir and returns true if successful. 
if (not "abc/def"_var.oscwd()) ...
// or
if (not oscwd("abc/def")) ...


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. 

let cmd = "ls -l xyz";
if (not cmd.osshell()) ...
// or
if (not osshell(cmd)) ...

obj is command

if instr.osshellread(oscmd) Same as osshell but captures stdout 
var intext;
if (not intext.osshellread("ls -l xyz")) ...

// or capturing stdout but ignoring exit status
intext = osshellread("ls -l xyz");

obj is instr

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")) ...

obj is outstr

var= var.ostempdirpath() Get the path of the tmp dir 
let v1 = var().ostempdirpath(); // "/tmp/"
// or
let v2 = ostempdirpath();

obj is var()

var= var.ostempfilename() Create and get a temporary file 
var tempfilename1 = var().ostempfilename(); // "/tmp/~exoEcLj3C"
// or
var tempfilename2 = ostempfilename();

obj is var()

if envvalue.osgetenv(envcode) Get the value of an environment variable 
var envvalue1;
if (not envvalue1.osgetenv("HOME")) ... // "/home/exodus"
// or
var envvalue2 = osgetenv("HOME");
cmd envvalue.ossetenv(envcode) Set the value of an environment variable code 
var envvalue, envcode = "HOME";
envvalue.ossetenv(envcode);
// or
ossetenv(envcode, envvalue);

obj is envvalue

var= var().ospid() Get the os process id 
let pid1 = var().ospid(); // 663237
// or
let pid2 = ospid();
var= var().ostid() Get the os thread process id 
let tid1 = var().ostid(); // 663237
// or
let tid2 = ostid();
var= var().version() Get the libexodus build date and time 
let v1 = var().version(); // "29 JAN 2025 14:56:52"


Output
Usage Function Description
expr var.output() To stdout. No new line. Buffered.
expr var.outputl() To stdout. Starts a new line. Flushed.
expr var.outputt() To stdout. Adds a tab. Buffered.
expr var.logput() To stdlog. No new line. Buffered.
expr var.logputl() To stdlog. Starts a new line. Flushed.
expr var.errput() To stderr. No new line. Flushed.
expr var.errputl() To stderr. Starts a new line. Flushed.
expr var.output(prefix) To stdout. With a prefix. No new line. Buffered.
expr var.outputl(prefix) To stdout. With a prefix. Starts a new line. Flushed.
expr var.outputt(prefix) To stdout. With a prefix. Adds a tab. Buffered.
expr var.logput(prefix) To stdlog. With a prefix. No new line. Buffered.
expr var.logputl(prefix) To stdlog. With a prefix. Starts a new line. Flushed.
expr var.errput(prefix) To stderr. With a prefix. No new line. Flushed.
expr var.errputl(prefix) To 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
osflush();

obj is var()


Standard Input
Usage Function Description
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
Retrieved from "https://devwiki.neosys.com/index.php?title=Functions_wikifmt&oldid=1583"