Functions: Difference between revisions

From NEOSYS Dev Wiki
Jump to navigationJump to search
No edit summary
No edit summary
 
(4 intermediate revisions by the same user not shown)
Line 1: Line 1:
<!DOCTYPE html>
<html>
<html>
<head>
<head>
Line 9: Line 7:
<style>
<style>


body {
:root {
margin: 10px;
    --bs-font-monospace: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace;
}
}
body {
margin: 10px;
    font-size: 1rem;
    font-weight: 400;
font-family: system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue","Noto Sans","Liberation Sans",Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji";
line-height: 1.5;
}
pre {
margin: 0px;
white-space: pre;
overflow-x: auto;
max-width: none;
width: auto;
}
table, th, td {
border: 1px solid #a2a9b1;
}
th {
background-color: #eaecf0;
font-weight: bold;
text-align: left;
padding: 8px;
}


pre {
td {
margin: 0px;
padding: 0 0.5em 0 0.7em;
white-space: pre-wrap;
vertical-align: top;
word-wrap: break-word;
}
white-space: -moz-pre-wrap;
 
white-space: -pre-wrap;
.toc, .toccolours {
white-space: -o-pre-wrap;
border: 1px solid #a2a9b1;
overflow-wrap: break-word;
background-color: #f8f9fa;
overflow-x: auto;
padding: 5px;
}
font-size: 95%;
}
 
.toc {
display: table;
padding: 7px;
}
 
.wikitable {
background-color: #f8f9fa;
color: #202122;
margin: 1em 0;
border: 1px solid #a2a9b1;
border-collapse: collapse;
}


table, th, td {
p {
border: 1px solid #a2a9b1;
max-width: 50ch;
}
margin: 0.4em 0 0.5em 0;
}


th {
/* paras starting em/em get indented*/
background-color: #eaecf0;
p:has(> em:first-child) {
font-weight: bold;
padding-left: 68px;
text-align: left;
border-top: 1px dashed grey;
padding: 8px;
/*border-bottom: 1px dashed grey;*/
}
}


td {
/* first line of description is the title.*/
padding: 0.2em 0.4em;
/* Exclude p with anything in it like em/em */
vertical-align: top;
td:nth-child(3) p:first-child:not(:has(*)) {
}
font-weight: 500;
}


p {
/* We only use em/em for leading words (arguments) */
  margin: 0.4em 0 0.5em 0;
em {
}
    display: inline-block;
    min-width: 64px; /* Fill the undone indent approximately */
    margin-left: -68px; /* Undo indent for the box */
}


.toc, .toccolours {
/* Style em like code*/
border: 1px solid #a2a9b1;
code, em {
background-color: #f8f9fa;
color:inherit; /* ignore styling from mediawiki/bootstrap etc.*/
padding: 5px;
font-family: var(--bs-font-monospace);
font-size: 95%;
font-style: normal;
}
/*font-size: smaller;*/
.toc {
font-weight: normal;
display: table;
}
padding: 7px;
}


.wikitable {
background-color: #f8f9fa;
color: #202122;
margin: 1em 0;
border: 1px solid #a2a9b1;
border-collapse: collapse;
}
img {
img {
border: 0;
border: 0;
Line 74: Line 108:
}
}


h1,h2,h3,h4,h5,h6 {
h1, h2, h3, h4, h5, h6 {
color: #000;
color: #000;
margin: 0;
margin: 0;
Line 82: Line 116:
}
}


h1,h2 {
h1, h2 {
margin-bottom: 0.6em;
margin-bottom: 0.6em;
border-bottom: 1px solid #a2a9b1
border-bottom: 1px solid #a2a9b1
}
}


h3,h4,h5 {
h3, h4, h5 {
margin-bottom: 0.3em
margin-bottom: 0.3em
}
}
Line 131: Line 165:


ol {
ol {
margin: 0.3em 0 0 3.2em;
padding: 0;
list-style-image: none
list-style-image: none
}
}


li {
li {
margin-bottom: 0.1em
}
dt {
font-weight: bold;
margin-bottom: 0.1em
margin-bottom: 0.1em
}
}


dl {
dl {
margin-top: 0.2em;
display: grid;
margin-bottom: 0.5em
grid-template-columns: minmax(auto, max-content) 1fr; /* Left: expands to fit content, Right: remaining space */
/*gap: 10px;*/ /* Space between rows and columns */
overflow: hidden; /* Clears floats for the dl container */
/*align-items: baseline;*/ /* Align grid items by baseline */
    align-items: stretch; /* Change from baseline to stretch to ensure equal heights */
        max-width: 50ch;
}
 
dt, dd {
margin: 0;
box-sizing: border-box;
border-bottom: 1px dashed grey;
line-height: 1.5; /* Consistent line height */
vertical-align: baseline; /* Ensure text aligns on baseline */
}
 
dt {
grid-column: 1; /* Left column */
padding-right: 5px;
// text-align: center;
font-weight: bold;
font-family: var(--bs-font-monospace);
white-space: pre-wrap;
/* font-size: 95%;*
/* padding-top: 0.15em;*/ /* Nudge dt text baseline down to match dd */
}
}


dd {
dd {
margin-left: 1.6em;
grid-column: 2; /* Right column */
margin-bottom: 0.1em
margin-left:1em;
}
}


.gendoc_function {
 
color: #800;
.gendoc_function {
font-weight: 700;
color: #800;
}
font-weight: 700;
}


</style>
</style>
Line 171: Line 223:




 
/* 0. .hll/.err
 
1. Comments
2. Keywords
3. Operator
4. Literals
5. Name
6. Generic
7. Text.
*/


/* Highlight and Error */
/* Highlight and Error */
Line 223: Line 282:


/* used in exodus_cpp.py EXTRA_TYPES 'dim', 'var', '_var', 'rex', '_rex', 'let', 'in', 'out', 'io', 'qqqqqqq'
/* used in exodus_cpp.py EXTRA_TYPES 'dim', 'var', '_var', 'rex', '_rex', 'let', 'in', 'out', 'io', 'qqqqqqq'
        'programexit', 'programinit',
    'libraryinit', 'libraryexit',
        'libraryinit', 'libraryexit',
    'commoninit', 'commonexit',
        'commoninit', 'commonexit',
    'dictinit', 'dictexit'*/
        'dictinit', 'dictexit'*/
.kt  { color: var(--keyword-type-color); font-weight: var(--keyword-font-weight); font-style: var(--keyword-font-style); } /* Keyword.Type */
.kt  { color: var(--keyword-type-color); font-weight: var(--keyword-font-weight); font-style: var(--keyword-font-style); } /* Keyword.Type */


Line 402: Line 460:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td></td><td>var v1;</td><td><p>Create an unassigned var.
<tr><td><p><code></code></p></td><td><p><code>var v1;</code></p></td><td><p>Create an unassigned var.</p>
</p>
<p>Unassigned variables can be assigned conditionally in if/else statements or used as outbound arguments of function calls.</p>
<p>Unassigned variables can be assigned conditionally in if/else statements or used as outbound arguments of function calls.
<p>A runtime error is thrown if a var is used before being assigned so silent "use before assign" bugs cannot occur.</p>
</p>
<p>
A runtime error is thrown if a var is used before being assigned so silent "use before assign" bugs cannot occur.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">client</span><span class="p">;</span><span class="w"> </span><span class="c1">// Unassigned var</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">client</span><span class="p">;</span><span class="w"> </span><span class="c1">// Unassigned var</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">read</span><span class="p">(</span><span class="n">client</span><span class="w"> </span><span class="ow">from</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;SB001&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">read</span><span class="p">(</span><span class="n">client</span><span class="w"> </span><span class="ow">from</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;SB001&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
<p>
<div class="highlight light"><pre><span class="c1">//            Exodus keywords:    C++ declarations:</span>
<div class="highlight light"><pre><span class="c1">//            Exodus keywords:    C++ declarations:</span>
<span class="c1">//            Non-Const  Const    Non-Const  Const</span>
<span class="c1">//            Non-Const  Const    Non-Const  Const</span>
Line 416: Line 475:
<span class="c1">// Reference:  out        in      var&amp;        const var&amp;</span>
<span class="c1">// Reference:  out        in      var&amp;        const var&amp;</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>var v1 = expression;</td><td><p>Assign a var using a literal or an expression.
<tr><td><p><code></code></p></td><td><p><code>var v1 = expression;</code></p></td><td><p>Assign a var using a literal or an expression.</p>
</p>
<p>Use "let" instead of "var" wherever possible as a shorthand way of writing "const var".</p>
Use "let" instead of "var" wherever possible as a shorthand way of writing "const var".
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">42</span><span class="p">;</span><span class="w">                </span><span class="c1">// Integer</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">42</span><span class="p">;</span><span class="w">                </span><span class="c1">// Integer</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">42.3</span><span class="p">;</span><span class="w">              </span><span class="c1">// Double</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">42.3</span><span class="p">;</span><span class="w">              </span><span class="c1">// Double</span>
Line 438: Line 498:
<span class="kt">var</span><span class="w"> </span><span class="n">x</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">0.1</span><span class="p">,</span><span class="w"> </span><span class="n">y</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;0.2&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">z</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">x</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">y</span><span class="p">;</span><span class="w"> </span><span class="c1">// z -&gt; 0.3</span>
<span class="kt">var</span><span class="w"> </span><span class="n">x</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">0.1</span><span class="p">,</span><span class="w"> </span><span class="n">y</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;0.2&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">z</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">x</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">y</span><span class="p">;</span><span class="w"> </span><span class="c1">// z -&gt; 0.3</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>v1.assigned()</td><td>
<tr><td><p><code>if</code></p></td><td><p><code>v1.assigned()</code></p></td><td><p>Check if a var has been assigned a value.</p>
<em>Returns:</em> True if the var is assigned, otherwise false</td></tr>
<p><em>return:</em> True if the var is assigned, otherwise false</p>
<tr><td>if</td><td>v1.unassigned()</td><td>
</td></tr>
<em>Returns:</em> True if the var is unassigned, otherwise false</td></tr>
<tr><td><p><code>if</code></p></td><td><p><code>v1.unassigned()</code></p></td><td><p>Check if a var has not been assigned a value;</p>
<tr><td>var=</td><td>v2.or_default(defaultvalue)</td><td>
<p><em>return:</em> True if the var is unassigned, otherwise false</p>
<p><em>Returns:</em> A copy of the var if it is assigned or the default value if it is not.
</td></tr>
</p>
<tr><td><p><code>var=</code></p></td><td><p><code>v2.or_default(defaultvalue)</code></p></td><td><p>Copy a var or, if it is unassigned, copy a default value.</p>
<p>Can be used to handle optional arguments in functions.
<p><em>return:</em> A copy of the var if it is assigned or the default value if it is not.</p>
</p>
<p>Can be used to handle optional arguments in functions.</p>
<p><em>defaultvalue:</em> Cannot be unassigned.
<p><em>defaultvalue:</em> Cannot be unassigned.</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="p">;</span><span class="w"> </span><span class="c1">// Unassigned</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="p">;</span><span class="w"> </span><span class="c1">// Unassigned</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">or_default</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// v2 -&gt; &quot;abc&quot;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">or_default</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// v2 -&gt; &quot;abc&quot;</span>
Line 454: Line 516:
<span class="kt">var</span><span class="w"> </span><span class="n">v3</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">or_default</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="p">);</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v3</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">or_default</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
<p><em>Mutator:</em> defaulter()
</p>
</p>
<p></p>
<p><em>Mutator:</em> defaulter()</p>
</td></tr>
</td></tr>
<tr><td></td><td>v1.defaulter(defaultvalue)</td><td><p>If the var is unassigned then assign the default value to it, otherwise do nothing.
<tr><td><p><code></code></p></td><td><p><code>v1.defaulter(defaultvalue)</code></p></td><td><p>If a var is unassigned, assign a default value.</p>
</p>
<p>If the var is unassigned then assign the default value to it, otherwise do nothing.</p>
<em>defaultvalue:</em> Cannot be unassigned.
<p><em>defaultvalue:</em> Cannot be unassigned.</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="p">;</span><span class="w"> </span><span class="c1">// Unassigned</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="p">;</span><span class="w"> </span><span class="c1">// Unassigned</span>
<span class="n">v1</span><span class="p">.</span><span class="nf">defaulter</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// v1 -&gt; &quot;abc&quot;</span>
<span class="n">v1</span><span class="p">.</span><span class="nf">defaulter</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// v1 -&gt; &quot;abc&quot;</span>
Line 467: Line 529:
<span class="nf">defaulter</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="p">);</span>
<span class="nf">defaulter</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>v1.swap(io v2)</td><td><p>Swap the contents of one var with another.
<tr><td><p><code></code></p></td><td><p><code>v1.swap(io v2)</code></p></td><td><p>Swap the contents of one var with another.</p>
</p>
<p>Useful for stashing large strings quickly. They are moved using pointers without making copies or allocating memory.</p>
<p>Useful for stashing large strings quickly. They are moved using pointers without making copies or allocating memory.
<p>Eiher or both variables may be unassigned.</p>
</p>
<p>
Eiher or both variables may be unassigned.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">space</span><span class="p">(</span><span class="mi">65&#39;536</span><span class="p">);</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">space</span><span class="p">(</span><span class="mi">65&#39;536</span><span class="p">);</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;&quot;</span><span class="p">;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;&quot;</span><span class="p">;</span>
Line 479: Line 541:
<span class="nf">swap</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="n">v2</span><span class="p">);</span>
<span class="nf">swap</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="n">v2</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>v2.move()</td><td><p>Force the contents of a var to be moved instead of copied. The moved var becomes an empty string.
<tr><td><p><code>var=</code></p></td><td><p><code>v2.move()</code></p></td><td><p>Move a var into another.</p>
</p>
<p>Shallow copy of var data and take ownership of the moved var's string if any. The moved var becomes an empty string.</p>
<p>This allows large strings to be handled efficiently. They are moved using pointers without making copies or allocating memory.
<p>This allows large strings to be handled efficiently. They are moved using pointers without making copies or allocating memory.</p>
</p>
<p>The moved var must be assigned otherwise a VarUnassigned error is thrown.</p>
The moved var must be assigned otherwise a VarUnassigned error is thrown.
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">space</span><span class="p">(</span><span class="mi">65&#39;536</span><span class="p">);</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">space</span><span class="p">(</span><span class="mi">65&#39;536</span><span class="p">);</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">move</span><span class="p">();</span><span class="w"> </span><span class="c1">// v2.len() -&gt; 65&#39;536 // v1 -&gt; &quot;&quot;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">move</span><span class="p">();</span><span class="w"> </span><span class="c1">// v2.len() -&gt; 65&#39;536 // v1 -&gt; &quot;&quot;</span>
Line 490: Line 553:
<span class="kt">var</span><span class="w"> </span><span class="n">v3</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">move</span><span class="p">(</span><span class="n">v2</span><span class="p">);</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v3</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">move</span><span class="p">(</span><span class="n">v2</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>v2.clone()</td><td><p>Returns a copy of the var.
<tr><td><p><code>var=</code></p></td><td><p><code>v2.clone()</code></p></td><td><p>Return a copy of the var.</p>
</p>
<p>The cloned var may be unassigned, in which case the copy will be unassigned too.
The cloned var may be unassigned, in which case the copy will be unassigned too.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="p">;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">clone</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;abc&quot;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">clone</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;abc&quot;</span>
Line 499: Line 562:
<span class="kt">var</span><span class="w"> </span><span class="n">v3</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">clone</span><span class="p">(</span><span class="n">v2</span><span class="p">);</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v3</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">clone</span><span class="p">(</span><span class="n">v2</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>v1.dump()</td><td><p>Return a string describing internal data of a var.
<tr><td><p><code>var=</code></p></td><td><p><code>v1.dump()</code></p></td><td><p>Return a string describing internal data of a var.</p>
</p>
<p>If the str is located on the heap then its address is given.</p>
<p>If the str is located on the heap then its address is given.
<p><em>typ:</em> </p>
</p>
<dl>
<p><em>typ:</em>
<dt>0x01</dt><dd>str is available.</dd>
</p>
<dt>0x02</dt><dd>int is available.</dd>
<p>0x01 str is available.
<dt>0x04</dt><dd>dbl is available.</dd>
</p>
<dt>0x08</dt><dd>nan: str is not a number.</dd>
<p>0x02 int is available.
<dt>0x16</dt><dd>osfile (nan is true, str, int and dbl have special meaning).</dd>
</p>
</dl>
<p>0x04 dbl is available.
<p>
</p>
<p>0x08 nan: str is not a number.
</p>
0x16 osfile: str, int and dbl have special meaning.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">str</span><span class="p">(</span><span class="s">&quot;x&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">32</span><span class="p">);</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">str</span><span class="p">(</span><span class="s">&quot;x&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">32</span><span class="p">);</span>
<span class="n">v1</span><span class="p">.</span><span class="nf">dump</span><span class="p">().</span><span class="nf">outputl</span><span class="p">();</span><span class="w"> </span><span class="c1">/// e.g. var:0x7ffea7462cd0 typ:1 str:0x584d9e9f6e70 &quot;xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&quot;</span>
<span class="n">v1</span><span class="p">.</span><span class="nf">dump</span><span class="p">().</span><span class="nf">outputl</span><span class="p">();</span><span class="w"> </span><span class="c1">/// e.g. var:0x7ffea7462cd0 typ:1 str:0x584d9e9f6e70 &quot;xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&quot;</span>
Line 520: Line 580:
<span class="nf">outputl</span><span class="p">(</span><span class="nf">dump</span><span class="p">(</span><span class="n">v1</span><span class="p">));</span>
<span class="nf">outputl</span><span class="p">(</span><span class="nf">dump</span><span class="p">(</span><span class="n">v1</span><span class="p">));</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
</table>
</table>
Line 526: Line 587:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>if</td><td>v1.isnum()</td><td><p>Checks if a var is numeric.
<tr><td><p><code>if</code></p></td><td><p><code>v1.isnum()</code></p></td><td><p>Check if a var is numeric.</p>
</p>
<p><em>return:</em> True if a var holds a double, an integer, or a string that is defined as numeric.</p>
<p><em>Returns:</em> True if a var holds a double, an integer, or a string that is defined as numeric.
<p>A string is defined as numeric only if it consists of one or more digits 0-9, with an optional decimal point "." placed anywhere, with an optional + or - sign prefix, or it is the empty string "", which is defined to be zero.</p>
</p>
<p>
A string is defined as numeric only if it consists of one or more digits 0-9, with an optional decimal point "." placed anywhere, with an optional + or - sign prefix, or it is the empty string "", which is defined to be zero.
<div class="highlight light"><pre><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="s">&quot;+123.45&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">isnum</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<div class="highlight light"><pre><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="s">&quot;+123.45&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">isnum</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="w">      </span><span class="s">&quot;&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">isnum</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="w">      </span><span class="s">&quot;&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">isnum</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
Line 537: Line 597:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">isnum</span><span class="p">(</span><span class="s">&quot;123.&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">isnum</span><span class="p">(</span><span class="s">&quot;123.&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>v1.num()</td><td><p>Returns a copy of the var if it is numeric or 0 otherwise.
<tr><td><p><code>var=</code></p></td><td><p><code>v1.num()</code></p></td><td><p>Return a copy of the var if it is numeric or 0 otherwise.</p>
</p>
<p>Allow working numerically with data that may be non-numeric.</p>
<p><em>Returns:</em> A guaranteed numeric var
<p><em>return:</em> A guaranteed numeric var</p>
</p>
<p>
Allows working numerically with data that may be non-numeric.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;123.45&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">num</span><span class="p">();</span><span class="w">    </span><span class="c1">// 123.45</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;123.45&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">num</span><span class="p">();</span><span class="w">    </span><span class="c1">// 123.45</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">num</span><span class="p">()</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mi">100</span><span class="p">;</span><span class="w"> </span><span class="c1">// 100</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">num</span><span class="p">()</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mi">100</span><span class="p">;</span><span class="w"> </span><span class="c1">// 100</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>v2 + v3</td><td><p>Addition
<tr><td><p><code>var=</code></p></td><td><p><code>v2 + v3</code></p></td><td><p>Addition</p>
</p>
<p>Any attempt to perform numeric operations on non-numeric strings will throw a runtime error VarNonNumeric.</p>
<p>Attempts to perform numeric operations on non-numeric strings will throw a runtime error VarNonNumeric.
<p>Floating point numbers are implicitly converted to strings with no more than 12 significant digits of precision. This practically eliminates all floatng point rounding errors.</p>
</p>
<p>Internally, 0.1 + 0.2 looks like this using doubles.</p>
<p>Floating point numbers are implicitly converted to strings with no more than 12 significant digits of precision. This practically eliminates all floatng point rounding errors.
<p>0.10000000000000003 + 0.20000000000000004 -&gt; 0.30000000000000004</p>
</p>
<p>
<p>Internally, 0.1 + 0.2 looks like this using doubles.
</p>
0.10000000000000003 + 0.20000000000000004 -> 0.30000000000000004
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">0.1</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">0.1</span><span class="p">;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mf">0.2</span><span class="p">;</span><span class="w"> </span><span class="c1">// 0.3</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mf">0.2</span><span class="p">;</span><span class="w"> </span><span class="c1">// 0.3</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>v2 - v3</td><td>Subtraction</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>v2 - v3</code></p></td><td><p>Subtraction</p>
<tr><td>var=</td><td>v2 * v3</td><td>Multiplication</td></tr>
</td></tr>
<tr><td>var=</td><td>v2 / v3</td><td>Division</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>v2 * v3</code></p></td><td><p>Multiplication</p>
<tr><td>var=</td><td>v2 % v3</td><td>Modulus</td></tr>
</td></tr>
<tr><td></td><td>v1 += v2</td><td>Self addition
<tr><td><p><code>var=</code></p></td><td><p><code>v2 / v3</code></p></td><td><p>Division</p>
</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>v2 % v3</code></p></td><td><p>Modulus</p>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>v1 += v2</code></p></td><td><p>Self addition</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">0.1</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">0.1</span><span class="p">;</span>
<span class="n">v1</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="mf">0.2</span><span class="p">;</span><span class="w"> </span><span class="c1">// 0.3</span>
<span class="n">v1</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="mf">0.2</span><span class="p">;</span><span class="w"> </span><span class="c1">// 0.3</span>
</pre></div>
</pre></div>
</p>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>v1 -= v2</code></p></td><td><p>Self subtraction</p>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>v1 *= v2</code></p></td><td><p>Self multiplication</p>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>v1 /= v2</code></p></td><td><p>Self division</p>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>v1 %= v2</code></p></td><td><p>Self modulus</p>
</td></tr>
</td></tr>
<tr><td></td><td>v1 -= v2</td><td>Self subtraction</td></tr>
<tr><td><p><code></code></p></td><td><p><code>v1 ++</code></p></td><td><p>Post increment</p>
<tr><td></td><td>v1 *= v2</td><td>Self multiplication</td></tr>
<p>
<tr><td></td><td>v1 /= v2</td><td>Self division</td></tr>
<tr><td></td><td>v1 %= v2</td><td>Self modulus</td></tr>
<tr><td></td><td>v1 ++</td><td>Post increment
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">3</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">3</span><span class="p">;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">++</span><span class="p">;</span><span class="w"> </span><span class="c1">// v2 -&gt; 3 // v1 -&gt; 4</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">++</span><span class="p">;</span><span class="w"> </span><span class="c1">// v2 -&gt; 3 // v1 -&gt; 4</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>v1 --</td><td>Post decrement
<tr><td><p><code></code></p></td><td><p><code>v1 --</code></p></td><td><p>Post decrement</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">3</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">3</span><span class="p">;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">--</span><span class="p">;</span><span class="w"> </span><span class="c1">// v2 -&gt; 3 // v1 -&gt; 2</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">--</span><span class="p">;</span><span class="w"> </span><span class="c1">// v2 -&gt; 3 // v1 -&gt; 2</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>++ v1</td><td>Pre increment
<tr><td><p><code></code></p></td><td><p><code>++ v1</code></p></td><td><p>Pre increment</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">3</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">3</span><span class="p">;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">++</span><span class="w"> </span><span class="n">v1</span><span class="p">;</span><span class="w"> </span><span class="c1">// v2 -&gt; 4 // v1 -&gt; 4</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">++</span><span class="w"> </span><span class="n">v1</span><span class="p">;</span><span class="w"> </span><span class="c1">// v2 -&gt; 4 // v1 -&gt; 4</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>-- v1</td><td>Pre decrement
<tr><td><p><code></code></p></td><td><p><code>-- v1</code></p></td><td><p>Pre decrement</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">3</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">3</span><span class="p">;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">--</span><span class="w"> </span><span class="n">v1</span><span class="p">;</span><span class="w"> </span><span class="c1">// v2 -&gt; 2 // v1 -&gt; 2</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">--</span><span class="w"> </span><span class="n">v1</span><span class="p">;</span><span class="w"> </span><span class="c1">// v2 -&gt; 2 // v1 -&gt; 2</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
</table>
</table>
Line 598: Line 675:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>var=</td><td>""_var</td><td><p>The literal suffix "_var" allows dynamic arrays to be seamlessly embedded in code using a predefined set of visible equivalents of unprintable field mark characters as follows:
<tr><td><p><code>var=</code></p></td><td><p><code>""_var</code></p></td><td><p>Literal suffix "_var".</p>
<p>Allow dynamic arrays to be seamlessly embedded in code using a predefined set of visible equivalents of unprintable field mark characters as follows:</p>
<p>Visible equivalents:</p>
<dl>
<dt>`</dt><dd>RM  Record mark</dd>
<dt>^</dt><dd>FM  Field mark</dd>
<dt>]</dt><dd>VM  Value mark</dd>
<dt>}</dt><dd>SM  Subvalue mark</dd>
<dt>|</dt><dd>TM  Text mark</dd>
<dt>~</dt><dd>ST  Subtext mark</dd>
</dl>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;f1^f2^v1]v2^f4&quot;</span><span class="kt">_var</span><span class="p">;</span><span class="w"> </span><span class="c1">// &quot;f1&quot; _FM &quot;f2&quot; _FM &quot;v1&quot; _VM &quot;v2&quot; _FM &quot;f4&quot;</span>
</pre></div>
</p>
</p>
<p>  Visible  Unprintable
</td></tr>
</p>
<tr><td><p><code></code></p></td><td><p><code>var v1 = {"a", "b", "c" ...}; // Initializer list</code></p></td><td><p>Code a dynamic array var as as list.</p>
<p>*    `    RM  Record mark
<p>C++ constrains list elements to be all the same type: var, string, double, int, etc. but they all end up as fields of a dynamic array string.</p>
</p>
<p>
<p>*    ^    FM  Field mark
</p>
<p>*    ]    VM  Value mark
</p>
<p>*    }    SM  Subvalue mark
</p>
<p>*    |    TM  Text mark
</p>
*    ~    ST  Subtext mark
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;f1^f2^v1]v2^f4&quot;</span><span class="kt">_var</span><span class="p">;</span><span class="w"> </span><span class="c1">// &quot;f1&quot; _FM &quot;f2&quot; _FM &quot;v1&quot; _VM &quot;v2&quot; _FM &quot;f4&quot;</span>
</pre></div>
</td></tr>
<tr><td></td><td>var v1 = {"a", "b", "c" ...}; // Initializer list</td><td>Create a dynamic array var from a list. C++ constrains list elements to be all the same type: var, string, double, int, etc. but they all end up as fields of a dynamic array string.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="mi">11</span><span class="p">,</span><span class="w"> </span><span class="mi">22</span><span class="p">,</span><span class="w"> </span><span class="mi">33</span><span class="p">};</span><span class="w"> </span><span class="c1">// &quot;11^22^33&quot;_var</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="mi">11</span><span class="p">,</span><span class="w"> </span><span class="mi">22</span><span class="p">,</span><span class="w"> </span><span class="mi">33</span><span class="p">};</span><span class="w"> </span><span class="c1">// &quot;11^22^33&quot;_var</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>v2(fieldno);      v1(fieldno) = v2</td><td><p>Dynamic array - field extraction, update and append:
<tr><td><p><code>var=</code></p></td><td><p><code>v2(fieldno);      v1(fieldno) = v2</code></p></td><td><p>Dynamic array field extraction, update and append:</p>
</p>
<p>See also inserter() and remover().</p>
<p>See also inserter() and remover().
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aa^bb&quot;</span><span class="kt">_var</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aa^bb&quot;</span><span class="kt">_var</span><span class="p">;</span>
<span class="n">v1</span><span class="p">(</span><span class="mi">4</span><span class="p">)</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">44</span><span class="p">;</span><span class="w"> </span><span class="c1">// v1 -&gt; &quot;aa^bb^^44&quot;_var</span>
<span class="n">v1</span><span class="p">(</span><span class="mi">4</span><span class="p">)</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">44</span><span class="p">;</span><span class="w"> </span><span class="c1">// v1 -&gt; &quot;aa^bb^^44&quot;_var</span>
Line 628: Line 706:
<span class="n">v1</span><span class="p">(</span><span class="mi">-1</span><span class="p">)</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;55&quot;</span><span class="p">;</span><span class="w"> </span><span class="c1">// v1 -&gt; &quot;aa^bb^^44^55&quot;_var</span>
<span class="n">v1</span><span class="p">(</span><span class="mi">-1</span><span class="p">)</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;55&quot;</span><span class="p">;</span><span class="w"> </span><span class="c1">// v1 -&gt; &quot;aa^bb^^44^55&quot;_var</span>
</pre></div>
</pre></div>
Field access:
</p>
</p>
<p>It is recommended to use "v1.f(fieldno)" syntax using a ".f(" prefix to access fields in expressions instead of plain "v1(fieldno)". The former syntax (using .f()) will always compile whereas the latter does not compile in all contexts. It will compile only if being called on a constant var or in a location which requires a var. This is due to C++ not making a clear distinction between usage on the left and right side of assignment operator =.
<p></p>
</p>
<p>Field access:</p>
Furthermore using plain round brackets without the leading .f can be confused with function call syntax.
<p>It is recommended to use "v1.f(fieldno)" syntax using a ".f(" prefix to access fields in expressions instead of plain "v1(fieldno)". The former syntax (using .f()) will always compile whereas the latter does not compile in all contexts. It will compile only if being called on a constant var or in a location which requires a var. This is due to C++ not making a clear distinction between usage on the left and right side of assignment operator =.</p>
<p>Furthermore using plain round brackets without the leading .f can be confused with function call syntax.</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aa^bb^cc&quot;</span><span class="kt">_var</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aa^bb^cc&quot;</span><span class="kt">_var</span><span class="p">;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">f</span><span class="p">(</span><span class="mi">2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;bb&quot; /// .f() style access. Recommended.</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">f</span><span class="p">(</span><span class="mi">2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;bb&quot; /// .f() style access. Recommended.</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v3</span><span class="w"> </span><span class="o">=</span><span class="w">  </span><span class="n">v1</span><span class="p">(</span><span class="mi">2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;bb&quot; ///  () style access. Not recommended.</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v3</span><span class="w"> </span><span class="o">=</span><span class="w">  </span><span class="n">v1</span><span class="p">(</span><span class="mi">2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;bb&quot; ///  () style access. Not recommended.</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>v2(fieldno, valueno);      v1(fieldno, valueno) = v2</td><td><p>Dynamic array - value update and append
<tr><td><p><code>var=</code></p></td><td><p><code>v2(fieldno, valueno);      v1(fieldno, valueno) = v2</code></p></td><td><p>Dynamic array value update and append</p>
</p>
<p>See also inserter() and remover().</p>
See also inserter() and remover().
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aa^b1]b2^cc&quot;</span><span class="kt">_var</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aa^b1]b2^cc&quot;</span><span class="kt">_var</span><span class="p">;</span>
<span class="n">v1</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">4</span><span class="p">)</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;44&quot;</span><span class="p">;</span><span class="w"> </span><span class="c1">// v1 -&gt; &quot;aa^b1]b2]]44^cc&quot;_var</span>
<span class="n">v1</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">4</span><span class="p">)</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;44&quot;</span><span class="p">;</span><span class="w"> </span><span class="c1">// v1 -&gt; &quot;aa^b1]b2]]44^cc&quot;_var</span>
Line 646: Line 726:
<span class="n">v1</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">-1</span><span class="p">)</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">55</span><span class="p">;</span><span class="w"> </span><span class="c1">// v1 -&gt; &quot;aa^b1]b2]]44]55^cc&quot;_var</span>
<span class="n">v1</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">-1</span><span class="p">)</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">55</span><span class="p">;</span><span class="w"> </span><span class="c1">// v1 -&gt; &quot;aa^b1]b2]]44]55^cc&quot;_var</span>
</pre></div>
</pre></div>
Value access:
</p>
<p></p>
<p>Value access:</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aa^b1]b2^cc&quot;</span><span class="kt">_var</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aa^b1]b2^cc&quot;</span><span class="kt">_var</span><span class="p">;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">f</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="mi">2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;b2&quot; /// .f() style access. Recommended.</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">f</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="mi">2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;b2&quot; /// .f() style access. Recommended.</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v3</span><span class="w"> </span><span class="o">=</span><span class="w">  </span><span class="n">v1</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="mi">2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;b2&quot; ///  () style access. Not recommended.</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v3</span><span class="w"> </span><span class="o">=</span><span class="w">  </span><span class="n">v1</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="mi">2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;b2&quot; ///  () style access. Not recommended.</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
</table>
</table>
Line 657: Line 741:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>var=</td><td>v2 ^ v3</td><td><p>String concatention operator ^
<tr><td><p><code>var=</code></p></td><td><p><code>v2 ^ v3</code></p></td><td><p>String concatention operator ^</p>
</p>
<p>At least one side must be a var.</p>
<p>At least one side must be a var.
<p>"aa" ^ "22" will not compile but "aa" "22" will.</p>
</p>
<p>Floating point numbers are implicitly converted to strings with no more than 12 significant digits of precision. This practically eliminates all floatng point rounding errors.
<p>"aa" ^ "22" will not compile but "aa" "22" will.
</p>
Floating point numbers are implicitly converted to strings with no more than 12 significant digits of precision. This practically eliminates all floatng point rounding errors.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aa&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aa&quot;</span><span class="p">;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="mi">22</span><span class="p">;</span><span class="w"> </span><span class="c1">// &quot;aa22&quot;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="mi">22</span><span class="p">;</span><span class="w"> </span><span class="c1">// &quot;aa22&quot;</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>v1 ^= v2</td><td>String self concatention ^= (append)
<tr><td><p><code></code></p></td><td><p><code>v1 ^= v2</code></p></td><td><p>String self concatention ^= (append)
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aa&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aa&quot;</span><span class="p">;</span>
<span class="n">v1</span><span class="w"> </span><span class="o">^=</span><span class="w"> </span><span class="mi">22</span><span class="p">;</span><span class="w"> </span><span class="c1">// v1 -&gt; &quot;aa22&quot;</span>
<span class="n">v1</span><span class="w"> </span><span class="o">^=</span><span class="w"> </span><span class="mi">22</span><span class="p">;</span><span class="w"> </span><span class="c1">// v1 -&gt; &quot;aa22&quot;</span>
</pre></div></td></tr>
</pre></div>
<tr><td>var=</td><td>varnum.round(ndecimals = 0)</td><td><p>Convert a number into a string after rounding it to a given number of decimal places.
</p>
</p>
<p>Trailing zeros are not omitted. A leading "0." is shown where appropriate.
</td></tr>
</p>
<tr><td><p><code>var=</code></p></td><td><p><code>varnum.round(ndecimals = 0)</code></p></td><td><p>Round a number.</p>
<p>0.5 always rounds away from zero. i.e. 1.5 -> 2 and -2.5 -> -3
<p>Convert a number into a string after rounding it to a given number of decimal places.</p>
</p>
<p>Trailing zeros are not omitted. A leading "0." is shown where appropriate.</p>
<p><em>var:</em> The number to be converted.
<p>0.5 always rounds away from zero. i.e. 1.5 -&gt; 2 and -2.5 -&gt; -3</p>
</p>
<p><em>var:</em> The number to be converted.</p>
<p><em>ndecimals:</em> Determines how many decimal places are shown to the right of the decimal point or, if ndecimals is negative, how many 0's to the left of it.
<p><em>ndecimals:</em> Determines how many decimal places are shown to the right of the decimal point or, if ndecimals is negative, how many 0's to the left of it.</p>
</p>
<p><em>return:</em> A var containing an ASCII string of digits with a leading "-" if negative, and a decimal point "." if ndecimals is &gt; 0.</p>
<em>Returns:</em> A var containing an ASCII string of digits with a leading "-" if negative, and a decimal point "." if ndecimals is > 0.
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mf">0.295</span><span class="p">).</span><span class="nf">round</span><span class="p">(</span><span class="mi">2</span><span class="p">);</span><span class="w">  </span><span class="c1">//  &quot;0.30&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mf">0.295</span><span class="p">).</span><span class="nf">round</span><span class="p">(</span><span class="mi">2</span><span class="p">);</span><span class="w">  </span><span class="c1">//  &quot;0.30&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
Line 695: Line 776:
<span class="kt">var</span><span class="w"> </span><span class="n">v7</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">round</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="mi">-1</span><span class="p">);</span><span class="w">          </span><span class="c1">// &quot;0&quot;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v7</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">round</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="mi">-1</span><span class="p">);</span><span class="w">          </span><span class="c1">// &quot;0&quot;</span>
</pre></div>
</pre></div>
Negative number of decimals rounds to the left of the decimal point
</p>
<p>Negative number of decimals rounds to the left of the decimal point
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">round</span><span class="p">(</span><span class="mf">123456.789</span><span class="p">,</span><span class="w">  </span><span class="mi">0</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;123457&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">round</span><span class="p">(</span><span class="mf">123456.789</span><span class="p">,</span><span class="w">  </span><span class="mi">0</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;123457&quot;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">round</span><span class="p">(</span><span class="mf">123456.789</span><span class="p">,</span><span class="w"> </span><span class="mi">-1</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;123460&quot;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">round</span><span class="p">(</span><span class="mf">123456.789</span><span class="p">,</span><span class="w"> </span><span class="mi">-1</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;123460&quot;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v3</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">round</span><span class="p">(</span><span class="mf">123456.789</span><span class="p">,</span><span class="w"> </span><span class="mi">-2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;123500&quot;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v3</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">round</span><span class="p">(</span><span class="mf">123456.789</span><span class="p">,</span><span class="w"> </span><span class="mi">-2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;123500&quot;</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>var::chr(num)</td><td><p>Get a char given an integer 0-255.
<tr><td><p><code>var=</code></p></td><td><p><code>var::chr(num)</code></p></td><td><p>Get a char.</p>
</p>
<p><em>num:</em> An integer 0-255.</p>
<p><em>Returns:</em> A string containing a single char
<p><em>return:</em> A string containing a single char</p>
</p>
<p>0-127 -&gt; ASCII, 128-255 -&gt; invalid UTF-8 which cannot be written to the database or used in many exodus string operations</p>
0-127 -> ASCII, 128-255 -> invalid UTF-8 which cannot be written to the database or used in many exodus string operations
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">chr</span><span class="p">(</span><span class="mh">0x61</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;a&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">chr</span><span class="p">(</span><span class="mh">0x61</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;a&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">chr</span><span class="p">(</span><span class="mh">0x61</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">chr</span><span class="p">(</span><span class="mh">0x61</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>var::textchr(num)</td><td><p>Get a Unicode character given a Unicode Code Point (Number)
<tr><td><p><code>var=</code></p></td><td><p><code>var::textchr(num)</code></p></td><td><p>Get a Unicode character.</p>
</p>
<p><em>num:</em> A Unicode Code Point (Number)</p>
<em>Returns:</em> A single Unicode character in UTF8 encoding.
<p><em>return:</em> A single Unicode character in UTF8 encoding.</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">textchr</span><span class="p">(</span><span class="mi">171416</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;𩶘&quot; // or &quot;\xF0A9B698&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">textchr</span><span class="p">(</span><span class="mi">171416</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;𩶘&quot; // or &quot;\xF0A9B698&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">textchr</span><span class="p">(</span><span class="mi">171416</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">textchr</span><span class="p">(</span><span class="mi">171416</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>var::textchrname(unicode_code_point)</td><td><p>Get a Unicode character name
<tr><td><p><code>var=</code></p></td><td><p><code>var::textchrname(unicode_code_point)</code></p></td><td><p>Get a Unicode character name</p>
</p>
<p><em>unicode_code_point:</em> 0 - 0x10FFFF.</p>
<p><em>unicode_code_point:</em> 0 - 0x10FFFF.
<p><em>return:</em> Text of the name or "" if not a valid Unicode Code Point</p>
</p>
<p>
<em>Returns:</em> Text of the name or "" if not a valid Unicode Code Point
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">textchrname</span><span class="p">(</span><span class="mi">91</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;LEFT SQUARE BRACKET&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">textchrname</span><span class="p">(</span><span class="mi">91</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;LEFT SQUARE BRACKET&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">textchrname</span><span class="p">(</span><span class="mi">91</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">textchrname</span><span class="p">(</span><span class="mi">91</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.str(num)</td><td><p>Get a string of repeated substrings.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.str(num)</code></p></td><td><p>Get a string of repeated substrings.</p>
</p>
<p><em>var:</em> The substring to be repeated</p>
<p><em>var:</em> The substring to be repeated
<p><em>num:</em> How many times to repeat the substring</p>
</p>
<p><em>return:</em> A string</p>
<p><em>num:</em> How many times to repeat the substring
<p>
</p>
<em>Returns:</em> A string
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;ab&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">str</span><span class="p">(</span><span class="mi">3</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;ababab&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;ab&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">str</span><span class="p">(</span><span class="mi">3</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;ababab&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">str</span><span class="p">(</span><span class="s">&quot;ab&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">str</span><span class="p">(</span><span class="s">&quot;ab&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>var::space(nspaces)</td><td><p>Get a string containing a given number of spaces.
<tr><td><p><code>var=</code></p></td><td><p><code>var::space(nspaces)</code></p></td><td><p>Get a string as a given number of spaces.</p>
</p>
<p><em>nspaces:</em> The number of spaces required.</p>
<p><em>nspaces:</em> The number of spaces required.
<p><em>return:</em> A string of space chars.</p>
</p>
<p>
<em>Returns:</em> A string of space chars.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">space</span><span class="p">(</span><span class="mi">3</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;␣␣␣&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">space</span><span class="p">(</span><span class="mi">3</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;␣␣␣&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">space</span><span class="p">(</span><span class="mi">3</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">space</span><span class="p">(</span><span class="mi">3</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>varnum.numberinwords(locale = "")</td><td>
<tr><td><p><code>var=</code></p></td><td><p><code>varnum.numberinwords(locale = "")</code></p></td><td><p>Get a number written out in words insteads of digits.</p>
<p><em>Returns:</em> A string representing a given number written in words instead of digits.
<p><em>return:</em> A string.</p>
</p>
<p><em>locale:</em> e.g. en_GB, ar_AE, el_CY, es_US, fr_FR etc or a language name e.g. "french".</p>
<em>locale:</em> e.g. en_GB, ar_AE, el_CY, es_US, fr_FR etc or a language name e.g. "french".
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">softhyphen</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;</span><span class="se">\xc2\xad</span><span class="s">&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">softhyphen</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;</span><span class="se">\xc2\xad</span><span class="s">&quot;</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mf">123.45</span><span class="p">).</span><span class="nf">numberinwords</span><span class="p">(</span><span class="s">&quot;de_DE&quot;</span><span class="p">).</span><span class="nf">replace</span><span class="p">(</span><span class="n">softhyphen</span><span class="p">,</span><span class="w"> </span><span class="s">&quot; &quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;ein␣hundert␣drei␣und␣zwanzig␣Komma␣vier␣fünf&quot;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mf">123.45</span><span class="p">).</span><span class="nf">numberinwords</span><span class="p">(</span><span class="s">&quot;de_DE&quot;</span><span class="p">).</span><span class="nf">replace</span><span class="p">(</span><span class="n">softhyphen</span><span class="p">,</span><span class="w"> </span><span class="s">&quot; &quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;ein␣hundert␣drei␣und␣zwanzig␣Komma␣vier␣fünf&quot;</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
</table>
</table>
Line 764: Line 850:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>var=</td><td>strvar.at(pos1)</td><td><p>Get a single char from a string.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.at(pos1)</code></p></td><td><p>Get a single char from a string.</p>
</p>
<p><em>pos1:</em> First char is 1. Last char is -1.</p>
<p><em>pos1:</em> First char is 1. Last char is -1.
<p><em>return:</em> A single char if pos1 +/- the length of the string, or "" if greater. Returns the first char if pos1 is 0 or (-pos1) &gt; length.
</p>
<em>Returns:</em> A single char if pos1 +/- the length of the string, or "" if greater. Returns the first char if pos1 is 0 or (-pos1) > length.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="p">;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">at</span><span class="p">(</span><span class="mi">2</span><span class="p">);</span><span class="w">  </span><span class="c1">// &quot;b&quot;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">at</span><span class="p">(</span><span class="mi">2</span><span class="p">);</span><span class="w">  </span><span class="c1">// &quot;b&quot;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v3</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">at</span><span class="p">(</span><span class="mi">-3</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;a&quot;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v3</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">at</span><span class="p">(</span><span class="mi">-3</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;a&quot;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v4</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">at</span><span class="p">(</span><span class="mi">4</span><span class="p">);</span><span class="w">  </span><span class="c1">// &quot;&quot;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v4</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">at</span><span class="p">(</span><span class="mi">4</span><span class="p">);</span><span class="w">  </span><span class="c1">// &quot;&quot;</span>
</pre></div></td></tr>
</pre></div>
<tr><td>var=</td><td>strvar.ord()</td><td><p>Get the char number of a char
</p>
</p>
<p><em>Returns:</em> A number between 0 and 255.
</td></tr>
</p>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.ord()</code></p></td><td><p>Get the char number of a char.</p>
<p>If given a string, then only the first char is considered.
<p><em>return:</em> A number between 0 and 255.</p>
</p>
<p>If given a string, then only the first char is considered.</p>
Equivalent to ord() in php
<p>Equivalent to ord() in php</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">ord</span><span class="p">();</span><span class="w"> </span><span class="c1">// 0x61 // decimal 97, &#39;a&#39;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">ord</span><span class="p">();</span><span class="w"> </span><span class="c1">// 0x61 // decimal 97, &#39;a&#39;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ord</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ord</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.textord()</td><td><p>Get the Unicode Code Point of a Unicode character.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.textord()</code></p></td><td><p>Get the Unicode Code Point of a Unicode character.</p>
</p>
<p><em>var:</em> A UTF-8 string. Only the first Unicode character is considered.</p>
<p><em>var:</em> A UTF-8 string. Only the first Unicode character is considered.
<p><em>return:</em> A number 0 to 0x10FFFF.</p>
</p>
<p>Equivalent to ord() in python and ruby, mb_ord() php.</p>
<p><em>Returns:</em> A number 0 to 0x10FFFF.
<p>
</p>
Equivalent to ord() in python and ruby, mb_ord() php.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Γ&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">textord</span><span class="p">();</span><span class="w"> </span><span class="c1">// 915 // U+0393: Greek Capital Letter Gamma (Unicode character)</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Γ&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">textord</span><span class="p">();</span><span class="w"> </span><span class="c1">// 915 // U+0393: Greek Capital Letter Gamma (Unicode character)</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">textord</span><span class="p">(</span><span class="s">&quot;Γ&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">textord</span><span class="p">(</span><span class="s">&quot;Γ&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.len()</td><td><p>Get the length of a source string in number of chars
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.len()</code></p></td><td><p>Get the length of a source string in number of chars.</p>
</p>
<p><em>return:</em> A number</p>
<em>Returns:</em> A number
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">len</span><span class="p">();</span><span class="w"> </span><span class="c1">// 3</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">len</span><span class="p">();</span><span class="w"> </span><span class="c1">// 3</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">len</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">len</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>strvar.empty()</td><td><p>Checks if the var is an empty string.
<tr><td><p><code>if</code></p></td><td><p><code>strvar.empty()</code></p></td><td><p>Check if the var is an empty string.</p>
</p>
<p><em>return:</em> True if it is empty amd false if not.</p>
<p><em>Returns:</em> True if it is empty amd false if not.
<p>This is a shorthand and more expressive way of writing 'if (var == "")' or 'if (var.len() == 0)' or 'if (not var.len())'</p>
</p>
<p>Note that 'if (var.empty())' is not exactly the same as 'if (not var)' because 'if (var("0.0")' is also defined as false. If a string can be converted to 0 then it is considered to be false. Contrast this with common scripting languages where 'if (var("0"))' is defined to be true.</p>
<p>This is a shorthand and more expressive way of writing 'if (var == "")' or 'if (var.len() == 0)' or 'if (not var.len())'
<p>
</p>
Note that 'if (var.empty())' is not exactly the same as 'if (not var)' because 'if (var("0.0")' is also defined as false. If a string can be converted to 0 then it is considered to be false. Contrast this with common scripting languages where 'if (var("0"))' is defined to be true.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;0&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;0&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">empty</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">// true</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">empty</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">// true</span>
Line 818: Line 901:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">empty</span><span class="p">(</span><span class="n">v1</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">// true</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">empty</span><span class="p">(</span><span class="n">v1</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">// true</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.textwidth()</td><td><p>Count the number of output columns required for a given source string.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.textwidth()</code></p></td><td><p>Count the number of output columns required for a given source string.</p>
</p>
<p><em>return:</em> A number</p>
<p><em>Returns:</em> A number
<p>Allow wide multi-column Unicode characters that occupy more than one space in a text file or terminal screen.</p>
</p>
<p>Reduce combining characters to a single column. e.g. "e" followed by grave accent is multiple bytes but only occupies one output column.</p>
<p>Allows wide multi-column Unicode characters that occupy more than one space in a text file or terminal screen.
<p>Does not properly calculate all possible combining sequences of graphemes e.g. face followed by colour</p>
</p>
<p>
<p>Reduces combining characters to a single column. e.g. "e" followed by grave accent is multiple bytes but only occupies one output column.
</p>
Does not properly calculate all possible combining sequences of graphemes e.g. face followed by colour
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;🤡x🤡&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">textwidth</span><span class="p">();</span><span class="w"> </span><span class="c1">// 5</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;🤡x🤡&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">textwidth</span><span class="p">();</span><span class="w"> </span><span class="c1">// 5</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">textwidth</span><span class="p">(</span><span class="s">&quot;🤡x🤡&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">textwidth</span><span class="p">(</span><span class="s">&quot;🤡x🤡&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.textlen()</td><td><p>Count the number of Unicode code points in a source string.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.textlen()</code></p></td><td><p>Count the number of Unicode code points in a source string.</p>
</p>
<p><em>return:</em> A number.</p>
<em>Returns:</em> A number.
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Γιάννης&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">textlen</span><span class="p">();</span><span class="w"> </span><span class="c1">// 7</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Γιάννης&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">textlen</span><span class="p">();</span><span class="w"> </span><span class="c1">// 7</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">textlen</span><span class="p">(</span><span class="s">&quot;Γιάννης&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">textlen</span><span class="p">(</span><span class="s">&quot;Γιάννης&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.fcount(sepstr)</td><td><p>Count the number of fields in a source string.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.fcount(sepstr)</code></p></td><td><p>Count the number of fields in a source string.</p>
</p>
<p><em>sepstr:</em> The separator character or substr that delimits individual fields.</p>
<p><em>sepstr:</em> The separator character or substr that delimits individual fields.
<p><em>return:</em> The count of the number of fields</p>
</p>
<p>This is similar to "var.count(sepstr) + 1" but it returns 0 for an empty source string.</p>
<p><em>Returns:</em> The count of the number of fields
<p>
</p>
This is similar to "var.count(sepstr) + 1" but it returns 0 for an empty source string.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aa**cc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">fcount</span><span class="p">(</span><span class="s">&quot;*&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// 3</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aa**cc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">fcount</span><span class="p">(</span><span class="s">&quot;*&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// 3</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">fcount</span><span class="p">(</span><span class="s">&quot;aa**cc&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;*&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">fcount</span><span class="p">(</span><span class="s">&quot;aa**cc&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;*&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.count(sepstr)</td><td><p>Count the number of occurrences of a given substr in a source string.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.count(sepstr)</code></p></td><td><p>Count the number of occurrences of a given substr in a source string.</p>
</p>
<p><em>substr:</em> The substr to count.</p>
<p><em>substr:</em> The substr to count.
<p><em>return:</em> The count of the number of sepstr found.</p>
</p>
<p>Overlapping substrings are not counted.</p>
<p><em>Returns:</em> The count of the number of sepstr found.
<p>
</p>
Overlapping substrings are not counted.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aa**cc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">count</span><span class="p">(</span><span class="s">&quot;*&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// 2</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aa**cc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">count</span><span class="p">(</span><span class="s">&quot;*&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// 2</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">count</span><span class="p">(</span><span class="s">&quot;aa**cc&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;*&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">count</span><span class="p">(</span><span class="s">&quot;aa**cc&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;*&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>strvar.starts(prefix)</td><td><p>Checks if a source string starts with a given prefix (substr).
<tr><td><p><code>if</code></p></td><td><p><code>strvar.starts(prefix)</code></p></td><td><p>Check if a source string starts with a given prefix (substr).</p>
</p>
<p><em>prefix:</em> The substr to check for.</p>
<p><em>prefix:</em> The substr to check for.
<p><em>return:</em> True if the source string starts with the given prefix.</p>
</p>
<p>Always returns false if suffix is "". DIFFERS from c++, javascript, python3. See contains() for more info.</p>
<p><em>Returns:</em> True if the source string starts with the given prefix.
<p>
</p>
<em>Returns:</em> False if prefix is "". DIFFERS from c++, javascript, python3. See contains() for more info.
<div class="highlight light"><pre><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">starts</span><span class="p">(</span><span class="s">&quot;ab&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="nb">true</span>
<div class="highlight light"><pre><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">starts</span><span class="p">(</span><span class="s">&quot;ab&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="nb">true</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">starts</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;ab&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="nb">true</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">starts</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;ab&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="nb">true</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>strvar.ends(suffix)</td><td><p>Checks if a source string ends with a given suffix (substr).
<tr><td><p><code>if</code></p></td><td><p><code>strvar.ends(suffix)</code></p></td><td><p>Check if a source string ends with a given suffix (substr).</p>
</p>
<p><em>suffix:</em> The substr to check for.</p>
<p><em>suffix:</em> The substr to check for.
<p><em>return:</em> True if the source string ends with given suffix.</p>
</p>
<p>Always returns false if suffix is "". DIFFERS from c++, javascript, python3. See contains() for more info.</p>
<p><em>Returns:</em> True if the source string ends with given suffix.
<p>
</p>
<em>Returns:</em> False if suffix is "". DIFFERS from c++, javascript, python3. See contains() for more info.
<div class="highlight light"><pre><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">ends</span><span class="p">(</span><span class="s">&quot;bc&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="nb">true</span>
<div class="highlight light"><pre><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">ends</span><span class="p">(</span><span class="s">&quot;bc&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="nb">true</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">ends</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;bc&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="nb">true</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">ends</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;bc&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="nb">true</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>strvar.contains(substr)</td><td><p>Checks if a given substr exists in a source string.
<tr><td><p><code>if</code></p></td><td><p><code>strvar.contains(substr)</code></p></td><td><p>Check if a given substr exists in a source string.</p>
</p>
<p><em>substr:</em> The substr to check for.</p>
<p><em>substr:</em> The substr to check for.
<p><em>return:</em> True if the source string starts with, ends with or contains the given substr.</p>
</p>
<p>Always returns false if substr is "". DIFFERS from c++, javascript, python3. See contains() for more info.</p>
<p><em>Returns:</em> True if the source string starts with, ends with or contains the given substr.
<p>Human logic: "" is not equal to "x" therefore x does not contain "".</p>
</p>
<p>Human logic: Check each item (character) in the list for equality with what I am looking for and return success if any are equal.</p>
<p><em>Returns:</em> False if suffix is "". DIFFERS from c++, javascript, python3
<p>Programmer logic: Compare as many characters as are in the search string for presence in the list of characters and return success if there are no failures.</p>
</p>
<p>
<p>Human logic: "" is not equal to "x" therefore x does not contain "".
</p>
<p>Human logic: Check each item (character) in the list for equality with what I am looking for and return success if any are equal.
</p>
Programmer logic: Compare as many characters as are in the search string for presence in the list of characters and return success if there are no failures.
<div class="highlight light"><pre><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="s">&quot;abcd&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">contains</span><span class="p">(</span><span class="s">&quot;bc&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="nb">true</span>
<div class="highlight light"><pre><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="s">&quot;abcd&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">contains</span><span class="p">(</span><span class="s">&quot;bc&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="nb">true</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">contains</span><span class="p">(</span><span class="s">&quot;abcd&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;bc&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="nb">true</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">contains</span><span class="p">(</span><span class="s">&quot;abcd&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;bc&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="nb">true</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.index(substr, startchar1 = 1)</td><td><p>Find a substr in a source string.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.index(substr, startchar1 = 1)</code></p></td><td><p>Find a substr in a source string.</p>
</p>
<p><em>substr:</em> The substr to search for.</p>
<p><em>substr:</em> The substr to search for.
<p><em>startchar1:</em> The char position (1 based) to start the search at. The default is 1, the first char.</p>
</p>
<p><em>return:</em> The char position (1 based) that the substr is found at or 0 if not present.</p>
<p><em>startchar1:</em> The char position (1 based) to start the search at. The default is 1, the first char.
<p>
</p>
<em>Returns:</em> The char position (1 based) that the substr is found at or 0 if not present.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abcd&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">index</span><span class="p">(</span><span class="s">&quot;bc&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// 2</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abcd&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">index</span><span class="p">(</span><span class="s">&quot;bc&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// 2</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">index</span><span class="p">(</span><span class="s">&quot;abcd&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;bc&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">index</span><span class="p">(</span><span class="s">&quot;abcd&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;bc&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.indexn(substr, occurrence)</td><td><p>Find the nth occurrence of a substr in a source string.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.indexn(substr, occurrence)</code></p></td><td><p>Find the nth occurrence of a substr in a source string.</p>
</p>
<p><em>substr:</em> The string to search for.</p>
<p><em>substr:</em> The string to search for.
<p><em>return:</em> char position (1 based) or 0 if not present.</p>
</p>
<p>
<em>Returns:</em> char position (1 based) or 0 if not present.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abcabc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">indexn</span><span class="p">(</span><span class="s">&quot;bc&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span><span class="w"> </span><span class="c1">// 5</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abcabc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">indexn</span><span class="p">(</span><span class="s">&quot;bc&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span><span class="w"> </span><span class="c1">// 5</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">indexn</span><span class="p">(</span><span class="s">&quot;abcabc&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;bc&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">indexn</span><span class="p">(</span><span class="s">&quot;abcabc&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;bc&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.indexr(substr, startchar1 = -1)</td><td><p>Find the position of substr working backwards from the end of the string towards the beginning.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.indexr(substr, startchar1 = -1)</code></p></td><td><p>Find the position of substr working backwards</p>
</p>
<p>Start at the end and work backwards.</p>
<p><em>substr:</em> The string to search for.
<p><em>substr:</em> The string to search for.</p>
</p>
<p><em>return:</em> The char position of the substr if found, or 0 if not.</p>
<p><em>Returns:</em> The char position of the substr if found, or 0 if not.
<p><em>startchar1:</em> Defaults to -1 meaning start searching from the last char. Positive start1char1 counts from the beginning of the source string and negative startchar1 counts backwards from the last char.</p>
</p>
<p>
<em>startchar1:</em> defaults to -1 meaning start searching from the last char. Positive start1char1 counts from the beginning of the source string and negative startchar1 counts backwards from the last char.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abcabc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">indexr</span><span class="p">(</span><span class="s">&quot;bc&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// 5</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abcabc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">indexr</span><span class="p">(</span><span class="s">&quot;bc&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// 5</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">indexr</span><span class="p">(</span><span class="s">&quot;abcabc&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;bc&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">indexr</span><span class="p">(</span><span class="s">&quot;abcabc&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;bc&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.match(regex_str, regex_options = "")</td><td><p>Finds all matches of a given regular expression.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.match(regex_str, regex_options = "")</code></p></td><td><p>Find all matches of a given regular expression.</p>
</p>
<p><em>return:</em> Zero or more matching substrings separated by FMs. Any groups are in VMs.</p>
<p><em>Returns:</em> Zero or more matching substrings separated by FMs. Any groups are in VMs.
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc1abc2&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">match</span><span class="p">(</span><span class="s">&quot;BC(</span><span class="se">\\</span><span class="s">d)&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;i&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;bc1]1^bc2]2&quot;_var</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc1abc2&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">match</span><span class="p">(</span><span class="s">&quot;BC(</span><span class="se">\\</span><span class="s">d)&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;i&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;bc1]1^bc2]2&quot;_var</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">match</span><span class="p">(</span><span class="s">&quot;abc1abc2&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;BC(</span><span class="se">\\</span><span class="s">d)&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;i&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">match</span><span class="p">(</span><span class="s">&quot;abc1abc2&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;BC(</span><span class="se">\\</span><span class="s">d)&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;i&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</p>
<p><em>regex_options:</em>
<p></p>
</p>
<p><em>regex_options:</em> </p>
<p>* l - Literal (any regex chars are treated as normal chars)
<dl>
</p>
<dt>l</dt><dd>Literal (any regex chars are treated as normal chars)</dd>
<p>* i - Case insensitive
<dt>i</dt><dd>Case insensitive</dd>
</p>
<dt>p</dt><dd>ECMAScript/Perl (the default)</dd>
<p>* p - ECMAScript/Perl (the default)
<dt>b</dt><dd>Basic POSIX (same as sed)</dd>
</p>
<dt>e</dt><dd>Extended POSIX</dd>
<p>* b - Basic POSIX (same as sed)
<dt>a</dt><dd>awk</dd>
</p>
<dt>g</dt><dd>grep</dd>
<p>* e - Extended POSIX
<dt>eg</dt><dd>egrep or grep -E</dd>
</p>
</dl>
<p>* a - awk
<p></p>
</p>
<p>char ranges like a-z are locale sensitive if ECMAScript</p>
<p>* g - grep
<p></p>
</p>
<p><em>regex_options:</em> </p>
<p>* eg - egrep or grep -E
<dl>
</p>
<dt>m</dt><dd>Multiline. Default in boost (and therefore exodus)</dd>
 
<dt>s</dt><dd>Single line. Default in std::regex</dd>
<p>char ranges like a-z are locale sensitive if ECMAScript
<dt>f</dt><dd>First only. Only for replace() (not match() or search())</dd>
</p>
<dt>w</dt><dd>Wildcard glob style (e.g. *.cfg) not regex style. Only for match() and search(). Not replace().</dd>
 
</dl>
<p><em>regex_options:</em>
</td></tr>
</p>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.match(regex)</code></p></td><td><p>Ditto</p>
<p>* m - Multiline. Default in boost (and therefore exodus)
</td></tr>
</p>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.search(regex_str, io startchar1, regex_options = "")</code></p></td><td><p>Search for the first match of a regular expression.</p>
<p>* s - Single line. Default in std::regex
<p><em>startchar1:</em> [in] char position to start the search from</p>
</p>
<p><em>startchar1[out]:</em> char position to start the next search from or 0 if no more matches.</p>
<p>* f - First only. Only for replace() (not match() or search())
<p><em>return:</em> The 1st match like match()</p>
</p>
<p>regex_options as for match()</p>
<p>* w - Wildcard glob style (e.g. *.cfg) not regex style. Only for match() and search(). Not replace().
<p>
</p>
</td></tr>
<tr><td>var=</td><td>strvar.match(regex)</td><td>Ditto</td></tr>
<tr><td>var=</td><td>strvar.search(regex_str, io startchar1, regex_options = "")</td><td><p>Search for the first match of a regular expression.
</p>
<p><em>startchar1:</em> [in] char position to start the search from
</p>
<p><em>startchar1:</em> [out] char position to start the next search from or 0 if no more matches.
</p>
<p><em>Returns:</em> The 1st match like match()
</p>
regex_options as for match()
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">startchar1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">startchar1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc1abc2&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">search</span><span class="p">(</span><span class="s">&quot;BC(</span><span class="se">\\</span><span class="s">d)&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">startchar1</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;i&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;bc1]1&quot;_var // startchar1 -&gt; 5 /// Ready for the next search</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc1abc2&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">search</span><span class="p">(</span><span class="s">&quot;BC(</span><span class="se">\\</span><span class="s">d)&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">startchar1</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;i&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;bc1]1&quot;_var // startchar1 -&gt; 5 /// Ready for the next search</span>
Line 999: Line 1,060:
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">search</span><span class="p">(</span><span class="s">&quot;abc1abc2&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;BC(</span><span class="se">\\</span><span class="s">d)&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">startchar1</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;i&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">search</span><span class="p">(</span><span class="s">&quot;abc1abc2&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;BC(</span><span class="se">\\</span><span class="s">d)&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">startchar1</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;i&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.search(regex_str)</td><td>Ditto starting from first char</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.search(regex_str)</code></p></td><td><p>Ditto starting from first char</p>
<tr><td>var=</td><td>strvar.search(regex, io startchar1)</td><td>Ditto given a rex</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.search(regex)</td><td>Ditto starting from first char.</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.search(regex, io startchar1)</code></p></td><td><p>Ditto given a rex</p>
<tr><td>var=</td><td>strvar.hash(std::uint64_t modulus = 0)</td><td><p>Get a hash of a source string.
</td></tr>
</p>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.search(regex)</code></p></td><td><p>Ditto starting from first char.</p>
<p><em>modulus:</em> The result is limited to [0, modulus)
</td></tr>
</p>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.hash(std::uint64_t modulus = 0)</code></p></td><td><p>Get a hash of a source string.</p>
<p><em>Returns:</em> A 64 bit signed integer.
<p><em>modulus:</em> The result is limited to [0, modulus)</p>
</p>
<p><em>return:</em> A 64 bit signed integer.</p>
MurmurHash3 is used.
<p>MurmurHash3 is used.</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">hash</span><span class="p">();</span><span class="w"> </span><span class="n">assert</span><span class="p">(</span><span class="n">v1</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mi">6&#39;715&#39;211&#39;243&#39;465&#39;481&#39;821</span><span class="p">));</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">hash</span><span class="p">();</span><span class="w"> </span><span class="n">assert</span><span class="p">(</span><span class="n">v1</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mi">6&#39;715&#39;211&#39;243&#39;465&#39;481&#39;821</span><span class="p">));</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">hash</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">hash</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
</table>
</table>
Line 1,020: Line 1,084:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>var=</td><td>strvar.ucase()</td><td>Convert to upper case
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.ucase()</code></p></td><td><p>Convert to upper case</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Γιάννης&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">ucase</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;ΓΙΆΝΝΗΣ&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Γιάννης&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">ucase</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;ΓΙΆΝΝΗΣ&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ucase</span><span class="p">(</span><span class="s">&quot;Γιάννης&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ucase</span><span class="p">(</span><span class="s">&quot;Γιάννης&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.lcase()</td><td>Convert to lower case
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.lcase()</code></p></td><td><p>Convert to lower case</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;ΓΙΆΝΝΗΣ&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">lcase</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;γιάννης&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;ΓΙΆΝΝΗΣ&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">lcase</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;γιάννης&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">lcase</span><span class="p">(</span><span class="s">&quot;ΓΙΆΝΝΗΣ&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">lcase</span><span class="p">(</span><span class="s">&quot;ΓΙΆΝΝΗΣ&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.tcase()</td><td><p>Convert to title case.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.tcase()</code></p></td><td><p>Convert to title case.</p>
</p>
<p><em>return:</em> Original source string with the first letter of each word is capitalised.</p>
<em>Returns:</em> Original source string with the first letter of each word is capitalised.
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;γιάννης παππάς&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">tcase</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;Γιάννης Παππάς&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;γιάννης παππάς&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">tcase</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;Γιάννης Παππάς&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">tcase</span><span class="p">(</span><span class="s">&quot;γιάννης παππάς&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">tcase</span><span class="p">(</span><span class="s">&quot;γιάννης παππάς&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.fcase()</td><td><p>Convert to folded case.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.fcase()</code></p></td><td><p>Convert to folded case.</p>
</p>
<p>Case folding is the process of converting text to a case independent representation.</p>
<p>Returns the source string standardised in a way to enable consistent indexing and searching,
<p><em>return:</em> The source string standardised in a way to enable consistent indexing and searching,</p>
</p>
<p><em>https:</em> //www.w3.org/International/wiki/Case_folding</p>
<p>Case folding is the process of converting text to a case independent representation.
<p>Accents can be significant. As in French cote, coté, côte and côté.</p>
</p>
<p>Case folding is not locale-dependent.</p>
<p><em>https:</em>//www.w3.org/International/wiki/Case_folding
<p>
</p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Grüßen&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">fcase</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;grüssen&quot;</span>
<p>Accents can be significant. As in French cote, coté, côte and côté.
</p>
Case folding is not locale-dependent.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Grüßen&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">fcase</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;grüssen&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">tcase</span><span class="p">(</span><span class="s">&quot;Grüßen&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">tcase</span><span class="p">(</span><span class="s">&quot;Grüßen&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.normalize()</td><td><p>Replace Unicode character sequences with their standardised NFC form.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.normalize()</code></p></td><td><p>Replace Unicode character sequences with their standardised NFC form.</p>
</p>
<p>Unicode normalization is the process of converting Unicode strings to a standard form, making them binary comparable and suitable for text processing and comparison. It is an important part of Unicode text processing.</p>
<p>Unicode normalization is the process of converting Unicode strings to a standard form, making them binary comparable and suitable for text processing and comparison. It is an important part of Unicode text processing.
<p>For example, Unicode character "é" can be represented by either a single Unicode character, which is Unicode Code Point (\u00E9" - Latin Small Letter E with Acute), or a combination of two Unicode code points i.e. the ASCII letter "e" and a combining acute accent (Unicode Code Point "\u0301"). Unicode NFC definition converts the pair of code points to the single code point.</p>
</p>
<p>Normalization is not locale-dependent.</p>
<p>For example, Unicode character "é" can be represented by either a single Unicode character, which is Unicode Code Point (\u00E9" - Latin Small Letter E with Acute), or a combination of two Unicode code points i.e. the ASCII letter "e" and a combining acute accent (Unicode Code Point "\u0301"). Unicode NFC definition converts the pair of code points to the single code point.
<p>
</p>
Normalization is not locale-dependent.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;cafe</span><span class="se">\u0301</span><span class="s">&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">normalize</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;caf\u00E9&quot; // &quot;café&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;cafe</span><span class="se">\u0301</span><span class="s">&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">normalize</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;caf\u00E9&quot; // &quot;café&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">normalize</span><span class="p">(</span><span class="s">&quot;cafe</span><span class="se">\u0301</span><span class="s">&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">normalize</span><span class="p">(</span><span class="s">&quot;cafe</span><span class="se">\u0301</span><span class="s">&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.invert()</td><td><p>Simple reversible disguising of string text.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.invert()</code></p></td><td><p>Simple reversible disguising of string text.</p>
</p>
<p>It works by treating the string as UTF8 encoded Unicode code points and inverting the first 8 bits of their Unicode Code Points.</p>
<p>It works by treating the string as UTF8 encoded Unicode code points and inverting the first 8 bits of their Unicode Code Points.
<p><em>return:</em> A string.</p>
</p>
<p>invert(invert()) returns to the original text.</p>
<p><em>Returns:</em> A string.
<p>ASCII bytes become multibyte UTF-8 so string sizes increase.</p>
</p>
<p>Inverted characters remain on their original Unicode Code Page but are jumbled up.</p>
<p>invert(invert()) returns to the original text.
<p>Non-existant Unicode Code Points may be created but UTF8 encoding remains valid.</p>
</p>
<p>
<p>ASCII bytes become multibyte UTF-8 so string sizes increase.
</p>
<p>Inverted characters remain on their original Unicode Code Page but are jumbled up.
</p>
Non-existant Unicode Code Points may be created but UTF8 encoding remains valid.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">invert</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;\xC2&quot; &quot;\x9E&quot; &quot;\xC2&quot; &quot;\x9D&quot; &quot;\xC2&quot; &quot;\x9C&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">invert</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;\xC2&quot; &quot;\x9E&quot; &quot;\xC2&quot; &quot;\x9D&quot; &quot;\xC2&quot; &quot;\x9C&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">invert</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">invert</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.lower()</td><td><p>Reduce all types of field mark chars by one level.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.lower()</code></p></td><td><p>Reduce all types of field mark chars by one level.</p>
</p>
<p>Convert all FM to VM, VM to SM etc.</p>
<p>Convert all FM to VM, VM to SM etc.
<p><em>return:</em> The converted string.</p>
</p>
<p>Note that subtext ST chars are not converted because they are already the lowest level.</p>
<p><em>Returns:</em> The converted string.
<p>String size remains identical.</p>
</p>
<p>
<p>Note that subtext ST chars are not converted because they are already the lowest level.
</p>
String size remains identical.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;a1^b2^c3&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">lower</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;a1]b2]c3&quot;_var</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;a1^b2^c3&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">lower</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;a1]b2]c3&quot;_var</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">lower</span><span class="p">(</span><span class="s">&quot;a1^b2^c3&quot;</span><span class="kt">_var</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">lower</span><span class="p">(</span><span class="s">&quot;a1^b2^c3&quot;</span><span class="kt">_var</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.raise()</td><td><p>Increase all types of field mark chars by one level.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.raise()</code></p></td><td><p>Increase all types of field mark chars by one level.</p>
</p>
<p>Convert all VM to FM, SM to VM etc.</p>
<p>Convert all VM to FM, SM to VM etc.
<p><em>return:</em> The converted string.</p>
</p>
<p>The record mark char RM is not converted because it is already the highest level.</p>
<p><em>Returns:</em> The converted string.
<p>String size remains identical.</p>
</p>
<p>
<p>The record mark char RM is not converted because it is already the highest level.
</p>
String size remains identical.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;a1]b2]c3&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">raise</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;a1^b2^c3&quot;_var</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;a1]b2]c3&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">raise</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;a1^b2^c3&quot;_var</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;a1]b2]c3&quot;</span><span class="kt">_var</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;a1]b2]c3&quot;</span><span class="kt">_var</span><span class="p">;</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.crop()</td><td>Remove any redundant FM, VM etc. chars (Trailing FM; VM before FM etc.)
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.crop()</code></p></td><td><p>Remove any redundant FM, VM etc. chars (Trailing FM; VM before FM etc.)</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;a1^b2]]^c3^^&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">crop</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;a1^b2^c3&quot;_var</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;a1^b2]]^c3^^&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">crop</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;a1^b2^c3&quot;_var</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">crop</span><span class="p">(</span><span class="s">&quot;a1^b2]]^c3^^&quot;</span><span class="kt">_var</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">crop</span><span class="p">(</span><span class="s">&quot;a1^b2]]^c3^^&quot;</span><span class="kt">_var</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.quote()</td><td>Wrap in double quotes.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.quote()</code></p></td><td><p>Wrap in double quotes.</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">quote</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;\&quot;abc\&quot;&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">quote</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;\&quot;abc\&quot;&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">quote</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">quote</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.squote()</td><td>Wrap in single quotes.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.squote()</code></p></td><td><p>Wrap in single quotes.</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">squote</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;&#39;abc&#39;&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">squote</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;&#39;abc&#39;&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">squote</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">squote</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.unquote()</td><td>Remove one pair of surrounding double or single quotes.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.unquote()</code></p></td><td><p>Remove one pair of surrounding double or single quotes.</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;&#39;abc&#39;&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">unquote</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;abc&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;&#39;abc&#39;&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">unquote</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;abc&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">unquote</span><span class="p">(</span><span class="s">&quot;&#39;abc&#39;&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">unquote</span><span class="p">(</span><span class="s">&quot;&#39;abc&#39;&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.trim(trimchars = " ")</td><td><p>Remove all leading, trailing and excessive inner bytes.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.trim(trimchars = " ")</code></p></td><td><p>Remove all leading, trailing and excessive inner bytes.</p>
</p>
<p><em>trimchars:</em> The chars (bytes) to remove. The default is space.</p>
<em>trimchars:</em> The chars (bytes) to remove. The default is space.
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;␣␣a1␣␣b2␣c3␣␣&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">trim</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;a1␣b2␣c3&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;␣␣a1␣␣b2␣c3␣␣&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">trim</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;a1␣b2␣c3&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">trim</span><span class="p">(</span><span class="s">&quot;␣␣a1␣␣b2␣c3␣␣&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">trim</span><span class="p">(</span><span class="s">&quot;␣␣a1␣␣b2␣c3␣␣&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.trimfirst(trimchars = " ")</td><td>Ditto but only leading.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.trimfirst(trimchars = " ")</code></p></td><td><p>Ditto but only leading.</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;␣␣a1␣␣b2␣c3␣␣&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">trimfirst</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;a1␣␣b2␣c3␣␣&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;␣␣a1␣␣b2␣c3␣␣&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">trimfirst</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;a1␣␣b2␣c3␣␣&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">trimfirst</span><span class="p">(</span><span class="s">&quot;␣␣a1␣␣b2␣c3␣␣&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">trimfirst</span><span class="p">(</span><span class="s">&quot;␣␣a1␣␣b2␣c3␣␣&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.trimlast(trimchars = " ")</td><td>Ditto but only trailing.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.trimlast(trimchars = " ")</code></p></td><td><p>Ditto but only trailing.</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;␣␣a1␣␣b2␣c3␣␣&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">trimlast</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;␣␣a1␣␣b2␣c3&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;␣␣a1␣␣b2␣c3␣␣&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">trimlast</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;␣␣a1␣␣b2␣c3&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">trimlast</span><span class="p">(</span><span class="s">&quot;␣␣a1␣␣b2␣c3␣␣&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">trimlast</span><span class="p">(</span><span class="s">&quot;␣␣a1␣␣b2␣c3␣␣&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.trimboth(trimchars = " ")</td><td>Ditto but only leading and trailing, not inner.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.trimboth(trimchars = " ")</code></p></td><td><p>Ditto but only leading and trailing, not inner.</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;␣␣a1␣␣b2␣c3␣␣&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">trimboth</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;a1␣␣b2␣c3&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;␣␣a1␣␣b2␣c3␣␣&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">trimboth</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;a1␣␣b2␣c3&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">trimboth</span><span class="p">(</span><span class="s">&quot;␣␣a1␣␣b2␣c3␣␣&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">trimboth</span><span class="p">(</span><span class="s">&quot;␣␣a1␣␣b2␣c3␣␣&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.first()</td><td><p>Get the first char of a string.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.first()</code></p></td><td><p>Get the first char of a string.</p>
</p>
<p><em>return:</em> A char, or "" if empty.</p>
<p><em>Returns:</em> A char, or "" if empty.
<p>Equivalent to var.substr(1,length) or var[1, length] in Pick OS</p>
</p>
<p>
Equivalent to var.substr(1,length) or var[1, length] in Pick OS
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">first</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;a&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">first</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;a&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">first</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">first</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.last()</td><td><p>Get the last char of a string.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.last()</code></p></td><td><p>Get the last char of a string.</p>
</p>
<p><em>return:</em> A char, or "" if empty.</p>
<p><em>Returns:</em> A char, or "" if empty.
<p>Equivalent to var.substr(-1, 1) or var[-1, 1] in Pick OS</p>
</p>
<p>
Equivalent to var.substr(-1, 1) or var[-1, 1] in Pick OS
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">last</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;c&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">last</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;c&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">last</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">last</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.first(length)</td><td><p>Get the first n chars of a source string.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.first(length)</code></p></td><td><p>Get the first n chars of a source string.</p>
</p>
<p><em>length:</em> The number of chars (bytes) to get.</p>
<p><em>length:</em> The number of chars (bytes) to get.
<p><em>return:</em> A string of up to n chars.</p>
</p>
<p>Equivalent to var.substr(1, length) or var[1, length] in Pick OS</p>
<p><em>Returns:</em> A string of up to n chars.
<p>
</p>
Equivalent to var.substr(1, length) or var[1, length] in Pick OS
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">first</span><span class="p">(</span><span class="mi">2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;ab&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">first</span><span class="p">(</span><span class="mi">2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;ab&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">first</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">first</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.last(length)</td><td><p>Extract up to length trailing chars
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.last(length)</code></p></td><td><p>Extract up to length trailing chars</p>
</p>
<p>Equivalent to var.substr(-length, length) or var[-length, length] in Pick OS</p>
Equivalent to var.substr(-length, length) or var[-length, length] in Pick OS
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">last</span><span class="p">(</span><span class="mi">2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;bc&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">last</span><span class="p">(</span><span class="mi">2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;bc&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">last</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">last</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.cut(length)</td><td><p>Remove n chars (bytes) from the source string.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.cut(length)</code></p></td><td><p>Remove n chars (bytes) from the source string.</p>
</p>
<p><em>length:</em> Positive to remove first n chars or negative to remove the last n chars.</p>
<p><em>length:</em> Positive to remove first n chars or negative to remove the last n chars.
<p>If the absolute value of length is &gt;= the number of chars in the source string then all chars will be removed.</p>
</p>
<p>Equivalent to var.substr(length) or var[1, length] = "" in Pick OS</p>
<p>If the absolute value of length is >= the number of chars in the source string then all chars will be removed.
<p>
</p>
Equivalent to var.substr(length) or var[1, length] = "" in Pick OS
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abcd&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">cut</span><span class="p">(</span><span class="mi">2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;cd&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abcd&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">cut</span><span class="p">(</span><span class="mi">2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;cd&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">cut</span><span class="p">(</span><span class="s">&quot;abcd&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">cut</span><span class="p">(</span><span class="s">&quot;abcd&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.paste(pos1, length, replacestr)</td><td><p>Insert a substr at an given position after removing a given number of chars.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.paste(pos1, length, replacestr)</code></p></td><td><p>Insert a substr at an given position after removing a given number of chars.</p>
</p>
<p><em>pos1:</em> </p>
 
<dl>
<p><em>pos1:</em> 0 or 1 : Remove length chars from the beginning and insert at the beginning.
<dt>0 or 1</dt><dd>Remove length chars from the beginning and insert at the beginning.</dd>
</p>
<dt>   -1</dt><dd>Insert on or before the last char after removing up to length chars starting with the last char.</dd>
<p><em>pos1:</em> > than the length of the source string. Insert after the last char.
<dt>   -2</dt><dd>Ditto on or before the penultimate char.</dd>
</p>
<dt>&gt; strlen</dt><dd>If pos1 &gt; length of the source string, insert after the last char.</dd>
<p><em>pos1:</em> -1 : Remove up to length chars before inserting.Insert on or before the last char.
</dl>
</p>
<p>Equivalent to var[pos1, length] = substr in Pick OS</p>
<p><em>pos1:</em> -2 : Insert on or before the penultimate char.
<p>
</p>
Equivalent to var[pos1, length] = substr in Pick OS
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abcd&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">paste</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;XYZ&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;aXYZd&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abcd&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">paste</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;XYZ&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;aXYZd&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">paste</span><span class="p">(</span><span class="s">&quot;abcd&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;XYZ&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">paste</span><span class="p">(</span><span class="s">&quot;abcd&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;XYZ&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.paste(pos1, insertstr)</td><td><p>Insert text at char position without overwriting any following chars
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.paste(pos1, insertstr)</code></p></td><td><p>Insert text at char position without overwriting any following chars</p>
</p>
<p>Equivalent to var[pos1, 0] = substr in Pick OS</p>
Equivalent to var[pos1, 0] = substr in Pick OS
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abcd&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">paste</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;XYZ&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;aXYZbcd&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abcd&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">paste</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;XYZ&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;aXYZbcd&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">paste</span><span class="p">(</span><span class="s">&quot;abcd&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;XYZ&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">paste</span><span class="p">(</span><span class="s">&quot;abcd&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;XYZ&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.prefix(insertstr)</td><td><p>Insert text at the beginning
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.prefix(insertstr)</code></p></td><td><p>Insert text at the beginning</p>
</p>
<p>Equivalent to var[0, 0] = substr in Pick OS</p>
Equivalent to var[0, 0] = substr in Pick OS
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">prefix</span><span class="p">(</span><span class="s">&quot;XYZ&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;XYZabc&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">prefix</span><span class="p">(</span><span class="s">&quot;XYZ&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;XYZabc&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">prefix</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;XYZ&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">prefix</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;XYZ&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.append(appendable, ...)</td><td>Append anything at the end of a string
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.append(appendable, ...)</code></p></td><td><p>Append anything at the end of a string.</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">append</span><span class="p">(</span><span class="s">&quot; is &quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">10</span><span class="p">,</span><span class="w"> </span><span class="s">&quot; ok&quot;</span><span class="p">,</span><span class="w"> </span><span class="sc">&#39;.&#39;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;abc is 10 ok.&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">append</span><span class="p">(</span><span class="s">&quot; is &quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">10</span><span class="p">,</span><span class="w"> </span><span class="s">&quot; ok&quot;</span><span class="p">,</span><span class="w"> </span><span class="sc">&#39;.&#39;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;abc is 10 ok.&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">append</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot; is &quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">10</span><span class="p">,</span><span class="w"> </span><span class="s">&quot; ok&quot;</span><span class="p">,</span><span class="w"> </span><span class="sc">&#39;.&#39;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">append</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot; is &quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">10</span><span class="p">,</span><span class="w"> </span><span class="s">&quot; ok&quot;</span><span class="p">,</span><span class="w"> </span><span class="sc">&#39;.&#39;</span><span class="p">);</span>
</pre></div></td></tr>
</pre></div>
<tr><td>var=</td><td>strvar.pop()</td><td><p>Remove one trailing char.
</p>
</p>
Equivalent to var[-1, 1] = "" in Pick OS
</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.pop()</code></p></td><td><p>Remove one trailing char.</p>
<p>Equivalent to var[-1, 1] = "" in Pick OS</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">pop</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;ab&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">pop</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;ab&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">pop</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">pop</span><span class="p">(</span><span class="s">&quot;abc&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.field(delimiter, fieldnx = 1, nfieldsx = 1)</td><td><p>Copies one or more consecutive fields from a string given a delimiter
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.field(delimiter, fieldnx = 1, nfieldsx = 1)</code></p></td><td><p>Copy one or more consecutive fields from a string.</p>
</p>
<p><em>delimiter:</em> A Unicode character.</p>
<p><em>delimiter:</em> A Unicode character.
<p><em>fieldno:</em> The first field is 1, the last field is -1.</p>
</p>
<p><em>return:</em> A substring</p>
<p><em>fieldno:</em> The first field is 1, the last field is -1.
<p>
</p>
<em>Returns:</em> A substring
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aa*bb*cc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">field</span><span class="p">(</span><span class="s">&quot;*&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;bb&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aa*bb*cc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">field</span><span class="p">(</span><span class="s">&quot;*&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;bb&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">field</span><span class="p">(</span><span class="s">&quot;aa*bb*cc&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;*&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">field</span><span class="p">(</span><span class="s">&quot;aa*bb*cc&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;*&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aa*bb*cc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">field</span><span class="p">(</span><span class="s">&quot;*&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">-1</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;cc&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aa*bb*cc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">field</span><span class="p">(</span><span class="s">&quot;*&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">-1</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;cc&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">field</span><span class="p">(</span><span class="s">&quot;aa*bb*cc&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;*&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">-1</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">field</span><span class="p">(</span><span class="s">&quot;aa*bb*cc&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;*&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">-1</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.field2(separator, fieldno, nfields = 1)</code></p></td><td>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.field2(separator, fieldno, nfields = 1)</td><td></td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.fieldstore(separator, fieldno, nfields, replacement)</code></p></td><td><p>fieldstore() replaces, inserts or deletes subfields in a string.</p>
<tr><td>var=</td><td>strvar.fieldstore(separator, fieldno, nfields, replacement)</td><td><p>fieldstore() replaces, inserts or deletes subfields in a string.
<p><em>fieldno:</em> The field number to replace or, if not 1, the field number to start at. Negative fieldno counts backwards from the last field.</p>
</p>
<p><em>nfields:</em> The number of fields to replace or, if negative, the number of fields to delete first. Can be 0 to cause simple insertion of fields.</p>
<p><em>fieldno:</em> The field number to replace or, if not 1, the field number to start at. Negative fieldno counts backwards from the last field.
<p><em>replacement:</em> A string that is the replacement field or fields.</p>
</p>
<p><em>return:</em> A modified copy of the original string.</p>
<p><em>nfields:</em> The number of fields to replace or, if negative, the number of fields to delete first. Can be 0 to cause simple insertion of fields.
<p>There is no way to simply delete n fields because the replacement argument cannot be omitted, however one can achieve the same result by replacing n+1 fields with the n+1th field.</p>
</p>
<p></p>
<p><em>replacement:</em> A string that is the replacement field or fields.
<p>The replacement can contain multiple fields itself. If replacing n fields and the replacement contains &lt; n fields then the remaining fields become "". Conversely, if the replacement contains more fields than are required, they are discarded.</p>
</p>
<p>
<p><em>Returns:</em> A modified copy of the original string.
</p>
<p>There is no way to simply delete n fields because the replacement argument cannot be omitted, however one can achieve the same result by replacing n+1 fields with the n+1th field.
</p>
 
The replacement can contain multiple fields itself. If replacing n fields and the replacement contains < n fields then the remaining fields become "". Conversely, if the replacement contains more fields than are required, they are discarded.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aa,bb,cc,dd,ee&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">fieldstore</span><span class="p">(</span><span class="s">&quot;,&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;11,22&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;aa,11,22,,ee&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aa,bb,cc,dd,ee&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">fieldstore</span><span class="p">(</span><span class="s">&quot;,&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;11,22&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;aa,11,22,,ee&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">fieldstore</span><span class="p">(</span><span class="s">&quot;aa,bb,cc,dd,ee&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;,&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;11,22&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">fieldstore</span><span class="p">(</span><span class="s">&quot;aa,bb,cc,dd,ee&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;,&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;11,22&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
If nfields is 0 then insert the replacement field(s) before fieldno
</p>
<p></p>
<p>If nfields is 0 then insert the replacement field(s) before fieldno</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aa,bb,cc,dd,ee&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">fieldstore</span><span class="p">(</span><span class="s">&quot;,&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;11,22&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;aa,11,22,bb,cc,dd,ee&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aa,bb,cc,dd,ee&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">fieldstore</span><span class="p">(</span><span class="s">&quot;,&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;11,22&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;aa,11,22,bb,cc,dd,ee&quot;</span>
</pre></div>
</pre></div>
Line 1,303: Line 1,379:
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aa,bb,cc,dd,ee&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">fieldstore</span><span class="p">(</span><span class="s">&quot;,&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">-2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;11&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;aa,11,dd,ee&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aa,bb,cc,dd,ee&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">fieldstore</span><span class="p">(</span><span class="s">&quot;,&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">-2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;11&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;aa,11,dd,ee&quot;</span>
</pre></div>
</pre></div>
If nfields exceeds the number of fields in the input then additional empty fields are added.
</p>
<p></p>
<p>If nfields exceeds the number of fields in the input then additional empty fields are added.</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aa,bb,cc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">fieldstore</span><span class="p">(</span><span class="s">&quot;,&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">6</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;11&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;aa,bb,cc,,,11,&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aa,bb,cc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">fieldstore</span><span class="p">(</span><span class="s">&quot;,&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">6</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;11&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;aa,bb,cc,,,11,&quot;</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.substr(pos1, length)</td><td><p>substr version 1.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.substr(pos1, length)</code></p></td><td><p>substr version 1.</p>
</p>
<p>Copy a substr of length chars from a given a starting char position.</p>
<p>Copies a substr of length chars from a given a starting char position.
<p><em>return:</em> A substr or "".</p>
</p>
<p><em>pos1:</em> The char position to start at. If negative then start from a position counting backwards from the last char</p>
<p><em>Returns:</em> A substr or "".
<p><em>length:</em> The number of chars to copy. If negative then copy backwards. This reverses the order of the chars in the returned substr.</p>
</p>
<p>Equivalent to var[start, length] in Pick OS</p>
<p><em>pos1:</em> The char position to start at. If negative then start from a position counting backwards from the last char
<p>Not Unicode friendly.</p>
</p>
<p>
<p><em>length:</em> The number of chars to copy. If negative then copy backwards. This reverses the order of the chars in the returned substr.
</p>
<p>Equivalent to var[start, length] in Pick OS
</p>
Not Unicode friendly.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abcd&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">substr</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;bc&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abcd&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">substr</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;bc&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">substr</span><span class="p">(</span><span class="s">&quot;abcd&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">substr</span><span class="p">(</span><span class="s">&quot;abcd&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span>
</pre></div>
</pre></div>
If pos1 is negative then start counting backwards from the last char
</p>
<p></p>
<p>If pos1 is negative then start counting backwards from the last char</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abcd&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">substr</span><span class="p">(</span><span class="mi">-3</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;bc&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abcd&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">substr</span><span class="p">(</span><span class="mi">-3</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;bc&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">substr</span><span class="p">(</span><span class="s">&quot;abcd&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">-3</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">substr</span><span class="p">(</span><span class="s">&quot;abcd&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">-3</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span>
</pre></div>
</pre></div>
If length is negative then work backwards and return chars reversed
</p>
<p></p>
<p>If length is negative then work backwards and return chars reversed</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abcd&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">substr</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="mi">-2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;cb&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abcd&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">substr</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="mi">-2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;cb&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">substr</span><span class="p">(</span><span class="s">&quot;abcd&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="mi">-2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;cb&quot;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">substr</span><span class="p">(</span><span class="s">&quot;abcd&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="mi">-2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;cb&quot;</span>
</pre></div>
</pre></div>
</p>
</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.b(pos1, length)</code></p></td><td><p>Abbreviated alias of substr version 1.</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.b(pos1, length)</td><td>Abbreviated alias of substr version 1.</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.substr(pos1)</code></p></td><td><p>substr version 2.</p>
<tr><td>var=</td><td>strvar.substr(pos1)</td><td><p>substr version 2.
<p>Copy a substr from a given char position up to the end of the source string</p>
</p>
<p><em>return:</em> A substr or "".</p>
<p>Copies a substr from a given char position up to the end of the source string
<p><em>pos1:</em> The char position to start at. If negative then start from a position counting backwards from the last char</p>
</p>
<p>Equivalent to var[pos1, 9999999] in Pick OS</p>
<p><em>Returns:</em> A substr or "".
<p>Partially Unicode friendly but pos1 is in chars.</p>
</p>
<p>
<p><em>pos1:</em> The char position to start at. If negative then start from a position counting backwards from the last char
</p>
<p>Equivalent to var[pos1, 9999999] in Pick OS
</p>
Partially Unicode friendly but pos1 is in chars.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abcd&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">substr</span><span class="p">(</span><span class="mi">2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;bcd&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abcd&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">substr</span><span class="p">(</span><span class="mi">2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;bcd&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">substr</span><span class="p">(</span><span class="s">&quot;abcd&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">substr</span><span class="p">(</span><span class="s">&quot;abcd&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.b(pos1)</code></p></td><td><p>Shorthand alias of substr version 2.</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.b(pos1)</td><td>Shorthand alias of substr version 2.</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.substr(pos1, delimiterchars, out pos2)</code></p></td><td><p>substr version 3.</p>
<tr><td>var=</td><td>strvar.substr(pos1, delimiterchars, out pos2)</td><td><p>substr version 3.
<p>Copy a substr from a given char position up to (but excluding) any one of some given delimiter chars</p>
<p><em>return:</em> A substr or "".</p>
<p><em>pos1:</em> [in] The position of the first char to copy. Negative positions count backwards from the last char of the string.</p>
<p><em>pos2[out]:</em> The position of the next delimiter char, or one char position after the end of the source string if no subsequent delimiter chars are found.</p>
<p><em>COL2:</em> Is a predefined variable that can be used for pos2 instead of declaring a variable.</p>
<p>An empty string may be returned if pos1 [in] points to one of the delimiter chars or points beyond the end of the source string.</p>
<p>Equivalent to var[pos1, ",."] in Pick OS (non-numeric length).</p>
<p>Works with any encoding including UTF8 for the source string but the delimiter chars are bytes.</p>
<p>Add 1 to pos2 to skip over the next delimiter char to copy the next substr</p>
<p>Works with any encoding including UTF8 for the source string but the delimiter chars are bytes.</p>
<p>This function is similar to std::string::find_first_of but that function only returns pos2.</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">pos1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">4</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;12,45 78&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">substr</span><span class="p">(</span><span class="n">pos1</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;, &quot;</span><span class="p">,</span><span class="w"> </span><span class="kc">COL2</span><span class="p">);</span><span class="w">  </span><span class="c1">// v1 -&gt; &quot;45&quot; // COL2 -&gt; 6 // 6 is the position of the next delimiter char found.</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">substr</span><span class="p">(</span><span class="s">&quot;12,45 78&quot;</span><span class="p">,</span><span class="w"> </span><span class="kc">COL2</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;, &quot;</span><span class="p">,</span><span class="w"> </span><span class="kc">COL2</span><span class="p">);</span><span class="w"> </span><span class="c1">// v2 -&gt; &quot;78&quot; // COL2 -&gt; 9 // 9 is one after the end of the string meaning that none of the delimiter chars were found.</span>
</pre></div>
</p>
</p>
<p>Copies a substr from a given char position up to (but excluding) any one of some given delimiter chars
</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.b(pos1, delimiterchars, out pos2)</code></p></td><td><p>Shorthand alias of substr version 3.</p>
</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.substr2(io pos1, out delimiterno)</code></p></td><td><p>substr version 4.</p>
<p>Copy a substr from a given char position up to (but excluding) the next field mark char (RM, FM, VM, SM, TM, ST).</p>
<p><em>return:</em> A substr or "".</p>
<p><em>pos1:</em> [in] The position of the first char to copy. Negative positions count backwards from the last char of the string.</p>
<p><em>pos1[out]:</em> The position of the first char of the next substr after whatever field mark char is found, or one char position after the end of the source string if no subsequent field mark char is found.</p>
<p><em>field_mark_no[out]:</em> A number (1-6) indicating which of the standard field mark chars was found, or 0 if not.</p>
<p>An empty string may be returned if the pos1 [in] points to one of the field marks or beyond the end of the source string.</p>
<p>pos1 [out] is correctly positioned to copy the next substr.</p>
<p>Works with any encoding including UTF8. Was called "remove" in Pick OS.</p>
<p>The equivalent in Pick OS was the statement "Remove variable From string At column Setting flag"</p>
<p>This function is valuable for high performance processing of dynamic arrays.</p>
<p>It is notably used in "list" to print parallel columns of mixed combinations of multivalues/subvalues and text marks correctly lined up mv to mv, sv to sv, tm to tm even when particular values, subvalues and text fragments are missing from particular columns.</p>
<p>It is similar to version 3 of substr - substr(pos1, delimiterchars, pos2) except that in this version the delimiter chars are hard coded as the standard field mark chars (RM, FM, VM, SM, TM, ST) and it returns the first char position of the next substr, not the char position of the next field mark char.</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">pos1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">4</span><span class="p">,</span><span class="w"> </span><span class="n">field_mark_no</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;12^45^78&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">substr2</span><span class="p">(</span><span class="n">pos1</span><span class="p">,</span><span class="w"> </span><span class="n">field_mark_no</span><span class="p">);</span><span class="w">  </span><span class="c1">// &quot;45&quot; // pos1 -&gt; 7 // field_mark_no -&gt; 2 // field_mark_no 2 means that a FM was found.</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">substr2</span><span class="p">(</span><span class="s">&quot;12^45^78&quot;</span><span class="kt">_var</span><span class="p">,</span><span class="w"> </span><span class="n">pos1</span><span class="p">,</span><span class="w"> </span><span class="n">field_mark_no</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;78&quot; // pos1 -&gt; 9 // field_mark_no -&gt; 0 // field_mark_no 0 means that none of the standard field marks were found.</span>
</pre></div>
</p>
</p>
<p><em>Returns:</em> A substr or "".
</p>
<p><em>pos1:</em> [in] The position of the first char to copy. Negative positions count backwards from the last char of the string.
</p>
<p><em>pos2:</em> [out] The position of the next delimiter char, or one char position after the end of the source string if no subsequent delimiter chars are found.
</p>
<p><em>COL2:</em> is a predefined variable that can be used for pos2 instead of declaring a variable.
</p>
<p>An empty string may be returned if pos1 [in] points to one of the delimiter chars or points beyond the end of the source string.
</p>
<p>Equivalent to var[pos1, ",."] in Pick OS (non-numeric length).
</p>
<p>Works with any encoding including UTF8 for the source string but the delimiter chars are bytes.
</p>
<p>Add 1 to pos2 to skip over the next delimiter char to copy the next substr
</p>
<p>Works with any encoding including UTF8 for the source string but the delimiter chars are bytes.
</p>
This function is similar to std::string::find_first_of but that function only returns pos2.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">pos1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">4</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;12,45 78&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">substr</span><span class="p">(</span><span class="n">pos1</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;, &quot;</span><span class="p">,</span><span class="w"> </span><span class="n">COL2</span><span class="p">);</span><span class="w">  </span><span class="c1">// v1 -&gt; &quot;45&quot; // COL2 -&gt; 6 // 6 is the position of the next delimiter char found.</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">substr</span><span class="p">(</span><span class="s">&quot;12,45 78&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">COL2</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;, &quot;</span><span class="p">,</span><span class="w"> </span><span class="n">COL2</span><span class="p">);</span><span class="w"> </span><span class="c1">// v2 -&gt; &quot;78&quot; // COL2 -&gt; 9 // 9 is one after the end of the string meaning that none of the delimiter chars were found.</span>
</pre></div>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.b(pos1, delimiterchars, out pos2)</td><td>Shorthand alias of substr version 3.</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.b2(io pos1, out field_mark_no)</code></p></td><td><p>Shorthand alias of substr version 4.</p>
<tr><td>var=</td><td>strvar.substr2(io pos1, out delimiterno)</td><td><p>substr version 4.
</p>
<p>Copies a substr from a given char position up to (but excluding) the next field mark char (RM, FM, VM, SM, TM, ST).
</p>
<p><em>Returns:</em> A substr or "".
</p>
<p><em>pos1:</em> [in] The position of the first char to copy. Negative positions count backwards from the last char of the string.
</p>
<p><em>pos1:</em> [out] The position of the first char of the next substr after whatever field mark char is found, or one char position after the end of the source string if no subsequent field mark char is found.
</p>
<p><em>field_mark_no:</em> [out] A number (1-6) indicating which of the standard field mark chars was found, or 0 if not.
</p>
<p>An empty string may be returned if the pos1 [in] points to one of the field marks or beyond the end of the source string.
</p>
<p>pos1 [out] is correctly positioned to copy the next substr.
</p>
<p>Works with any encoding including UTF8. Was called "remove" in Pick OS.
</p>
<p>The equivalent in Pick OS was the statement "Remove variable From string At column Setting flag"
</p>
<p>...
</p>
<p>This function is valuable for high performance processing of dynamic arrays.
</p>
<p>It is notably used in "list" to print parallel columns of mixed combinations of multivalues/subvalues and text marks correctly lined up mv to mv, sv to sv, tm to tm even when particular values, subvalues and text fragments are missing from particular columns.
</p>
It is similar to version 3 of substr - substr(pos1, delimiterchars, pos2) except that in this version the delimiter chars are hard coded as the standard field mark chars (RM, FM, VM, SM, TM, ST) and it returns the first char position of the next substr, not the char position of the next field mark char.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">pos1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">4</span><span class="p">,</span><span class="w"> </span><span class="n">field_mark_no</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;12^45^78&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">substr2</span><span class="p">(</span><span class="n">pos1</span><span class="p">,</span><span class="w"> </span><span class="n">field_mark_no</span><span class="p">);</span><span class="w">  </span><span class="c1">// &quot;45&quot; // pos1 -&gt; 7 // field_mark_no -&gt; 2 // field_mark_no 2 means that a FM was found.</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">substr2</span><span class="p">(</span><span class="s">&quot;12^45^78&quot;</span><span class="kt">_var</span><span class="p">,</span><span class="w"> </span><span class="n">pos1</span><span class="p">,</span><span class="w"> </span><span class="n">field_mark_no</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;78&quot; // pos1 -&gt; 9 // field_mark_no -&gt; 0 // field_mark_no 0 means that none of the standard field marks were found.</span>
</pre></div>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.b2(io pos1, out field_mark_no)</td><td>Shorthand alias of substr version 4.</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.convert(fromchars, tochars)</code></p></td><td><p>Convert or delete chars one for one to other chars</p>
<tr><td>var=</td><td>strvar.convert(fromchars, tochars)</td><td><p>Convert or delete chars one for one to other chars
<p><em>from_chars:</em> chars to convert. If longer than to_chars then delete those characters instead of converting them.</p>
</p>
<p><em>to_chars:</em> chars to convert to</p>
<p><em>from_chars:</em> chars to convert. If longer than to_chars then delete those characters instead of converting them.
<p>Not UTF8 compatible.</p>
</p>
<p>
<p><em>to_chars:</em> chars to convert to
</p>
Not UTF8 compatible.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abcde&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">convert</span><span class="p">(</span><span class="s">&quot;aZd&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;XY&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;Xbce&quot; // a is replaced and d is removed</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abcde&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">convert</span><span class="p">(</span><span class="s">&quot;aZd&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;XY&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;Xbce&quot; // a is replaced and d is removed</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">convert</span><span class="p">(</span><span class="s">&quot;abcde&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;aZd&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;XY&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">convert</span><span class="p">(</span><span class="s">&quot;abcde&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;aZd&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;XY&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.textconvert(fromchars, tochars)</td><td>Ditto for Unicode code points.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.textconvert(fromchars, tochars)</code></p></td><td><p>Ditto for Unicode code points.</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;a🤡b😀c🌍d&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">textconvert</span><span class="p">(</span><span class="s">&quot;🤡😀&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;👋&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;a👋bc🌍d&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;a🤡b😀c🌍d&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">textconvert</span><span class="p">(</span><span class="s">&quot;🤡😀&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;👋&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;a👋bc🌍d&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">textconvert</span><span class="p">(</span><span class="s">&quot;a🤡b😀c🌍d&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;🤡😀&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;👋&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">textconvert</span><span class="p">(</span><span class="s">&quot;a🤡b😀c🌍d&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;🤡😀&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;👋&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.replace(fromstr, tostr)</td><td><p>Replace all occurrences of one substr with another.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.replace(fromstr, tostr)</code></p></td><td><p>Replace all occurrences of one substr with another.</p>
</p>
<p>Case sensitive.</p>
Case sensitive.
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Abc.Abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">replace</span><span class="p">(</span><span class="s">&quot;bc&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;AX.AX&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Abc.Abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">replace</span><span class="p">(</span><span class="s">&quot;bc&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;AX.AX&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">replace</span><span class="p">(</span><span class="s">&quot;Abc Abc&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;bc&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">replace</span><span class="p">(</span><span class="s">&quot;Abc Abc&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;bc&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.replace(regex, replacement_str)</td><td><p>Replace substrings using a regular expression.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.replace(regex, replacement_str)</code></p></td><td><p>Replace substrings using a regular expression.</p>
</p>
<p><em>regex:</em> A regular expression created by rex() or _rex.</p>
<p><em>regex:</em> A regular expression created by rex() or _rex.
<p><em>replacement_str:</em> A literal to replace all matched substrings.</p>
</p>
<p>The replacement string can include the following special replacement patterns:</p>
<p><em>replacement_str:</em> A literal to replace all matched substrings.
<p>Pattern</p>
</p>
<dl>
<p>The replacement string can include the following special replacement patterns:
<dt>$$</dt><dd>Inserts a "$".</dd>
</p>
<dt>$&amp;</dt><dd>Inserts the matched substring. Equivalent to $0.</dd>
<p>Pattern Inserts
<dt>$`</dt><dd>Inserts the portion of the string that precedes the matched substring.</dd>
</p>
<dt>$'</dt><dd>Inserts the portion of the string that follows the matched substring.</dd>
<p>* $$     Inserts a "$".
<dt>$n</dt><dd>Inserts the nth (1-indexed) capturing group where n is a positive integer less than 100.</dd>
</p>
</dl>
<p>* $&     Inserts the matched substring. Equivalent to $0.
<p>
</p>
<p>* $`     Inserts the portion of the string that precedes the matched substring.
</p>
<p>* $'     Inserts the portion of the string that follows the matched substring.
</p>
* $n     Inserts the nth (1-indexed) capturing group where n is a positive integer less than 100.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;A a B b&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">replace</span><span class="p">(</span><span class="s">&quot;[A-Z]&quot;</span><span class="kt">_rex</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;&#39;$0&#39;&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;&#39;A&#39; a &#39;B&#39; b&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;A a B b&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">replace</span><span class="p">(</span><span class="s">&quot;[A-Z]&quot;</span><span class="kt">_rex</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;&#39;$0&#39;&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;&#39;A&#39; a &#39;B&#39; b&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">replace</span><span class="p">(</span><span class="s">&quot;A a B b&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;[A-Z]&quot;</span><span class="kt">_rex</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;&#39;$0&#39;&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">replace</span><span class="p">(</span><span class="s">&quot;A a B b&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;[A-Z]&quot;</span><span class="kt">_rex</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;&#39;$0&#39;&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.replace(regex, ReplacementFunction auto repl_func)</td><td><p>Replace substrings using a regular expression and a custom function.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.replace(regex, ReplacementFunction auto repl_func)</code></p></td><td><p>Replace substrings using a regular expression and a custom function.</p>
</p>
<p>Allow complex string conversions.</p>
<p>Allows complex string conversions.
<p><em>repl_func:</em> A function with arguments (in match_str) that returns a var to replace match_str. May be an inline anonymous lambda function (capturing or non-capturing).</p>
</p>
<p>e.g. [](auto match_str) {return match_str;} // Does nothing.</p>
<p><em>repl_func:</em> A function with arguments (in match_str) that returns a var to replace match_str. May be an inline anonymous lambda function (capturing or non-capturing).
<p><em>match_str:</em> Text of a single match. If regex groups are used, match_str.f(1, 1) is the whole match, match_str.f(1, 2) is the first group, etc.</p>
</p>
<p>
<p>e.g. [](auto match_str) {return match_str;} // Does nothing.
</p>
<em>match_str:</em> Text of a single match. If regex groups are used, match_str.f(1, 1) is the whole match, match_str.f(1, 2) is the first group, etc.
<div class="highlight light"><pre><span class="c1">// Decode hex escape codes.</span>
<div class="highlight light"><pre><span class="c1">// Decode hex escape codes.</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="sa">R</span><span class="s">&quot;</span><span class="dl">(</span><span class="s">--\0x3B--\0x2F--</span><span class="dl">)</span><span class="s">&quot;</span><span class="p">;</span><span class="w">                                </span><span class="c1">// Hex escape codes.</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="sa">R</span><span class="s">&quot;</span><span class="dl">(</span><span class="s">--\0x3B--\0x2F--</span><span class="dl">)</span><span class="s">&quot;</span><span class="p">;</span><span class="w">                                </span><span class="c1">// Hex escape codes.</span>
<span class="n">v1</span><span class="p">.</span><span class="nf">replacer</span><span class="p">(</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">replace</span><span class="p">(</span>
<span class="w">    </span><span class="sa">R</span><span class="s">&quot;</span><span class="dl">(</span><span class="s">\\0x[0-9a-fA-F]{2,2}</span><span class="dl">)</span><span class="s">&quot;</span><span class="kt">_rex</span><span class="p">,</span><span class="w">                              </span><span class="c1">// Finds \0xFF.</span>
<span class="w">    </span><span class="sa">R</span><span class="s">&quot;</span><span class="dl">(</span><span class="s">\\0x[0-9a-fA-F]{2,2}</span><span class="dl">)</span><span class="s">&quot;</span><span class="kt">_rex</span><span class="p">,</span><span class="w">                              </span><span class="c1">// Find \0xFF.</span>
<span class="w">    </span><span class="p">[](</span><span class="k">auto</span><span class="w"> </span><span class="n">match_str</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="kr">return</span><span class="w"> </span><span class="n">match_str</span><span class="p">.</span><span class="nf">cut</span><span class="p">(</span><span class="mi">3</span><span class="p">).</span><span class="nf">iconv</span><span class="p">(</span><span class="s">&quot;HEX&quot;</span><span class="p">);}</span><span class="w">  </span><span class="c1">// Decodes to a char.</span>
<span class="w">    </span><span class="p">[](</span><span class="k">auto</span><span class="w"> </span><span class="n">match_str</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="kr">return</span><span class="w"> </span><span class="n">match_str</span><span class="p">.</span><span class="nf">cut</span><span class="p">(</span><span class="mi">3</span><span class="p">).</span><span class="nf">iconv</span><span class="p">(</span><span class="s">&quot;HEX&quot;</span><span class="p">);}</span><span class="w">  </span><span class="c1">// Decode to a char.</span>
<span class="p">);</span>
<span class="p">);</span>
<span class="n">assert</span><span class="p">(</span><span class="n">v1</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="s">&quot;--;--/--&quot;</span><span class="p">);</span>
<span class="n">assert</span><span class="p">(</span><span class="n">v2</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="s">&quot;--;--/--&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
<p>
<div class="highlight light"><pre><span class="c1">// Reformat dates using groups.</span>
<div class="highlight light"><pre><span class="c1">// Reformat dates using groups.</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Date: 03-15-2025&quot;</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v3</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Date: 03-15-2025&quot;</span><span class="p">;</span>
<span class="n">v2</span><span class="p">.</span><span class="nf">replacer</span><span class="p">(</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v4</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v3</span><span class="p">.</span><span class="nf">replace</span><span class="p">(</span>
<span class="w">    </span><span class="sa">R</span><span class="s">&quot;</span><span class="dl">(</span><span class="s">(\d{2})-(\d{2})-(\d{4})</span><span class="dl">)</span><span class="s">&quot;</span><span class="kt">_rex</span><span class="p">,</span>
<span class="w">    </span><span class="sa">R</span><span class="s">&quot;</span><span class="dl">(</span><span class="s">(\d{2})-(\d{2})-(\d{4})</span><span class="dl">)</span><span class="s">&quot;</span><span class="kt">_rex</span><span class="p">,</span>
<span class="w">    </span><span class="p">[](</span><span class="k">auto</span><span class="w"> </span><span class="n">match_str</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="kr">return</span><span class="w"> </span><span class="n">match_str</span><span class="p">.</span><span class="nf">f</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">4</span><span class="p">)</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="s">&quot;-&quot;</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="n">match_str</span><span class="p">.</span><span class="nf">f</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">)</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="s">&quot;-&quot;</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="n">match_str</span><span class="p">.</span><span class="nf">f</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">);}</span>
<span class="w">    </span><span class="p">[](</span><span class="k">auto</span><span class="w"> </span><span class="n">match_str</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="kr">return</span><span class="w"> </span><span class="n">match_str</span><span class="p">.</span><span class="nf">f</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">4</span><span class="p">)</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="s">&quot;-&quot;</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="n">match_str</span><span class="p">.</span><span class="nf">f</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">)</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="s">&quot;-&quot;</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="n">match_str</span><span class="p">.</span><span class="nf">f</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">);}</span>
<span class="p">);</span>
<span class="p">);</span>
<span class="n">assert</span><span class="p">(</span><span class="n">v2</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="s">&quot;Date: 2025-03-15&quot;</span><span class="p">);</span>
<span class="n">assert</span><span class="p">(</span><span class="n">v4</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="s">&quot;Date: 2025-03-15&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.unique()</td><td>Remove duplicate fields in an FM or VM etc. separated list
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.unique()</code></p></td><td><p>Remove duplicate fields, values or subvalues.</p>
<p>From a dynamic array.</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;a1^b2^a1^c2&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">unique</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;a1^b2^c2&quot;_var</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;a1^b2^a1^c2&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">unique</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;a1^b2^c2&quot;_var</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">unique</span><span class="p">(</span><span class="s">&quot;a1^b2^a1^c2&quot;</span><span class="kt">_var</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">unique</span><span class="p">(</span><span class="s">&quot;a1^b2^a1^c2&quot;</span><span class="kt">_var</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.sort(delimiter = FM)</td><td><p>Reorder fields in an FM or VM etc. separated list in ascending order
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.sort(delimiter = FM)</code></p></td><td><p>Reorder fields, values or subvalues.</p>
</p>
<p>In a dynamic array.</p>
Numeric data:
<p>Numeric data:
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;20^10^2^1^1.1&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">sort</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;1^1.1^2^10^20&quot;_var</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;20^10^2^1^1.1&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">sort</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;1^1.1^2^10^20&quot;_var</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">sort</span><span class="p">(</span><span class="s">&quot;20^10^2^1^1.1&quot;</span><span class="kt">_var</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">sort</span><span class="p">(</span><span class="s">&quot;20^10^2^1^1.1&quot;</span><span class="kt">_var</span><span class="p">);</span>
</pre></div>
</pre></div>
Alphabetic data:
</p>
<p>Alphabetic data:
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;b1^a1^c20^c10^c2^c1^b2&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">sort</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;a1^b1^b2^c1^c10^c2^c20&quot;_var</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;b1^a1^c20^c10^c2^c1^b2&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">sort</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;a1^b1^b2^c1^c10^c2^c20&quot;_var</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">sort</span><span class="p">(</span><span class="s">&quot;b1^a1^c20^c10^c2^c1^b2&quot;</span><span class="kt">_var</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">sort</span><span class="p">(</span><span class="s">&quot;b1^a1^c20^c10^c2^c1^b2&quot;</span><span class="kt">_var</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.reverse(delimiter = FM)</td><td>Reorder fields in an FM or VM etc. separated list in descending order
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.reverse(delimiter = FM)</code></p></td><td><p>Reorder fields in an FM or VM etc. separated list in descending order</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;20^10^2^1^1.1&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">reverse</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;1.1^1^2^10^20&quot;_var</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;20^10^2^1^1.1&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">reverse</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;1.1^1^2^10^20&quot;_var</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">reverse</span><span class="p">(</span><span class="s">&quot;20^10^2^1^1.1&quot;</span><span class="kt">_var</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">reverse</span><span class="p">(</span><span class="s">&quot;20^10^2^1^1.1&quot;</span><span class="kt">_var</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.shuffle(delimiter = FM)</td><td>Randomise the order of fields in an FM, VM separated list
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.randomize(delimiter = FM)</code></p></td><td><p>Randomise the order of fields in an FM, VM separated list</p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;20^10^2^1^1.1&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">shuffle</span><span class="p">();</span><span class="w"> </span><span class="c1">/// e.g. &quot;2^1^20^1.1^10&quot; (random order depending on initrand())</span>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;20^10^2^1^1.1&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">randomize</span><span class="p">();</span><span class="w"> </span><span class="c1">/// e.g. &quot;2^1^20^1.1^10&quot; (random order depending on initrand())</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">shuffle</span><span class="p">(</span><span class="s">&quot;20^10^2^1^1.1&quot;</span><span class="kt">_var</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">randomize</span><span class="p">(</span><span class="s">&quot;20^10^2^1^1.1&quot;</span><span class="kt">_var</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.parse(char sepchar = ' ')</td><td><p>Split a delimited string with embedded quotes into a dynamic array.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.parse(char sepchar = ' ')</code></p></td><td><p>Split a delimited string into a dynamic array.</p>
</p>
<p>Replace separator chars with FM chars except inside double or single quotes and ignoring escaped quotes \" \'</p>
<p>Can be used to process CSV data.
<p><em>return:</em> A dynamic array</p>
</p>
<p>Can be used to process CSV data.</p>
Replaces separator chars with FM chars except inside double or single quotes and ignoring escaped quotes &bsol;" &bsol;'
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc,</span><span class="se">\&quot;</span><span class="s">def,</span><span class="se">\&quot;</span><span class="s">123</span><span class="se">\&quot;</span><span class="s"> fgh</span><span class="se">\&quot;</span><span class="s">,12.34&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">parse</span><span class="p">(</span><span class="sc">&#39;,&#39;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;abc^\&quot;def,\&quot;123\&quot; fgh\&quot;^12.34&quot;_var</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc,</span><span class="se">\&quot;</span><span class="s">def,</span><span class="se">\&quot;</span><span class="s">123</span><span class="se">\&quot;</span><span class="s"> fgh</span><span class="se">\&quot;</span><span class="s">,12.34&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">parse</span><span class="p">(</span><span class="sc">&#39;,&#39;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;abc^\&quot;def,\&quot;123\&quot; fgh\&quot;^12.34&quot;_var</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">parse</span><span class="p">(</span><span class="s">&quot;abc,</span><span class="se">\&quot;</span><span class="s">def,</span><span class="se">\&quot;</span><span class="s">123</span><span class="se">\&quot;</span><span class="s"> fgh</span><span class="se">\&quot;</span><span class="s">,12.34&quot;</span><span class="p">,</span><span class="w"> </span><span class="sc">&#39;,&#39;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">parse</span><span class="p">(</span><span class="s">&quot;abc,</span><span class="se">\&quot;</span><span class="s">def,</span><span class="se">\&quot;</span><span class="s">123</span><span class="se">\&quot;</span><span class="s"> fgh</span><span class="se">\&quot;</span><span class="s">,12.34&quot;</span><span class="p">,</span><span class="w"> </span><span class="sc">&#39;,&#39;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>dim=</td><td>strvar.split(delimiter = FM)</td><td><p>Split a delimited string into a dim array.
<tr><td><p><code>dim=</code></p></td><td><p><code>strvar.split(delimiter = FM)</code></p></td><td><p>Split a delimited string into a dim array.</p>
</p>
<p><em>Delimiter:</em> Can be multibyte Unicode.</p>
<p>The delimiter can be multibyte Unicode.
<p><em>return:</em> A dim array.</p>
</p>
<p>
<em>Returns:</em> A dim array.
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="n">d1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;a^b^c&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">split</span><span class="p">();</span><span class="w"> </span><span class="c1">// A dimensioned array with three elements (vars)</span>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="n">d1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;a^b^c&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">split</span><span class="p">();</span><span class="w"> </span><span class="c1">// A dimensioned array with three elements (vars)</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">dim</span><span class="w"> </span><span class="n">d2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">split</span><span class="p">(</span><span class="s">&quot;a^b^c&quot;</span><span class="kt">_var</span><span class="p">);</span>
<span class="nf">dim</span><span class="w"> </span><span class="n">d2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">split</span><span class="p">(</span><span class="s">&quot;a^b^c&quot;</span><span class="kt">_var</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.paste(pos1, length, replacestr)</code></p></td><td>
</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.fieldstore(delimiter, fieldno, nfields, replacement)</code></p></td><td>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.fieldstore(delimiter, fieldno, nfields, replacement)</td><td></td></tr>
</table>
</table>
<h5 id=String_Mutation_-_Standalone_Commands>String Mutation - Standalone Commands</h5>
<h5 id=String_Mutation_-_Standalone_Commands>String Mutation - Standalone Commands</h5>
Line 1,550: Line 1,622:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td></td><td>strvar.ucaser()</td><td><p>Upper case
<tr><td><p><code></code></p></td><td><p><code>strvar.ucaser()</code></p></td><td><p>To upper case</p>
</p>
<p>All string mutators follow the same pattern as ucaser. See the non-mutating functions for details.</p>
All string mutators follow the same pattern as ucaser.<br>See the non-mutating functions for details.
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="p">;</span>
<span class="n">v1</span><span class="p">.</span><span class="nf">ucaser</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;ABC&quot;</span>
<span class="n">v1</span><span class="p">.</span><span class="nf">ucaser</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;ABC&quot;</span>
Line 1,558: Line 1,630:
<span class="nf">ucaser</span><span class="p">(</span><span class="n">v1</span><span class="p">);</span>
<span class="nf">ucaser</span><span class="p">(</span><span class="n">v1</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.lcaser()</code></p></td><td>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.tcaser()</code></p></td><td>
</td></tr>
</td></tr>
<tr><td></td><td>strvar.lcaser()</td><td></td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.fcaser()</code></p></td><td>
<tr><td></td><td>strvar.tcaser()</td><td></td></tr>
</td></tr>
<tr><td></td><td>strvar.fcaser()</td><td></td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.normalizer()</code></p></td><td>
<tr><td></td><td>strvar.normalizer()</td><td></td></tr>
</td></tr>
<tr><td></td><td>strvar.inverter()</td><td></td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.inverter()</code></p></td><td>
<tr><td></td><td>strvar.quoter()</td><td></td></tr>
<tr><td></td><td>strvar.squoter()</td><td></td></tr>
<tr><td></td><td>strvar.unquoter()</td><td></td></tr>
<tr><td></td><td>strvar.lowerer()</td><td></td></tr>
<tr><td></td><td>strvar.raiser()</td><td></td></tr>
<tr><td></td><td>strvar.cropper()</td><td></td></tr>
<tr><td></td><td>strvar.trimmer(trimchars = " ")</td><td></td></tr>
<tr><td></td><td>strvar.trimmerfirst(trimchars = " ")</td><td></td></tr>
<tr><td></td><td>strvar.trimmerlast(trimchars = " ")</td><td></td></tr>
<tr><td></td><td>strvar.trimmerboth(trimchars = " ")</td><td></td></tr>
<tr><td></td><td>strvar.firster()</td><td></td></tr>
<tr><td></td><td>strvar.laster()</td><td></td></tr>
<tr><td></td><td>strvar.firster(length)</td><td></td></tr>
<tr><td></td><td>strvar.laster(length)</td><td></td></tr>
<tr><td></td><td>strvar.cutter(length)</td><td></td></tr>
<tr><td></td><td>strvar.paster(pos1, length, insertstr)</td><td></td></tr>
<tr><td></td><td>strvar.paster(pos1, insertstr)</td><td></td></tr>
<tr><td></td><td>strvar.prefixer(insertstr)</td><td></td></tr>
<tr><td></td><td>strvar.appender(appendable, ...)</td><td></td></tr>
<tr><td></td><td>strvar.popper()</td><td></td></tr>
<tr><td></td><td>strvar.fieldstorer(delimiter, fieldno, nfields, replacement)</td><td></td></tr>
<tr><td></td><td>strvar.substrer(pos1, length)</td><td></td></tr>
<tr><td></td><td>strvar.substrer(pos1)</td><td></td></tr>
<tr><td></td><td>strvar.converter(from_chars, to_chars)</td><td></td></tr>
<tr><td></td><td>strvar.textconverter(from_characters, to_characters)</td><td></td></tr>
<tr><td></td><td>strvar.replacer(regex, tostr)</td><td></td></tr>
<tr><td></td><td>strvar.replacer(regex, ReplacementFunction auto repl_func)</td><td></td></tr>
<tr><td></td><td>strvar.replacer(fromstr, tostr)</td><td></td></tr>
<tr><td></td><td>strvar.uniquer()</td><td></td></tr>
<tr><td></td><td>strvar.sorter(delimiter = FM)</td><td></td></tr>
<tr><td></td><td>strvar.reverser(delimiter = FM)</td><td></td></tr>
<tr><td></td><td>strvar.shuffler(delimiter = FM)</td><td></td></tr>
<tr><td></td><td>strvar.parser(char sepchar = ' ')</td><td></td></tr>
</table>
<h5 id=I/O_Conversion>I/O Conversion</h5>
 
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>var=</td><td>var.oconv(convstr)</td><td><p>Converts internal data to output external display format according to a given conversion code or pattern
</p>
<p>If the internal data is invalid and cannot be converted then most conversions return the ORIGINAL data unconverted
</p>
<p>Throws a runtime error VarNotImplemented if convstr is invalid
</p>
See [[#ICONV/OCONV PATTERNS]]
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mi">30123</span><span class="p">).</span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;D/E&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;21/06/2050&quot;</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">oconv</span><span class="p">(</span><span class="mi">30123</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;D/E&quot;</span><span class="p">);</span>
</pre></div>
</td></tr>
</td></tr>
<tr><td>var=</td><td>var.iconv(convstr)</td><td><p>Converts external data to internal format according to a given conversion code or pattern
<tr><td><p><code></code></p></td><td><p><code>strvar.quoter()</code></p></td><td>
</p>
<p>If the external data is invalid and cannot be converted then most conversions return the EMPTY STRING ""
</p>
<p>Throws a runtime error VarNotImplemented if convstr is invalid
</p>
See [[#ICONV/OCONV PATTERNS]]
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;21 JUN 2050&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">iconv</span><span class="p">(</span><span class="s">&quot;D/E&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// 30123</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">iconv</span><span class="p">(</span><span class="s">&quot;21 JUN 2050&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;D/E&quot;</span><span class="p">);</span>
</pre></div>
</td></tr>
</td></tr>
<tr><td>var=</td><td>var.format(fmt_str, args, ...)</td><td><p>Classic format function in printf style
<tr><td><p><code></code></p></td><td><p><code>strvar.squoter()</code></p></td><td>
</p>
<p>vars can be formatted either with C++ format codes e.g. {:_>8.2f}
</p>
or with exodus oconv codes e.g. {::MD20P|R(_)#8} as in the below example.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mf">12.345</span><span class="p">).</span><span class="nf">format</span><span class="p">(</span><span class="s">&quot;&#39;{:_&gt;8.2f}&#39;&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;&#39;___12.35&#39;&quot;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mf">12.345</span><span class="p">).</span><span class="nf">format</span><span class="p">(</span><span class="s">&quot;&#39;{::MD20P|R(_)#8}&#39;&quot;</span><span class="p">);</span>
<span class="c1">// or</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v3</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">format</span><span class="p">(</span><span class="s">&quot;&#39;{:_&gt;8.2f}&#39;&quot;</span><span class="p">,</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mf">12.345</span><span class="p">));</span><span class="w"> </span><span class="c1">// &quot;&#39;___12.35&#39;&quot;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v4</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">format</span><span class="p">(</span><span class="s">&quot;&#39;{::MD20P|R(_)#8}&#39;&quot;</span><span class="p">,</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mf">12.345</span><span class="p">));</span>
</pre></div>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.from_codepage(codepage)</td><td><p>Converts from codepage encoded text to UTF-8 encoded exodus text
<tr><td><p><code></code></p></td><td><p><code>strvar.unquoter()</code></p></td><td>
</p>
<p>e.g. Codepage "CP1124" (Ukrainian).
</p>
Use Linux command "iconv -l" for complete list of code pages and encodings.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;</span><span class="se">\xa4</span><span class="s">&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">from_codepage</span><span class="p">(</span><span class="s">&quot;CP1124&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;Є&quot;</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">from_codepage</span><span class="p">(</span><span class="s">&quot;</span><span class="se">\xa4</span><span class="s">&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;CP1124&quot;</span><span class="p">);</span>
<span class="c1">// U+0404 Cyrillic Capital Letter Ukrainian Ie Unicode character</span>
</pre></div>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.to_codepage(codepage)</td><td>Converts to codepage encoded text from exodus UTF-8 encoded text
<tr><td><p><code></code></p></td><td><p><code>strvar.lowerer()</code></p></td><td>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Є&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">to_codepage</span><span class="p">(</span><span class="s">&quot;CP1124&quot;</span><span class="p">).</span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;HEX&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;A4&quot;</span>
</td></tr>
<span class="c1">// or</span>
<tr><td><p><code></code></p></td><td><p><code>strvar.raiser()</code></p></td><td>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">to_codepage</span><span class="p">(</span><span class="s">&quot;Є&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;CP1124&quot;</span><span class="p">).</span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;HEX&quot;</span><span class="p">);</span>
</td></tr>
</pre></div>
<tr><td><p><code></code></p></td><td><p><code>strvar.cropper()</code></p></td><td>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.trimmer(trimchars = " ")</code></p></td><td>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.trimmerfirst(trimchars = " ")</code></p></td><td>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.trimmerlast(trimchars = " ")</code></p></td><td>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.trimmerboth(trimchars = " ")</code></p></td><td>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.firster()</code></p></td><td>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.laster()</code></p></td><td>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.firster(length)</code></p></td><td>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.laster(length)</code></p></td><td>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.cutter(length)</code></p></td><td>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.paster(pos1, length, insertstr)</code></p></td><td>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.paster(pos1, insertstr)</code></p></td><td>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.prefixer(insertstr)</code></p></td><td>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.appender(appendable, ...)</code></p></td><td>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.popper()</code></p></td><td>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.fieldstorer(delimiter, fieldno, nfields, replacement)</code></p></td><td>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.substrer(pos1, length)</code></p></td><td>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.substrer(pos1)</code></p></td><td>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.converter(from_chars, to_chars)</code></p></td><td>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.textconverter(from_characters, to_characters)</code></p></td><td>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.replacer(regex, tostr)</code></p></td><td>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.replacer(regex, ReplacementFunction auto repl_func)</code></p></td><td>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.replacer(fromstr, tostr)</code></p></td><td>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.uniquer()</code></p></td><td>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.sorter(delimiter = FM)</code></p></td><td>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.reverser(delimiter = FM)</code></p></td><td>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.randomizer(delimiter = FM)</code></p></td><td>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>strvar.parser(char sepchar = ' ')</code></p></td><td>
</td></tr>
</td></tr>
</table>
</table>
<h5 id=Dynamic_Array_Functions>Dynamic Array Functions</h5>
<h5 id=I/O_Conversion>I/O Conversion</h5>


<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>var=</td><td>strvar.f(fieldno, valueno = 0, subvalueno = 0)</td><td><p>f() is a highly abbreviated alias for the Pick OS field/value/subvalue extract() function.
<tr><td><p><code>var=</code></p></td><td><p><code>var.oconv(convstr)</code></p></td><td><p>Convert internal data to output external display format.</p>
</p>
<p><em>convstr:</em> A conversion code or pattern. See ICONV/OCONV PATTERNS</p>
<p>"f()" can be thought of as "field" although the function can extract values and subvalues as well.
<p><em>return:</em> The data in external display format or, if the data is invalid and cannot converted, most conversions return the original data UNCONVERTED.</p>
</p>
<p><em>throw:</em> VarNotImplemented if convstr is invalid</p>
<p>The convenient Pick OS angle bracket syntax for field extraction (e.g. xxx<20>) is not available in C++.
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mi">30123</span><span class="p">).</span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;D/E&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;21/06/2050&quot;</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">oconv</span><span class="p">(</span><span class="mi">30123</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;D/E&quot;</span><span class="p">);</span>
</pre></div>
</p>
</p>
The abbreviated exodus field extraction function (e.g. xxx.f(20)) is provided instead since field access is extremely heavily used in source code.
</td></tr>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;f1^f2v1]f2v2]f2v3^f2&quot;</span><span class="kt">_var</span><span class="p">;</span>
<tr><td><p><code>var=</code></p></td><td><p><code>var.iconv(convstr)</code></p></td><td><p>Convert external data to internal format.</p>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">f</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;f2v2&quot;</span>
<p><em>convstr:</em> A conversion code or pattern. See ICONV/OCONV PATTERNS</p>
<p><em>return:</em> The data in internal format or, if the data is invalid and cannot be converted, most conversions return the EMPTY STRING ""</p>
<p><em>throw:</em> VarNotImplemented if convstr is invalid</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;21 JUN 2050&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">iconv</span><span class="p">(</span><span class="s">&quot;D/E&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// 30123</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">iconv</span><span class="p">(</span><span class="s">&quot;21 JUN 2050&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;D/E&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.extract(fieldno, valueno = 0, subvalueno = 0)</td><td>Extract a specific field, value or subvalue from a dynamic array.
<tr><td><p><code>var=</code></p></td><td><p><code>var.format(fmt_str, args, ...)</code></p></td><td><p>Classic format function in printf style</p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;f1^f2v1]f2v2]f2v3^f2&quot;</span><span class="kt">_var</span><span class="p">;</span>
<p>vars can be formatted either with C++ format codes e.g. {:_&gt;8.2f}</p>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">extract</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;f2v2&quot;</span>
<p>or with exodus oconv codes e.g. {::MD20P|R(_)#8} as in the below example.</p>
<span class="c1">//</span>
<p>
<span class="c1">// For brevity the function alias &quot;f()&quot; (standing for &quot;field&quot;) is normally used instead of &quot;extract()&quot; as follows:</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mf">12.345</span><span class="p">).</span><span class="nf">format</span><span class="p">(</span><span class="s">&quot;&#39;{:_&gt;8.2f}&#39;&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;&#39;___12.35&#39;&quot;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v3</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">f</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mf">12.345</span><span class="p">).</span><span class="nf">format</span><span class="p">(</span><span class="s">&quot;&#39;{::MD20P|R(_)#8}&#39;&quot;</span><span class="p">);</span>
<span class="c1">// or</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v3</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">format</span><span class="p">(</span><span class="s">&quot;&#39;{:_&gt;8.2f}&#39;&quot;</span><span class="p">,</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mf">12.345</span><span class="p">));</span><span class="w"> </span><span class="c1">// &quot;&#39;___12.35&#39;&quot;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v4</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">format</span><span class="p">(</span><span class="s">&quot;&#39;{::MD20P|R(_)#8}&#39;&quot;</span><span class="p">,</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mf">12.345</span><span class="p">));</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.update(fieldno, valueno, subvalueno, replacement)</td><td><p>Same as var.updater() function but returns a new string instead of updating a variable in place.<br>Rarely used.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.from_codepage(codepage)</code></p></td><td><p>Convert from codepage encoded text to UTF-8 encoded exodus text</p>
<p><em>codepage:</em> e.g. Codepage "CP1124" (Ukrainian).</p>
<p>Use Linux command "iconv -l" for a complete list of code pages and encodings.</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;</span><span class="se">\xa4</span><span class="s">&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">from_codepage</span><span class="p">(</span><span class="s">&quot;CP1124&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;Є&quot;</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">from_codepage</span><span class="p">(</span><span class="s">&quot;</span><span class="se">\xa4</span><span class="s">&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;CP1124&quot;</span><span class="p">);</span>
<span class="c1">// U+0404 Cyrillic Capital Letter Ukrainian Ie Unicode character</span>
</pre></div>
</p>
</p>
"update()" was called "replace()" in Pick OS/Basic.</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.update(fieldno, valueno, replacement)</td><td>Ditto for a specific multivalue</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.to_codepage(codepage)</code></p></td><td><p>Convert to codepage encoded text from exodus UTF-8 encoded text</p>
<tr><td>var=</td><td>strvar.update(fieldno, replacement)</td><td>Ditto for a specific field</td></tr>
<p>
<tr><td>var=</td><td>strvar.insert(fieldno, valueno, subvalueno, insertion)</td><td>Same as var.inserter() function but returns a new string instead of updating a variable in place.</td></tr>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Є&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">to_codepage</span><span class="p">(</span><span class="s">&quot;CP1124&quot;</span><span class="p">).</span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;HEX&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;A4&quot;</span>
<tr><td>var=</td><td>strvar.insert(fieldno, valueno, insertion)</td><td>Ditto for a specific multivalue</td></tr>
<span class="c1">// or</span>
<tr><td>var=</td><td>strvar.insert(fieldno, insertion)</td><td>Ditto for a specific field</td></tr>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">to_codepage</span><span class="p">(</span><span class="s">&quot;Є&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;CP1124&quot;</span><span class="p">).</span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;HEX&quot;</span><span class="p">);</span>
<tr><td>var=</td><td>strvar.remove(fieldno, valueno = 0, subvalueno = 0)</td><td><p>Same as var.remover() function but returns a new string instead of updating a variable in place.
</pre></div>
</p>
</p>
"remove()" was called "delete()" in Pick OS/Basic.</td></tr>
</td></tr>
</table>
</table>
<h5 id=Dynamic_Array_Filters>Dynamic Array Filters</h5>
<h5 id=Dynamic_Array_Functions>Dynamic Array Functions</h5>


<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>var=</td><td>strvar.sum()</td><td>Sum up multiple values into one higher level
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.f(fieldno, valueno = 0, subvalueno = 0)</code></p></td><td><p>f() is a highly abbreviated alias for the Pick OS field/value/subvalue extract() function.</p>
<p>"f()" can be thought of as "field" although the function can extract values and subvalues as well.</p>
<p>The convenient Pick OS angle bracket syntax for field extraction (e.g. xxx&lt;20&gt;) is not available in C++.</p>
<p>The abbreviated exodus field extraction function (e.g. xxx.f(20)) is provided instead since field access is extremely heavily used in source code.</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;f1^f2v1]f2v2]f2v3^f2&quot;</span><span class="kt">_var</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">f</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;f2v2&quot;</span>
</pre></div>
</p>
</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.extract(fieldno, valueno = 0, subvalueno = 0)</code></p></td><td><p>Extract a specific field, value or subvalue from a dynamic array.</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;f1^f2v1]f2v2]f2v3^f2&quot;</span><span class="kt">_var</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">extract</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;f2v2&quot;</span>
<span class="c1">//</span>
<span class="c1">// For brevity the function alias &quot;f()&quot; (standing for &quot;field&quot;) is normally used instead of &quot;extract()&quot; as follows:</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v3</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">f</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span>
</pre></div>
</p>
</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.update(fieldno, valueno, subvalueno, replacement)</code></p></td><td><p>Update (replace or insert) a specific subvalue  in a dynamic array.</p>
<p>Same as var.updater() function but returns a new string instead of updating a variable in place. Rarely used.</p>
<p>"update()" was called "replace()" in Pick OS/Basic.</p>
</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.update(fieldno, valueno, replacement)</code></p></td><td><p>Update (replace or insert) a specific value in a dynamic array.</p>
</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.update(fieldno, replacement)</code></p></td><td><p>Update (replace or insert) a specific field a dynamic array.</p>
</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.insert(fieldno, valueno, subvalueno, insertion)</code></p></td><td><p>Insert a subvalue in a dynamic array.</p>
<p>Same as var.inserter() function but returns a new string instead of updating a variable in place.</p>
</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.insert(fieldno, valueno, insertion)</code></p></td><td><p>Insert a value in a dynamic array.</p>
</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.insert(fieldno, insertion)</code></p></td><td><p>Insert a field in a dynamic array.</p>
</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.remove(fieldno, valueno = 0, subvalueno = 0)</code></p></td><td><p>Remove a field, value or subvalue from a dynamic array.</p>
<p>Same as var.remover() function but returns a new string instead of updating a variable in place.</p>
<p>"remove()" was called "delete()" in Pick OS/Basic.</p>
</td></tr>
</table>
<h5 id=Dynamic_Array_Filters>Dynamic Array Filters</h5>
 
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.sum()</code></p></td><td><p>Sum up multiple values in a dynamic array.</p>
<p>Whatever is the lowest level is summed up into a higher level.</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;1]2]3^4]5]6&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">sum</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;6^15&quot;_var</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;1]2]3^4]5]6&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">sum</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;6^15&quot;_var</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">sum</span><span class="p">(</span><span class="s">&quot;1]2]3^4]5]6&quot;</span><span class="kt">_var</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">sum</span><span class="p">(</span><span class="s">&quot;1]2]3^4]5]6&quot;</span><span class="kt">_var</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.sumall()</td><td>Sum up all levels into a single figure
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.sumall()</code></p></td><td><p>Sum up everything in a dynamic array.</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;1]2]3^4]5]6&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">sumall</span><span class="p">();</span><span class="w"> </span><span class="c1">// 21</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;1]2]3^4]5]6&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">sumall</span><span class="p">();</span><span class="w"> </span><span class="c1">// 21</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">sumall</span><span class="p">(</span><span class="s">&quot;1]2]3^4]5]6&quot;</span><span class="kt">_var</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">sumall</span><span class="p">(</span><span class="s">&quot;1]2]3^4]5]6&quot;</span><span class="kt">_var</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.sum(delimiter)</td><td>Ditto allowing commas etc.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.sum(delimiter)</code></p></td><td><p>Sum all fields using a given delimiter.</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;10,20,30&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">sum</span><span class="p">(</span><span class="s">&quot;,&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// 60</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;10,20,30&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">sum</span><span class="p">(</span><span class="s">&quot;,&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// 60</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">sum</span><span class="p">(</span><span class="s">&quot;10,20,30&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;,&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">sum</span><span class="p">(</span><span class="s">&quot;10,20,30&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;,&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.stddev()</code></p></td><td><p>Calculate basic statistics include stddev.</p>
<p><em>return:</em> An FM delimited string containing n, tot, min, max, tot, mean and stddev</p>
<p><em>strvar:</em> A dynamic array containing numbers using any field, value or subvalue mark delimiters.</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;-11.2^0^11.5^12^13.9^14&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="n">stddev</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;6^40.2^-11.2^14^6.7^9.32344714506&quot;_var</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">stddev</span><span class="p">(</span><span class="s">&quot;-11.2^0^11.5^12^13.9^14&quot;</span><span class="kt">_var</span><span class="p">);</span>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.mv(opcode, var2)</td><td>Binary ops (+, -, *, /) in parallel on multiple values
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.mv(opcode, var2)</code></p></td><td><p>Binary ops on parallel multivalues</p>
<p></p>
<p><em>opcode:</em> </p>
<dl>
<dt>+</dt><dd>Addition</dd>
<dt>-</dt><dd>Subtraction</dd>
<dt>∗</dt><dd>Multiplication</dd>
<dt>/</dt><dd>Division</dd>
</dl>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;10]20]30&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">mv</span><span class="p">(</span><span class="s">&quot;+&quot;</span><span class="p">,</span><span class="s">&quot;2]3]4&quot;</span><span class="kt">_var</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;12]23]34&quot;_var</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;10]20]30&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">mv</span><span class="p">(</span><span class="s">&quot;+&quot;</span><span class="p">,</span><span class="s">&quot;2]3]4&quot;</span><span class="kt">_var</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;12]23]34&quot;_var</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
</table>
</table>
Line 1,722: Line 1,869:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td></td><td>strvar.updater(fieldno, replacement)</td><td>Replace a specific field in a dynamic array
<tr><td><p><code></code></p></td><td><p><code>strvar.updater(fieldno, replacement)</code></p></td><td><p>Replace a specific field in a dynamic array</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;f1^v1]v2}s2}s3^f3&quot;</span><span class="kt">_var</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;f1^v1]v2}s2}s3^f3&quot;</span><span class="kt">_var</span><span class="p">;</span>
<span class="n">v1</span><span class="p">.</span><span class="nf">updater</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;f1^X^f3&quot;_var</span>
<span class="n">v1</span><span class="p">.</span><span class="nf">updater</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;f1^X^f3&quot;_var</span>
Line 1,730: Line 1,878:
<span class="nf">updater</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span>
<span class="nf">updater</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>strvar.updater(fieldno, valueno, replacement)</td><td>Replace a specific value of a specific field in a dynamic array.
<tr><td><p><code></code></p></td><td><p><code>strvar.updater(fieldno, valueno, replacement)</code></p></td><td><p>Replace a specific value in a dynamic array.</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;f1^v1]v2}s2}s3^f3&quot;</span><span class="kt">_var</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;f1^v1]v2}s2}s3^f3&quot;</span><span class="kt">_var</span><span class="p">;</span>
<span class="n">v1</span><span class="p">.</span><span class="nf">updater</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;f1^v1]X^f3&quot;_var</span>
<span class="n">v1</span><span class="p">.</span><span class="nf">updater</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;f1^v1]X^f3&quot;_var</span>
Line 1,739: Line 1,889:
<span class="nf">updater</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span>
<span class="nf">updater</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>strvar.updater(fieldno, valueno, subvalueno, replacement)</td><td>Replace a specific subvalue of a specific value of a specific field in a dynamic array.
<tr><td><p><code></code></p></td><td><p><code>strvar.updater(fieldno, valueno, subvalueno, replacement)</code></p></td><td><p>Replace a specific subvalue in a dynamic array.</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;f1^v1]v2}s2}s3^f3&quot;</span><span class="kt">_var</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;f1^v1]v2}s2}s3^f3&quot;</span><span class="kt">_var</span><span class="p">;</span>
<span class="n">v1</span><span class="p">.</span><span class="nf">updater</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;f1^v1]v2}X}s3^f3&quot;_var</span>
<span class="n">v1</span><span class="p">.</span><span class="nf">updater</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;f1^v1]v2}X}s3^f3&quot;_var</span>
Line 1,748: Line 1,900:
<span class="nf">updater</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span>
<span class="nf">updater</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>strvar.inserter(fieldno, insertion)</td><td>Insert a specific field in a dynamic array, moving all other fields up.
<tr><td><p><code></code></p></td><td><p><code>strvar.inserter(fieldno, insertion)</code></p></td><td><p>Insert a specific field in a dynamic array</p>
<p>All other fields are moved up.</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;f1^v1]v2}s2}s3^f3&quot;</span><span class="kt">_var</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;f1^v1]v2}s2}s3^f3&quot;</span><span class="kt">_var</span><span class="p">;</span>
<span class="n">v1</span><span class="p">.</span><span class="nf">inserter</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;f1^X^v1]v2}s2}s3^f3&quot;_var</span>
<span class="n">v1</span><span class="p">.</span><span class="nf">inserter</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;f1^X^v1]v2}s2}s3^f3&quot;_var</span>
Line 1,755: Line 1,910:
<span class="nf">inserter</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span>
<span class="nf">inserter</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>strvar.inserter(fieldno, valueno, insertion)</td><td>Ditto for a specific value in a specific field, moving all other values up.
<tr><td><p><code></code></p></td><td><p><code>strvar.inserter(fieldno, valueno, insertion)</code></p></td><td><p>Insert a specific value in a dynamic array.</p>
<p>All other values are moved up.</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;f1^v1]v2}s2}s3^f3&quot;</span><span class="kt">_var</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;f1^v1]v2}s2}s3^f3&quot;</span><span class="kt">_var</span><span class="p">;</span>
<span class="n">v1</span><span class="p">.</span><span class="nf">inserter</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;f1^v1]X]v2}s2}s3^f3&quot;_var</span>
<span class="n">v1</span><span class="p">.</span><span class="nf">inserter</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;f1^v1]X]v2}s2}s3^f3&quot;_var</span>
Line 1,762: Line 1,920:
<span class="nf">inserter</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span>
<span class="nf">inserter</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>strvar.inserter(fieldno, valueno, subvalueno, insertion)</td><td>Ditto for a specific subvalue in a dynamic array, moving all other subvalues up.
<tr><td><p><code></code></p></td><td><p><code>strvar.inserter(fieldno, valueno, subvalueno, insertion)</code></p></td><td><p>Insert a specific subvalue in a dynamic array.</p>
<p>All other subvalues are moved up.</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;f1^v1]v2}s2}s3^f3&quot;</span><span class="kt">_var</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;f1^v1]v2}s2}s3^f3&quot;</span><span class="kt">_var</span><span class="p">;</span>
<span class="n">v1</span><span class="p">.</span><span class="nf">inserter</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;f1^v1]v2}X}s2}s3^f3&quot;_var</span>
<span class="n">v1</span><span class="p">.</span><span class="nf">inserter</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;f1^v1]v2}X}s2}s3^f3&quot;_var</span>
Line 1,769: Line 1,930:
<span class="n">v1</span><span class="p">.</span><span class="nf">inserter</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span>
<span class="n">v1</span><span class="p">.</span><span class="nf">inserter</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>strvar.remover(fieldno, valueno = 0, subvalueno = 0)</td><td>Remove a specific field (or value, or subvalue) from a dynamic array, moving all other fields (or values, or subvaluesdown.
<tr><td><p><code></code></p></td><td><p><code>strvar.remover(fieldno, valueno = 0, subvalueno = 0)</code></p></td><td><p>Remove a specific field, value, or subvalue from a dynamic array.</p>
<p>All other fields, values, or subvalues are moved down.</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;f1^v1]v2}s2}s3^f3&quot;</span><span class="kt">_var</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;f1^v1]v2}s2}s3^f3&quot;</span><span class="kt">_var</span><span class="p">;</span>
<span class="n">v1</span><span class="p">.</span><span class="nf">remover</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;f1^v1^f3&quot;_var</span>
<span class="n">v1</span><span class="p">.</span><span class="nf">remover</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;f1^v1^f3&quot;_var</span>
Line 1,776: Line 1,940:
<span class="nf">remover</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span>
<span class="nf">remover</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
</table>
</table>
Line 1,782: Line 1,947:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>var=</td><td>strvar.locate(target)</td><td><p>locate() with only the target substr argument provided searches unordered values separated by any of the field mark chars.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.locate(substr)</code></p></td><td><p>locate substr in dynamic array</p>
</p>
<p>Search unordered fields, values and/or subvalues.</p>
<p><em>Returns:</em> The field, value, subvalue etc. number if found or 0 if not.
<p>With only the substr argument provided, locate searches regardless of the field mark delimiters present.</p>
</p>
<p><em>return:</em> The field, value or subvalue number if found or 0 if not. Fields are counted regardless of delimiter.</p>
Searching for empty fields, values etc. (i.e. "") will work. Locating "" in "]yy" will return 1, in "xx]]zz" 2, and in "xx]yy]" 3, however, locating "" in "xx" will return 0 because there is conceptually no empty value in "xx". Locate "" in "" will return 1.
<p>Searching for empty fields, values etc. (i.e. "") will work. Locating "" in "]yy" will return 1, in "xx]]zz" 2, and in "xx]yy]" 3, however, locating "" in "xx" will return 0 because there is conceptually no empty value in "xx". Locate "" in "" will return 1.</p>
<p>
<div class="highlight light"><pre><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="s">&quot;UK^US^UA&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">locate</span><span class="p">(</span><span class="s">&quot;US&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">// 2</span>
<div class="highlight light"><pre><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="s">&quot;UK^US^UA&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">locate</span><span class="p">(</span><span class="s">&quot;US&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">// 2</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">locate</span><span class="p">(</span><span class="s">&quot;US&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;UK^US^UA&quot;</span><span class="kt">_var</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">locate</span><span class="p">(</span><span class="s">&quot;US&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;UK^US^UA&quot;</span><span class="kt">_var</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>strvar.locate(target, out valueno)</td><td><p>locate() with only the target substr provided and setting returned searches unordered values separated by any type of field mark chars.
<tr><td><p><code>if</code></p></td><td><p><code>strvar.locate(substr, out valueno)</code></p></td><td><p>locate substr in values.</p>
</p>
<p>Search unordered VM delimited string.</p>
<p><em>Returns:</em> True if found
<p><em>valueno[out]:</em> Value number if found or the max value number + 1 if not. If not found then valueno [out] is suitable for creating a new value.</p>
</p>
<p><em>return:</em> True if found or False if not.</p>
<em>Setting:</em> Field, value, subvalue etc. number if found or the max number + 1 if not. Suitable for additiom of new values
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">setting</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">valueno</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="s">&quot;UK]US]UA&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">locate</span><span class="p">(</span><span class="s">&quot;US&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">setting</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">// setting -&gt; 2</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="s">&quot;UK]US]UA&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">locate</span><span class="p">(</span><span class="s">&quot;US&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">valueno</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">// valueno -&gt; 2</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">locate</span><span class="p">(</span><span class="s">&quot;US&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;UK]US]UA&quot;</span><span class="kt">_var</span><span class="p">,</span><span class="w"> </span><span class="n">setting</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">locate</span><span class="p">(</span><span class="s">&quot;US&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;UK]US]UA&quot;</span><span class="kt">_var</span><span class="p">,</span><span class="n">valueno</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>strvar.locate(target, out setting, fieldno, valueno = 0)</td><td><p>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.
<tr><td><p><code>if</code></p></td><td><p><code>strvar.locate(substr, out num, fieldno, valueno = 0)</code></p></td><td><p>locate substr in dynamic array.</p>
<p>Search in an unordered dynamic array.</p>
<p><em>fieldno:</em> If fieldno is non-zero then search the specified field number otherwise, if fieldno is 0, search using FM as delimiter.</p>
<p><em>valueno:</em> If provided, search the specified value number for a subvalue.</p>
<p><em>num[out]:</em> If found, the field, value or subvalue number where it was found. If not found, the max field, value or subvalue number + 1. If not found then num [out] is suitable for creating a new field, value or subvalue.</p>
<p><em>return:</em> True if found or False if not.</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="nf">num</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="s">&quot;f1^f2v1]f2v2]s1}s2}s3}s4^f3^f4&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">locate</span><span class="p">(</span><span class="s">&quot;s4&quot;</span><span class="p">,</span><span class="w"> </span><span class="nf">num</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">// num -&gt; 4 // Return true</span>
</pre></div>
</p>
</p>
<p><em>Returns:</em> True if found and with the field, value or subvalue number in setting.
</td></tr>
</p>
<tr><td><p><code>if</code></p></td><td><p><code>strvar.locateby(ordercode, substr, out valueno)</code></p></td><td><p>locate substr in ordered dynamic array</p>
<em>Returns:</em> False if not found and with the max field, value or subvalue number found + 1 in setting. Suitable for replacement of new fields, values or subvalues.
<p>locateby() without fieldno or valueno arguments, searches ordered values separated by VM chars.</p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">setting</span><span class="p">;</span>
<p>Data must already be in the correct order for searching to work properly.</p>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="s">&quot;f1^f2v1]f2v2]s1}s2}s3}s4^f3^f4&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">locate</span><span class="p">(</span><span class="s">&quot;s4&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">setting</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">// setting -&gt; 4 // returns true</span>
<p><em>ordercode:</em> </p>
<dl>
<dt>AL</dt><dd>Ascending  - Left Justified (Alphabetic)</dd>
<dt>DL</dt><dd>Descending - Left Justified (Alphabetic)</dd>
<dt>AR</dt><dd>Ascending  - Right Justified (Numeric/Natural)</dd>
<dt>DR</dt><dd>Descending - Right Justified (Numeric/Natural)</dd>
</dl>
<p><em>return:</em> True if found, otherwise false.</p>
<p><em>valueno[out]:</em> Either the value no found or the correct value no for inserting the substr</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">valueno</span><span class="p">;</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="s">&quot;aaa]bbb]ccc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">locateby</span><span class="p">(</span><span class="s">&quot;AL&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;bb&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">valueno</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="c1">// valueno -&gt; 2 // Return false and valueno = where it could be correctly inserted.</span>
</pre></div>
</pre></div>
</td></tr>
<tr><td>if</td><td>strvar.locateby(ordercode, target, out valueno)</td><td><p>locateby() without fieldno or valueno arguments searches ordered values separated by VM chars.
</p>
<p>The order code can be AL, DL, AR, DR meaning Ascending Left, Descending Right, Ascending Right, Ascending Left.
</p>
<p>Left is used to indicate alphabetic order where 10 < 2.
</p>
<p>Right is used to indicate numeric order where 10 > 2.
</p>
<p>Data must be in the correct order for searching to work properly.
</p>
<p><em>Returns:</em> True if found.
</p>
</p>
In case the target is not exactly found then the correct value no for inserting the target is returned in setting.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">valueno</span><span class="p">;</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="s">&quot;aaa]bbb]ccc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">locateby</span><span class="p">(</span><span class="s">&quot;AL&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;bb&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">valueno</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="c1">// valueno -&gt; 2 // returns false and valueno = where it could be correctly inserted.</span>
</pre></div>
</td></tr>
</td></tr>
<tr><td>if</td><td>strvar.locateby(ordercode, target, out setting, fieldno, valueno = 0)</td><td>locateby() ordered as above but in fields if fieldno is 0, or values in a specific fieldno, or subvalues in a specific valueno.
<tr><td><p><code>if</code></p></td><td><p><code>strvar.locateby(ordercode, substr, out num, fieldno, valueno = 0)</code></p></td><td><p>locate substr in ordered dynamic array</p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">setting</span><span class="p">;</span>
<p>locateby() with fieldno and/or valueno arguments, searches fields if fieldno is 0, or values in a specific fieldno, or subvalues in a specific valueno.</p>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="s">&quot;f1^f2^aaa]bbb]ccc^f4&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">locateby</span><span class="p">(</span><span class="s">&quot;AL&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;bb&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">setting</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="c1">// setting -&gt; 2 // return false and where it could be correctly inserted.</span>
<p>For more info, see locateby() without fieldno or valueno arguments.</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="nf">num</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="s">&quot;f1^f2^aaa]bbb]ccc^f4&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">locateby</span><span class="p">(</span><span class="s">&quot;AL&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;bb&quot;</span><span class="p">,</span><span class="w"> </span><span class="nf">num</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="c1">// num -&gt; 2 // return false and where it could be correctly inserted.</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>strvar.locateusing(usingchar, target)</td><td>locate() a target substr in the whole unordered string using a given delimiter char returning true if found.
<tr><td><p><code>if</code></p></td><td><p><code>strvar.locateusing(usingchar, substr)</code></p></td><td><p>locate substr using any delimiter.</p>
<p>
<div class="highlight light"><pre><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="s">&quot;AB,EF,CD&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">locateusing</span><span class="p">(</span><span class="s">&quot;,&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;EF&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<div class="highlight light"><pre><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="s">&quot;AB,EF,CD&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">locateusing</span><span class="p">(</span><span class="s">&quot;,&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;EF&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>strvar.locateusing(usingchar, target, out setting, fieldno = 0, valueno = 0, subvalueno = 0)</td><td><p>locate() the target in a specific field, value or subvalue using a specified delimiter and unordered data
<tr><td><p><code>if</code></p></td><td><p><code>strvar.locateusing(usingchar, substr, out num, fieldno = 0, valueno = 0, subvalueno = 0)</code></p></td><td><p>locate substr in dynamic array using any delimiter</p>
<p>Search in a specific field, value or subvalue.</p>
<p><em>num[out]:</em>  If found, the number where found, otherwise the maximum number of delimited fields + 1.</p>
<p><em>return:</em> True if found and False if not.</p>
<p>This is similar to the main locate command but the delimiter char can be specified e.g. a comma or TM etc.</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="nf">num</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="s">&quot;f1^f2^f3c1,f3c2,f3c3^f4&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">locateusing</span><span class="p">(</span><span class="s">&quot;,&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;f3c2&quot;</span><span class="p">,</span><span class="w"> </span><span class="nf">num</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">// num -&gt; 2 // Return true</span>
</pre></div>
</p>
</p>
<p><em>Returns:</em> True If found and returns in setting the number of the delimited field found.
</p>
<p><em>Returns:</em> False if not found and returns in setting the maximum number of delimited fields + 1 if not found.
</p>
This is similar to the main locate command but the delimiter char can be specified e.g. a comma or TM etc.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">setting</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="s">&quot;f1^f2^f3c1,f3c2,f3c3^f4&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">locateusing</span><span class="p">(</span><span class="s">&quot;,&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;f3c2&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">setting</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">// setting -&gt; 2 // returns true</span>
</pre></div>
</td></tr>
</td></tr>
<tr><td>if</td><td>strvar.locatebyusing(ordercode, usingchar, target, out setting, fieldno = 0, valueno = 0, subvalueno = 0)</td><td><p>locatebyusing() supports all the above features in a single function.
<tr><td><p><code>if</code></p></td><td><p><code>strvar.locatebyusing(ordercode, usingchar, substr, out num, fieldno = 0, valueno = 0, subvalueno = 0)</code></p></td><td><p>locatebyusing() supports all the locate features in a single function.</p>
</p>
</td></tr>
<em>Returns:</em> True if found.</td></tr>
</table>
</table>
<h5 id=Database_Access>Database Access</h5>
<h5 id=Database_Access>Database Access</h5>
Line 1,856: Line 2,033:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>if</td><td>conn.connect(conninfo = "")</td><td><p>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.
<tr><td><p><code>if</code></p></td><td><p><code>dbconn.connect(conninfo = "")</code></p></td><td><p>Establish a connection to a database.</p>
</p>
<p><em>conninfo:</em> The DB connection string parameters are merged from the following places in descending priority.</p>
<p>The DB connection string (conninfo) parameters are merged from the following places in descending priority.
<ol>
</p>
<li>Provided in connect()'s conninfo argument. See the last option. for the complete list of parameters.</li>
<p>1. Provided in connect()'s conninfo argument. See 4. for the complete list of parameters.
<li>Any environment variables EXO_HOST EXO_PORT EXO_USER EXO_DATA EXO_PASS EXO_TIME</li>
</p>
<li>Any parameters found in a configuration file at ~/.config/exodus/exodus.cfg</li>
<p>2. Any environment variables EXO_HOST EXO_PORT EXO_USER EXO_DATA EXO_PASS EXO_TIME
<li>The default conninfo is "host=127.0.0.1 port=5432 dbname=exodus user=exodus password=somesillysecret connect_timeout=10"</li>
</p>
</ol>
<p>3. Any parameters found in a configuration file at ~/.config/exodus/exodus.cfg
<p>Setting environment variable EXO_DBTRACE=1 will cause tracing of DB interface including SQL commands.</p>
</p>
<p><em>dbconn[out]:</em> Becomes a reference or handle for future functions that require a connection argument.</p>
<p>4. The default conninfo is "host=127.0.0.1 port=5432 dbname=exodus user=exodus password=somesillysecret connect_timeout=10"
<p>For all the various DB function calls, the dbconn or operative var can be either:</p>
</p>
<ul>
Setting environment variable EXO_DBTRACE=1 will cause tracing of DB interface including SQL commands.
<li>A DB connection created with dbconnect().</li>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">conn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<li>A file var created with open().</li>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="n">conn</span><span class="p">.</span><span class="nf">connect</span><span class="p">(</span><span class="s">&quot;dbname=exodus user=exodus password=somesillysecret&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...;</span>
<li>Any var. A default connection will be established on the fly.</li>
</ul>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">dbconn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="n">dbconn</span><span class="p">.</span><span class="nf">connect</span><span class="p">(</span><span class="s">&quot;dbname=exodus user=exodus password=somesillysecret&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">connect</span><span class="p">())</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">connect</span><span class="p">())</span><span class="w"> </span><span class="p">...</span>
Line 1,876: Line 2,057:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">connect</span><span class="p">(</span><span class="s">&quot;exodus&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">connect</span><span class="p">(</span><span class="s">&quot;exodus&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>conn.attach(filenames)</td><td><p>"attach" causes the given filenames to be associated with a specific connection for the remainder of the session.
<tr><td><p><code>if</code></p></td><td><p><code>dbconn.attach(filenames)</code></p></td><td><p>Attach filename(s) to a specific DB connection.</p>
</p>
<p>Any following use of the given filename(s) without specifying a connection will be directed to the specified connection until process termination.</p>
<p>It is not necessary to attach files before opening them.
<p>It is not necessary to attach files before opening them but the act of opening them also attaches them.</p>
</p>
<p>The files must exist in the specified connection.</p>
<p>Attachments can changed by calling attach() or open() on a different connection or they can be removed by calling detach().
<p>Attachments can changed by calling attach() or open() on a different connection or they can be removed by calling detach().</p>
</p>
<p><em>dbconn:</em> The connection to which the filename(s) should be attached. Defaults to the default connection.</p>
<p><em>var:</em> Defaults to the default connection.
<p><em>filenames:</em> FM separated list.</p>
</p>
<p><em>return:</em> False if any filename does not exist and cannot be opened on the given connection. All filenames that can be opened on the connection are attached even if some cannot.</p>
<p><em>filenames:</em> FM separated list.
<p>Internally, attach merely opens each filename on the given connection causing them to be added to an internal cache.</p>
</p>
<p>
<p><em>Returns:</em> false if any filename does not exist and cannot be opened on the given connection. All filenames that can be opened on the conneciton are attached even if some cannot.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">dbconn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
</p>
Internally, attach merely opens each filename on the given connection causing them to be added to an internal cache.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">conn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">filenames</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients^dict.xo_clients&quot;</span><span class="kt">_var</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">filenames</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients^dict.xo_clients&quot;</span><span class="kt">_var</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">conn</span><span class="p">.</span><span class="nf">attach</span><span class="p">(</span><span class="n">filenames</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">dbconn</span><span class="p">.</span><span class="nf">attach</span><span class="p">(</span><span class="n">filenames</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">attach</span><span class="p">(</span><span class="n">filenames</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">attach</span><span class="p">(</span><span class="n">filenames</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>conn.detach(filenames)</td><td><p>Removes files from the internal cache created by previous open() and attach() calls.
<tr><td><p><code></code></p></td><td><p><code>dbconn.detach(filenames)</code></p></td><td><p>Remove files from the internal cache created by previous open() and attach() calls.</p>
</p>
<p><em>filenames:</em> FM separated list.</p>
<p><em>var:</em> Defaults to the default connection.
</p>
<p><em>filenames:</em> FM separated list.
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>conn.begintrans()</td><td>Begin a DB transaction.
<tr><td><p><code>if</code></p></td><td><p><code>dbconn.begintrans()</code></p></td><td><p>Begin a DB transaction.</p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">conn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<p><em>return:</em> </p>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="n">conn</span><span class="p">.</span><span class="nf">begintrans</span><span class="p">())</span><span class="w"> </span><span class="p">...</span>
<dl>
<dt>True</dt><dd>Successfully begun.</dd>
<dt>False</dt><dd>DB refused. See lasterror() for info.</dd>
</dl>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">dbconn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="n">dbconn</span><span class="p">.</span><span class="nf">begintrans</span><span class="p">())</span><span class="w"> </span><span class="p">...</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">begintrans</span><span class="p">())</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">begintrans</span><span class="p">())</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>conn.statustrans()</td><td>Check if a DB transaction is in progress.
<tr><td><p><code>if</code></p></td><td><p><code>dbconn.statustrans()</code></p></td><td><p>Check if a DB transaction is in progress.</p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">conn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<p><em>return:</em> True or False.</p>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">conn</span><span class="p">.</span><span class="nf">statustrans</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">dbconn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">dbconn</span><span class="p">.</span><span class="nf">statustrans</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">statustrans</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">statustrans</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>conn.rollbacktrans()</td><td>Rollback a DB transaction.
<tr><td><p><code>if</code></p></td><td><p><code>dbconn.rollbacktrans()</code></p></td><td><p>Rollback a DB transaction.</p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">conn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<p><em>return:</em> </p>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">conn</span><span class="p">.</span><span class="nf">rollbacktrans</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<dl>
<dt>True</dt><dd>Successfully rolled back or there was no transaction in progress.</dd>
<dt>False</dt><dd>DB refused. See lasterror() for info.</dd>
</dl>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">dbconn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">dbconn</span><span class="p">.</span><span class="nf">rollbacktrans</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">rollbacktrans</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">rollbacktrans</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>conn.committrans()</td><td><p>Commit a DB transaction.
<tr><td><p><code>if</code></p></td><td><p><code>dbconn.committrans()</code></p></td><td><p>Commit a DB transaction.</p>
</p>
<p><em>return:</em> </p>
<em>Returns:</em> True if successfully committed or if there was no transaction in progress, otherwise false.
<dl>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">conn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<dt>True</dt><dd>Successfully committed or there was no transaction in progress.</dd>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">conn</span><span class="p">.</span><span class="nf">committrans</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<dt>False</dt><dd>DB refused. See lasterror() for info.</dd>
</dl>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">dbconn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">dbconn</span><span class="p">.</span><span class="nf">committrans</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">committrans</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">committrans</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>conn.sqlexec(sqlcmd)</td><td><p>Execute an sql command.
<tr><td><p><code>if</code></p></td><td><p><code>dbconn.sqlexec(sqlcmd)</code></p></td><td><p>Execute an sql command.</p>
</p>
<p><em>return:</em> </p>
<em>Returns:</em> True if there was no sql error otherwise lasterror() returns a detailed error message.
<dl>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">conn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<dt>True</dt><dd>Successfully executed.</dd>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">conn</span><span class="p">.</span><span class="nf">sqlexec</span><span class="p">(</span><span class="s">&quot;select 1&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<dt>False</dt><dd>DB refused. See lasterror() for info.</dd>
</dl>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">dbconn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">dbconn</span><span class="p">.</span><span class="nf">sqlexec</span><span class="p">(</span><span class="s">&quot;select 1&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">sqlexec</span><span class="p">(</span><span class="s">&quot;select 1&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">sqlexec</span><span class="p">(</span><span class="s">&quot;select 1&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>conn.sqlexec(sqlcmd, io response)</td><td><p>Execute an SQL command and capture the response.
<tr><td><p><code>if</code></p></td><td><p><code>dbconn.sqlexec(sqlcmd, io response)</code></p></td><td><p>Execute an SQL command and capture the response.</p>
</p>
<p><em>return:</em> </p>
<p><em>Returns:</em> True if there was no sql error otherwise response contains a detailed error message.
<dl>
</p>
<dt>True</dt><dd>Successfully executed.</dd>
<p><em>response:</em> Any rows and columns returned are separated by RM and FM respectively. The first row is the column names.
<dt>False</dt><dd>DB refused. See lasterror() for info.</dd>
</p>
</dl>
<em>Recommended:</em> Don't use sql directly unless you must to manage or configure a database.
<p><em>response:</em> Any rows and columns returned are separated by RM and FM respectively. The first row is the column names.</p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">conn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<p>It is *ecommended* that you do not use sql directly unless you must, perhaps to manage or configure a database.</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">dbconn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">sqlcmd</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;select &#39;xxx&#39; as col1, &#39;yyy&#39; as col2&quot;</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">sqlcmd</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;select &#39;xxx&#39; as col1, &#39;yyy&#39; as col2&quot;</span><span class="p">;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">response</span><span class="p">;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">response</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">conn</span><span class="p">.</span><span class="nf">sqlexec</span><span class="p">(</span><span class="n">sqlcmd</span><span class="p">,</span><span class="w"> </span><span class="n">response</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">// response -&gt; &quot;col1^col2\x1fxxx^yyy&quot;_var /// \x1f is the Record Mark (RM) char. The backtick char is used here by gendoc to deliminate source code.</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">dbconn</span><span class="p">.</span><span class="nf">sqlexec</span><span class="p">(</span><span class="n">sqlcmd</span><span class="p">,</span><span class="w"> </span><span class="n">response</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">// response -&gt; &quot;col1^col2\x1fxxx^yyy&quot;_var /// \x1f is the Record Mark (RM) char. The backtick char is used here by gendoc to deliminate source code.</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">sqlexec</span><span class="p">(</span><span class="n">sqlcmd</span><span class="p">,</span><span class="w"> </span><span class="n">response</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">sqlexec</span><span class="p">(</span><span class="n">sqlcmd</span><span class="p">,</span><span class="w"> </span><span class="n">response</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>conn.disconnect()</td><td>Closes DB connection and frees process resources both locally and in the database server.
<tr><td><p><code></code></p></td><td><p><code>dbconn.disconnect()</code></p></td><td><p>Close a DB connection</p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">conn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<p>Free process resources both locally and in the database server.</p>
<span class="n">conn</span><span class="p">.</span><span class="nf">disconnect</span><span class="p">();</span>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">dbconn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<span class="n">dbconn</span><span class="p">.</span><span class="nf">disconnect</span><span class="p">();</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">disconnect</span><span class="p">();</span>
<span class="nf">disconnect</span><span class="p">();</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>conn.disconnectall()</td><td><p>Closes all connections and frees process resources both locally and in the database server(s).
<tr><td><p><code></code></p></td><td><p><code>dbconn.disconnectall()</code></p></td><td><p>Close all DB connections</p>
</p>
<p>Free process resources both locally and in the database server(s).</p>
All connections are closed automatically when a process terminates.
<p>All connections are closed automatically when a process terminates.</p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">conn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<p>
<span class="n">conn</span><span class="p">.</span><span class="nf">disconnectall</span><span class="p">();</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">dbconn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<span class="n">dbconn</span><span class="p">.</span><span class="nf">disconnectall</span><span class="p">();</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">disconnectall</span><span class="p">();</span>
<span class="nf">disconnectall</span><span class="p">();</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>var::lasterror()</td><td>
<tr><td><p><code>var=</code></p></td><td><p><code>var::lasterror()</code></p></td><td><p><em>return:</em> The last OS or DB error message.</p>
<em>Returns:</em> The last OS or DB error message.
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">lasterror</span><span class="p">();</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">lasterror</span><span class="p">();</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">lasterror</span><span class="p">();</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">lasterror</span><span class="p">();</span>
</pre></div>
</pre></div>
</p>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>dbconn.setlasterror(msg)</code></p></td><td><p>Set the lasterror() message.</p>
</td></tr>
</td></tr>
<tr><td></td><td>conn.setlasterror(msg)</td><td>Set the lasterror() message.</td></tr>
<tr><td><p><code></code></p></td><td><p><code>var::loglasterror(source = "")</code></p></td><td><p>Log the last OS or DB error message.</p>
<tr><td></td><td>var::loglasterror(source = "")</td><td><p>Log the last OS or DB error message.
<p><em>Output:</em> To stdlog</p>
</p>
<p>Prefix the output with source if provided.</p>
<p><em>Output:</em> to stdlog
<p>
</p>
Prefixes the output with source if provided.
<div class="highlight light"><pre><span class="kt">var</span><span class="o">::</span><span class="nf">loglasterror</span><span class="p">(</span><span class="s">&quot;main:&quot;</span><span class="p">);</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="o">::</span><span class="nf">loglasterror</span><span class="p">(</span><span class="s">&quot;main:&quot;</span><span class="p">);</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">loglasterror</span><span class="p">(</span><span class="s">&quot;main:&quot;</span><span class="p">);</span>
<span class="nf">loglasterror</span><span class="p">(</span><span class="s">&quot;main:&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
</table>
</table>
Line 1,997: Line 2,210:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>if</td><td>conn.dbcreate(new_dbname, old_dbname = "")</td><td><p>Create a named database on a particular connection.
<tr><td><p><code>if</code></p></td><td><p><code>dbconn.dbcreate(new_dbname, old_dbname = "")</code></p></td><td><p>Create a named database on a particular connection.</p>
</p>
<p>Optionally copies an existing database from the same connection</p>
<p>The target database cannot already exist.
<p><em>return:</em> True or False. See lasterror() for errors.</p>
</p>
<ul>
Optionally copies an existing database from the same connection and which cannot have any current connections.
<li>Target database must not already exist.</li>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">conn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<li>Source database must exist on the same connection.</li>
<li>Source database cannot have any current connections.</li>
</ul>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">dbconn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">dbdelete</span><span class="p">(</span><span class="s">&quot;xo_gendoc_testdb&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">{};</span><span class="w"> </span><span class="c1">// Cleanup first</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">dbdelete</span><span class="p">(</span><span class="s">&quot;xo_gendoc_testdb&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">{};</span><span class="w"> </span><span class="c1">// Cleanup first</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">conn</span><span class="p">.</span><span class="nf">dbcreate</span><span class="p">(</span><span class="s">&quot;xo_gendoc_testdb&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">dbconn</span><span class="p">.</span><span class="nf">dbcreate</span><span class="p">(</span><span class="s">&quot;xo_gendoc_testdb&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">dbcreate</span><span class="p">(</span><span class="s">&quot;xo_gendoc_testdb&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">dbcreate</span><span class="p">(</span><span class="s">&quot;xo_gendoc_testdb&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>conn.dbcopy(from_dbname, to_dbname)</td><td><p>Create a named database as a copy of an existing database.
<tr><td><p><code>if</code></p></td><td><p><code>dbconn.dbcopy(from_dbname, to_dbname)</code></p></td><td><p>Create a named database as a copy of an existing database.</p>
</p>
<p><em>return:</em> True or False. See lasterror() for errors.</p>
<p>The target database cannot already exist.
<ul>
</p>
<li>Target database must not already exist.</li>
The source database must exist on the same connection and cannot have any current connections.
<li>Source database must exist on the same connection.</li>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">conn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<li>Source database cannot have any current connections.</li>
</ul>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">dbconn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">dbdelete</span><span class="p">(</span><span class="s">&quot;xo_gendoc_testdb2&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">{};</span><span class="w"> </span><span class="c1">// Cleanup first</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">dbdelete</span><span class="p">(</span><span class="s">&quot;xo_gendoc_testdb2&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">{};</span><span class="w"> </span><span class="c1">// Cleanup first</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">conn</span><span class="p">.</span><span class="nf">dbcopy</span><span class="p">(</span><span class="s">&quot;xo_gendoc_testdb&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;xo_gendoc_testdb2&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">dbconn</span><span class="p">.</span><span class="nf">dbcopy</span><span class="p">(</span><span class="s">&quot;xo_gendoc_testdb&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;xo_gendoc_testdb2&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">dbcopy</span><span class="p">(</span><span class="s">&quot;xo_gendoc_testdb&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;xo_gendoc_testdb2&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">dbcopy</span><span class="p">(</span><span class="s">&quot;xo_gendoc_testdb&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;xo_gendoc_testdb2&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>conn.dblist()</td><td>
<tr><td><p><code>var=</code></p></td><td><p><code>dbconn.dblist()</code></p></td><td><p>Get a list of available databases.</p>
<em>Returns:</em> A list of available databases on a particular connection.
<p>A list for a given connection or the default connection.</p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">conn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<p><em>return:</em> An FM delimited list.</p>
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">conn</span><span class="p">.</span><span class="nf">dblist</span><span class="p">();</span>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">dbconn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">dbconn</span><span class="p">.</span><span class="nf">dblist</span><span class="p">();</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">dblist</span><span class="p">();</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">dblist</span><span class="p">();</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>conn.dbdelete(dbname)</td><td><p>Delete (drop) a named database.
<tr><td><p><code>if</code></p></td><td><p><code>dbconn.dbdelete(dbname)</code></p></td><td><p>Delete (drop) a named database.</p>
</p>
<p><em>return:</em> True or False. See lasterror() for errors.</p>
The target database must exist and cannot have any current connections.
<ul>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">conn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<li>Database does not exist</li>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">conn</span><span class="p">.</span><span class="nf">dbdelete</span><span class="p">(</span><span class="s">&quot;xo_gendoc_testdb2&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<li>Database has active connections.</li>
</ul>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">dbconn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">dbconn</span><span class="p">.</span><span class="nf">dbdelete</span><span class="p">(</span><span class="s">&quot;xo_gendoc_testdb2&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">dbdelete</span><span class="p">(</span><span class="s">&quot;xo_gendoc_testdb2&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">dbdelete</span><span class="p">(</span><span class="s">&quot;xo_gendoc_testdb2&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>conn.createfile(filename)</td><td><p>Create a named DB file.
<tr><td><p><code>if</code></p></td><td><p><code>dbconn.createfile(filename)</code></p></td><td><p>Create a named DB file.</p>
</p>
<p>filenames ending with "_temp" only last until the connection is closed.</p>
filenames ending with "_temp" only last until the connection is closed.
<p><em>return:</em> True or False. See lasterror() for errors.</p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">filename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_gendoc_temp&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">conn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<ul>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">conn</span><span class="p">.</span><span class="nf">createfile</span><span class="p">(</span><span class="n">filename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<li>Filename is invalid.</li>
<li>Filename already exists.</li>
</ul>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">filename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_gendoc_temp&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">dbconn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">dbconn</span><span class="p">.</span><span class="nf">createfile</span><span class="p">(</span><span class="n">filename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">createfile</span><span class="p">(</span><span class="n">filename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">createfile</span><span class="p">(</span><span class="n">filename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>conn.renamefile(filename, newfilename)</td><td>Rename a DB file.
<tr><td><p><code>if</code></p></td><td><p><code>dbconn.renamefile(filename, newfilename)</code></p></td><td><p>Rename a DB file.</p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">conn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">filename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_gendoc_temp&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">new_filename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_gendoc_temp2&quot;</span><span class="p">;</span>
<p><em>return:</em> True or False. See lasterror() for errors.</p>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">conn</span><span class="p">.</span><span class="nf">renamefile</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span><span class="w"> </span><span class="n">new_filename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<ul>
<li>source filename does not exist.</li>
<li>newfilename is invalid.</li>
<li>newfilename already exists.</li>
</ul>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">dbconn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">filename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_gendoc_temp&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">new_filename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_gendoc_temp2&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">dbconn</span><span class="p">.</span><span class="nf">renamefile</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span><span class="w"> </span><span class="n">new_filename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">renamefile</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span><span class="w"> </span><span class="n">new_filename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">renamefile</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span><span class="w"> </span><span class="n">new_filename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>conn.listfiles()</td><td>
<tr><td><p><code>var=</code></p></td><td><p><code>dbconn.listfiles()</code></p></td><td><p>Get a list of all files in a database.</p>
<em>Returns:</em> A list of all files in a database
<p><em>return:</em> An FM separated list.</p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">conn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<p>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="n">conn</span><span class="p">.</span><span class="nf">listfiles</span><span class="p">())</span><span class="w"> </span><span class="p">...</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">dbconn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="n">dbconn</span><span class="p">.</span><span class="nf">listfiles</span><span class="p">())</span><span class="w"> </span><span class="p">...</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">listfiles</span><span class="p">())</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">listfiles</span><span class="p">())</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>conn.clearfile(filename)</td><td>Delete all records in a DB file
<tr><td><p><code>if</code></p></td><td><p><code>dbconn.clearfile(filename)</code></p></td><td><p>Delete all records in a DB file.</p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">conn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">filename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_gendoc_temp2&quot;</span><span class="p">;</span>
<p><em>return:</em> True or False. See lasterror() for errors.</p>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="n">conn</span><span class="p">.</span><span class="nf">clearfile</span><span class="p">(</span><span class="n">filename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<ul>
<li>filename does not exist.</li>
</ul>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">dbconn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">filename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_gendoc_temp2&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="n">dbconn</span><span class="p">.</span><span class="nf">clearfile</span><span class="p">(</span><span class="n">filename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">clearfile</span><span class="p">(</span><span class="n">filename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">clearfile</span><span class="p">(</span><span class="n">filename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>conn.deletefile(filename)</td><td>Delete a DB file
<tr><td><p><code>if</code></p></td><td><p><code>dbconn.deletefile(filename)</code></p></td><td><p>Delete a DB file.</p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">conn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">filename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_gendoc_temp2&quot;</span><span class="p">;</span>
<p><em>return:</em> True or False. See lasterror() for errors.</p>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">conn</span><span class="p">.</span><span class="nf">deletefile</span><span class="p">(</span><span class="n">filename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<ul>
<li>filename does not exist.</li>
</ul>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">dbconn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">filename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_gendoc_temp2&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">dbconn</span><span class="p">.</span><span class="nf">deletefile</span><span class="p">(</span><span class="n">filename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">deletefile</span><span class="p">(</span><span class="n">filename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">deletefile</span><span class="p">(</span><span class="n">filename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>conn_or_file.reccount(filename = "")</td><td>
<tr><td><p><code>var=</code></p></td><td><p><code>conn_or_file.reccount(filename = "")</code></p></td><td><p>Get the approx number of records in a DB file.</p>
<p><em>Returns:</em> The approx. number of records in a DB file.
<p>Might return -1 if not known.</p>
</p>
<p>Not very accurate inside transactions.</p>
<p>Might return -1 if not known.
<p><em>return:</em> An approximate number.</p>
</p>
<p>
Not very accurate inside transactions.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">dbconn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">filename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">conn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">filename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">nrecs1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">dbconn</span><span class="p">.</span><span class="nf">reccount</span><span class="p">(</span><span class="n">filename</span><span class="p">);</span>
<span class="kt">var</span><span class="w"> </span><span class="n">nrecs1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">conn</span><span class="p">.</span><span class="nf">reccount</span><span class="p">(</span><span class="n">filename</span><span class="p">);</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="kt">var</span><span class="w"> </span><span class="n">nrecs2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">reccount</span><span class="p">(</span><span class="n">filename</span><span class="p">);</span>
<span class="kt">var</span><span class="w"> </span><span class="n">nrecs2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">reccount</span><span class="p">(</span><span class="n">filename</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
<tr><td><p><code>if</code></p></td><td><p><code>conn_or_file.flushindex(filename = "")</code></p></td><td><p>Call the DB maintenance function.</p>
<p>For one file or all files.</p>
<p>Ensure that reccount() function is reasonably accurate.</p>
<p>Despite the name, this doesnt flush any index.</p>
<p><em>return:</em> True or False. See lasterror() for errors.</p>
<ul>
<li>Cannot perform maintenance while a transaction is active.</li>
</ul>
</td></tr>
</td></tr>
<tr><td>if</td><td>conn_or_file.flushindex(filename = "")</td><td><p>Calls DB maintenance function for a file or all files.
</p>
<p>This doesnt actually flush any indexes but does make sure that reccount() function is reasonably accurate.
</p>
<em>Returns:</em> True if successful otherwise false if not and with lasterror() set.</td></tr>
</table>
</table>
<h5 id=Database_File_I/O>Database File I/O</h5>
<h5 id=Database_File_I/O>Database File I/O</h5>
Line 2,098: Line 2,360:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>if</td><td>file.open(dbfilename, connection = "")</td><td><p>Opens a DB file to a var which can be used in subsequent DB function calls to access a specific file using a specific connection.
<tr><td><p><code>if</code></p></td><td><p><code>file.open(dbfilename, dbconn = "")</code></p></td><td><p>Open a DB file.</p>
</p>
<p>To a var which can be used in subsequent DB function calls to access a specific file using a specific connection.</p>
<p><em>connection:</em> If not specified and the filename is present in an internal cache of filenames and connections created by previous calls to open() or attach() then open() returns true. If it is not present in the cache then the default connection will be checked.
<p><em>dbconn:</em> If dbconn is *not* specified, and the filename is present in an internal cache of filenames and connections created by previous calls to open() or attach() then open() returns true. If it is not present in the cache then the default connection will be checked.</p>
</p>
<p><em>return:</em> See lasterror().</p>
<em>Returns:</em> True if the filename was present in the cache OR if the DB connection reports that the file is present.
<dl>
<dt>True</dt><dd>The filename was present in the cache OR the DB connection reports that the file is present.</dd>
<dt>False</dt><dd>The DB connection reports that the file does not exist.</dd>
</dl>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">filename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">filename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="n">file</span><span class="p">.</span><span class="nf">open</span><span class="p">(</span><span class="n">filename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="n">file</span><span class="p">.</span><span class="nf">open</span><span class="p">(</span><span class="n">filename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
Line 2,108: Line 2,374:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">open</span><span class="p">(</span><span class="n">filename</span><span class="w"> </span><span class="ow">to</span><span class="w"> </span><span class="n">file</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">open</span><span class="p">(</span><span class="n">filename</span><span class="w"> </span><span class="ow">to</span><span class="w"> </span><span class="n">file</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>file.close()</td><td><p>Closes DB file var
<tr><td><p><code></code></p></td><td><p><code>file.close()</code></p></td><td><p>Close a DB file.</p>
</p>
<p>Does nothing currently since database file vars consume no resources</p>
Does nothing currently since database file vars consume no resources
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">;</span>
<span class="n">file</span><span class="p">.</span><span class="nf">close</span><span class="p">();</span>
<span class="n">file</span><span class="p">.</span><span class="nf">close</span><span class="p">();</span>
Line 2,117: Line 2,384:
<span class="nf">close</span><span class="p">(</span><span class="n">file</span><span class="p">);</span>
<span class="nf">close</span><span class="p">(</span><span class="n">file</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>file.createindex(fieldname, dictfile = "")</td><td><p>Creates a secondary index for a given DB file and field name.
<tr><td><p><code>if</code></p></td><td><p><code>file.createindex(fieldname, dictfile = "")</code></p></td><td><p>Create a secondary index.</p>
</p>
<p>For a given DB file and field name.</p>
<p>The fieldname must exist in a dictionary file. The default dictionary is "dict." ^ filename.
<p>The fieldname must exist in a dictionary file. The default dictionary is "dict." ^ filename.</p>
</p>
<p><em>return:</em> False if the index cannot be created for any reason. See lasterror().</p>
<p><em>Returns:</em> False if the index cannot be created for any reason.
<ul>
</p>
<li>Index already exists</li>
<p>* Index already exists
<li>File does not exist</li>
</p>
<li>The dictionary file does not have a record with a key of the given field name.</li>
<p>* File does not exist
<li>The dictionary file does not exist. Default is "dict." ^ filename.</li>
</p>
<li>The dictionary field defines a calculated field that uses an exodus function. Using a psql function is OK.</li>
<p>* The dictionary file does not have a record with a key of the given field name.
</ul>
</p>
<p>
<p>* The dictionary file does not exist. Default is "dict." ^ filename.
</p>
* The dictionary field defines a calculated field that uses an exodus function. Using a psql function is OK.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">filename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">fieldname</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;DATE_CREATED&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">filename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">fieldname</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;DATE_CREATED&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">deleteindex</span><span class="p">(</span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;DATE_CREATED&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">{};</span><span class="w"> </span><span class="c1">// Cleanup first</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">deleteindex</span><span class="p">(</span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;DATE_CREATED&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">{};</span><span class="w"> </span><span class="c1">// Cleanup first</span>
Line 2,139: Line 2,404:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">createindex</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span><span class="w"> </span><span class="n">fieldname</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">createindex</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span><span class="w"> </span><span class="n">fieldname</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>file|conn.listindex(file_or_filename = "", fieldname = "")</td><td><p>Lists secondary indexes in a database or for a DB file
<tr><td><p><code>var=</code></p></td><td><p><code>file|dbconn.listindex(file_or_filename = "", fieldname = "")</code></p></td><td><p>List secondary indexes.</p>
</p>
<p>In a database or for a DB file.</p>
<em>Returns:</em> False if the DB file or fieldname are given and do not exist
<p><em>return:</em> An FM separated list.</p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">conn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<ul>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">conn</span><span class="p">.</span><span class="nf">listindex</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">// includes &quot;xo_clients__date_created&quot;</span>
<li>DB file or fieldname does not exist.</li>
</ul>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">dbconn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">dbconn</span><span class="p">.</span><span class="nf">listindex</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">// include &quot;xo_clients__date_created&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">listindex</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">listindex</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>file.deleteindex(fieldname)</td><td><p>Deletes a secondary index for a DB file and field name.
<tr><td><p><code>if</code></p></td><td><p><code>file.deleteindex(fieldname)</code></p></td><td><p>Delete a secondary index.</p>
</p>
<p>For a DB file and field name.</p>
<p><em>Returns:</em> False if the index cannot be deleted for any reason
<p><em>return:</em> False if the index cannot be deleted for any reason. See lasterror().</p>
</p>
<ul>
<p>* File does not exist
<li>File does not exist</li>
</p>
<li>Index does not already exists</li>
* Index does not already exists
</ul>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">fieldname</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;DATE_CREATED&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">fieldname</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;DATE_CREATED&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">file</span><span class="p">.</span><span class="nf">deleteindex</span><span class="p">(</span><span class="n">fieldname</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">file</span><span class="p">.</span><span class="nf">deleteindex</span><span class="p">(</span><span class="n">fieldname</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
Line 2,161: Line 2,433:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">deleteindex</span><span class="p">(</span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">fieldname</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">deleteindex</span><span class="p">(</span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">fieldname</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>file.lock(key)</td><td><p>Places a metaphorical DB lock on a particular record given a DB file and key.
<tr><td><p><code>var=</code></p></td><td><p><code>file.lock(key)</code></p></td><td><p>Place a metaphorical DB lock.</p>
</p>
<p>On a particular record given a DB file and key.</p>
<p>This is a advisory lock, not a physical lock, since it makes no restriction on the access or modification of data by other connections.
<p>This is a advisory lock, not a physical lock, since it makes no restriction on the access or modification of data by other connections.</p>
</p>
<p>Neither the DB file nor the record key need to actually exist since a lock is just a hash of the DB file name and key combined.</p>
<p>Neither the DB file nor the record key need to actually exist since a lock is just a hash of the DB file name and key combined.
<p>If another connection attempts to place an identical lock on the same database it will be denied.</p>
</p>
<p>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.</p>
<p>If another connection attempts to place an identical lock on the same database it will be denied.
<p>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).</p>
</p>
<p>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.</p>
<p>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.
<p><em>Returns:</em> </p>
</p>
<dl>
<p>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).
<dt>0</dt><dd>Failure: Another connection has already placed the same lock.</dd>
</p>
<dt>""</dt><dd>Failure: The lock has already been placed.</dd>
<p>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.
<dt>1</dt><dd>Success: A new lock has been placed.</dd>
</p>
<dt>2</dt><dd>Success: The lock has already been placed and the connection is in a transaction.</dd>
<p><em>Returns:</em>
</dl>
</p>
<p>
<p>* 0: Failure: Another connection has already placed the same lock.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;1000&quot;</span><span class="p">;</span>
</p>
<p>* "" Failure: The lock has already been placed.
</p>
<p>* 1: Success: A new lock has been placed.
</p>
* 2: Success: The lock has already been placed and the connection is in a transaction.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;1000&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">file</span><span class="p">.</span><span class="nf">lock</span><span class="p">(</span><span class="n">key</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">file</span><span class="p">.</span><span class="nf">lock</span><span class="p">(</span><span class="n">key</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">lock</span><span class="p">(</span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">lock</span><span class="p">(</span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>file.unlock(key)</td><td><p>Removes a DB lock placed by the lock function.
<tr><td><p><code>if</code></p></td><td><p><code>file.unlock(key)</code></p></td><td><p>Remove a DB lock.</p>
</p>
<p>A lock placed by the lock function.</p>
<p>Only locks placed on the specified connection can be removed.
<p><em>return:</em> True or False. See lasterror().</p>
</p>
<ul>
<p>Locks cannot be removed while a connection is in a transaction.
<li>Lock cannot be removed while in a transaction.</li>
</p>
<li>Lock is not present in the connection.</li>
<em>Returns:</em> False if the lock is not present in a connection.
</ul>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;1000&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;1000&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">file</span><span class="p">.</span><span class="nf">unlock</span><span class="p">(</span><span class="n">key</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">file</span><span class="p">.</span><span class="nf">unlock</span><span class="p">(</span><span class="n">key</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
Line 2,203: Line 2,471:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">unlock</span><span class="p">(</span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">unlock</span><span class="p">(</span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>file.unlockall()</td><td><p>Removes all DB locks placed by the lock function in the specified connection.
<tr><td><p><code>if</code></p></td><td><p><code>file.unlockall()</code></p></td><td><p>Remove all DB locks.</p>
</p>
<p>All locks placed by the lock function in the specified connection.</p>
Locks cannot be removed while in a transaction.
<p><em>return:</em> True or False. See lasterror().</p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">conn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<ul>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="n">conn</span><span class="p">.</span><span class="nf">unlockall</span><span class="p">())</span><span class="w"> </span><span class="p">...</span>
<li>Locks cannot be removed while in a transaction.</li>
</ul>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">dbconn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="n">dbconn</span><span class="p">.</span><span class="nf">unlockall</span><span class="p">())</span><span class="w"> </span><span class="p">...</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">unlockall</span><span class="p">(</span><span class="n">conn</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">unlockall</span><span class="p">(</span><span class="n">dbconn</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>record.write(file, key)</td><td><p>Writes a record into a DB file given a unique primary key.
<tr><td><p><code></code></p></td><td><p><code>record.write(file, key)</code></p></td><td><p>Write a record into a DB file.</p>
</p>
<p>Given a unique primary key, either inserts a new record or updates an existing record.</p>
<p>Either inserts a new record or updates an existing record.
<p><em>return:</em> Nothing since writes always succeed.</p>
</p>
<p><em>throw:</em> VarDBException if the file does not exist.</p>
<p><em>Returns:</em> Nothing since writes always succeed.
<p>Any memory cached record is deleted.</p>
</p>
<p>
<p><em>Throws:</em> VarDBException if the file does not exist. Like most DB functions.
</p>
Any memory cached record is deleted.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">record</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Client GD^G^20855^30000^1001.00^20855.76539&quot;</span><span class="kt">_var</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">record</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Client GD^G^20855^30000^1001.00^20855.76539&quot;</span><span class="kt">_var</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;GD001&quot;</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;GD001&quot;</span><span class="p">;</span>
Line 2,229: Line 2,500:
<span class="nf">write</span><span class="p">(</span><span class="n">record</span><span class="w"> </span><span class="ow">on</span><span class="w"> </span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">);</span>
<span class="nf">write</span><span class="p">(</span><span class="n">record</span><span class="w"> </span><span class="ow">on</span><span class="w"> </span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>record.read(file, key)</td><td><p>Reads a record from a DB file for a given key.
<tr><td><p><code>if</code></p></td><td><p><code>record.read(file, key)</code></p></td><td><p>Read a record from a DB file.</p>
</p>
<p>Given a unique primary key.</p>
<p><em>file:</em> A DB filename or a var opened to a DB file.
<p><em>file:</em> A DB filename or a var opened to a DB file.</p>
</p>
<p><em>key:</em> The key of the record to be read.</p>
<p><em>key:</em> The key of the record to be read.
<p><em>return:</em> False if the key doesnt exist</p>
</p>
<p><em>var:</em> Contains the record if it exists or is unassigned if not.</p>
<p><em>Returns:</em> False if the key doesnt exist
<p>A special case of the key being "%RECORDS%" results in a fictitious "record" being returned as an FM separated list of all the keys in the DB file up to a maximum size of 4Mib, sorted in natural order.</p>
</p>
<p>
<p><em>var:</em> Contains the record if it exists or is unassigned if not.
</p>
A special case of the key being "%RECORDS%" results in a fictitious "record" being returned as an FM separated list of all the keys in the DB file up to a maximum size of 4Mib, sorted in natural order.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">record</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">record</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;GD001&quot;</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;GD001&quot;</span><span class="p">;</span>
Line 2,247: Line 2,516:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">read</span><span class="p">(</span><span class="n">record</span><span class="w"> </span><span class="ow">from</span><span class="w"> </span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">read</span><span class="p">(</span><span class="n">record</span><span class="w"> </span><span class="ow">from</span><span class="w"> </span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>file.deleterecord(key)</td><td><p>Deletes a record from a DB file given a key.
<tr><td><p><code>if</code></p></td><td><p><code>file.deleterecord(key)</code></p></td><td><p>Delete a record from a DB file.</p>
</p>
<p>Given a unique primary key.</p>
<p><em>Returns:</em> False if the key doesnt exist
<p><em>return:</em> True or False.</p>
</p>
<ul>
<p>Any memory cached record is deleted.
<li>Key doesnt exist.</li>
</p>
</ul>
deleterecord(in file), a one argument free function, is available that deletes multiple records using the currently active select list.
<p>Any memory cached record is deleted.</p>
<p>deleterecord(in file), a one argument free function, is available that deletes multiple records using the currently active select list.</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;GD001&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;GD001&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">file</span><span class="p">.</span><span class="nf">deleterecord</span><span class="p">(</span><span class="n">key</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">file</span><span class="p">.</span><span class="nf">deleterecord</span><span class="p">(</span><span class="n">key</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
Line 2,260: Line 2,532:
<span class="c1">//if (deleterecord(file, key)) ...</span>
<span class="c1">//if (deleterecord(file, key)) ...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>record.insertrecord(file, key)</td><td><p>Inserts a new record in a DB file.
<tr><td><p><code>if</code></p></td><td><p><code>record.insertrecord(file, key)</code></p></td><td><p>Insert a new record in a DB file.</p>
</p>
<p>Given a unique primary key.</p>
<p><em>Returns:</em> False if the key already exists
<p><em>return:</em> True or False.</p>
</p>
<ul>
Any memory cached record is deleted.
<li>Key already exists</li>
</ul>
<p>Any memory cached record is deleted.</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">record</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Client GD^G^20855^30000^1001.00^20855.76539&quot;</span><span class="kt">_var</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">record</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Client GD^G^20855^30000^1001.00^20855.76539&quot;</span><span class="kt">_var</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;GD001&quot;</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;GD001&quot;</span><span class="p">;</span>
Line 2,272: Line 2,548:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">insertrecord</span><span class="p">(</span><span class="n">record</span><span class="w"> </span><span class="ow">on</span><span class="w"> </span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">insertrecord</span><span class="p">(</span><span class="n">record</span><span class="w"> </span><span class="ow">on</span><span class="w"> </span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>record.updaterecord(file, key)</td><td><p>Updates an existing record in a DB file.
<tr><td><p><code>if</code></p></td><td><p><code>record.updaterecord(file, key)</code></p></td><td><p>Update an existing record in a DB file.</p>
</p>
<p>Given a unique primary key.</p>
<p><em>Returns:</em> False if no record with the given key exists.
<p><em>return:</em> True or False.</p>
</p>
<ul>
Any memory cached record is deleted.
<li>Key does not exists</li>
</ul>
<p>Any memory cached record is deleted.</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">record</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Client GD^G^20855^30000^1001.00^20855.76539&quot;</span><span class="kt">_var</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">record</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Client GD^G^20855^30000^1001.00^20855.76539&quot;</span><span class="kt">_var</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;GD001&quot;</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;GD001&quot;</span><span class="p">;</span>
Line 2,284: Line 2,564:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">updaterecord</span><span class="p">(</span><span class="n">record</span><span class="w"> </span><span class="ow">on</span><span class="w"> </span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">updaterecord</span><span class="p">(</span><span class="n">record</span><span class="w"> </span><span class="ow">on</span><span class="w"> </span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>record.updatekey(key, newkey)</td><td><p>Updates the key of an existing record in a DB file.
<tr><td><p><code>if</code></p></td><td><p><code>record.updatekey(key, newkey)</code></p></td><td><p>Update the key of an existing record in a DB file.</p>
</p>
<p>Given two unique primary keys.</p>
<p><em>Returns:</em> True if successful or false if no record with the given key exists, or a record with newkey already exists
<p><em>return:</em> True or False.</p>
</p>
<ul>
Any memory cached records of either key are deleted.
<li>Key does not exists</li>
<li>New key already exists.</li>
</ul>
<p>Any memory cached records of either key are deleted.</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;GD001&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">newkey</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;GD002&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;GD001&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">newkey</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;GD002&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="n">file</span><span class="p">.</span><span class="nf">updatekey</span><span class="p">(</span><span class="n">key</span><span class="p">,</span><span class="w"> </span><span class="n">newkey</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="n">file</span><span class="p">.</span><span class="nf">updatekey</span><span class="p">(</span><span class="n">key</span><span class="p">,</span><span class="w"> </span><span class="n">newkey</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
Line 2,295: Line 2,580:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">updatekey</span><span class="p">(</span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">newkey</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="c1">// Reverse the above change.</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">updatekey</span><span class="p">(</span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">newkey</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="c1">// Reverse the above change.</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>strvar.readf(file, key, fieldno)</td><td>"Read field" Same as read() but only returns a specific field number from the record.
<tr><td><p><code>if</code></p></td><td><p><code>strvar.readf(file, key, fieldno)</code></p></td><td><p>Read a field from a DB file record.</p>
<p>Same as read() but only returns a specific field number from the record.</p>
<p><em>fieldno:</em> The field number to return from the DB record.</p>
<p><em>return:</em> A string var.</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="nf">field</span><span class="p">,</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;GD001&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">fieldno</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="nf">field</span><span class="p">,</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;GD001&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">fieldno</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">field</span><span class="p">.</span><span class="nf">readf</span><span class="p">(</span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">,</span><span class="w"> </span><span class="n">fieldno</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="c1">// field -&gt; &quot;G&quot;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">field</span><span class="p">.</span><span class="nf">readf</span><span class="p">(</span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">,</span><span class="w"> </span><span class="n">fieldno</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="c1">// field -&gt; &quot;G&quot;</span>
Line 2,302: Line 2,592:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">readf</span><span class="p">(</span><span class="nf">field</span><span class="w"> </span><span class="ow">from</span><span class="w"> </span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">,</span><span class="w"> </span><span class="n">fieldno</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">readf</span><span class="p">(</span><span class="nf">field</span><span class="w"> </span><span class="ow">from</span><span class="w"> </span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">,</span><span class="w"> </span><span class="n">fieldno</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>strvar.writef(file, key, fieldno)</td><td>"write field" Same as write() but only writes to a specific field number in the record
<tr><td><p><code></code></p></td><td><p><code>strvar.writef(file, key, fieldno)</code></p></td><td><p>Write a field to a DB file record.</p>
<p>Same as write() but only writes to a specific field number in the record.</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="nf">field</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;f3&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;1000&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">fieldno</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">3</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="nf">field</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;f3&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;1000&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">fieldno</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">3</span><span class="p">;</span>
<span class="nf">field</span><span class="p">.</span><span class="nf">writef</span><span class="p">(</span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">,</span><span class="w"> </span><span class="n">fieldno</span><span class="p">);</span>
<span class="nf">field</span><span class="p">.</span><span class="nf">writef</span><span class="p">(</span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">,</span><span class="w"> </span><span class="n">fieldno</span><span class="p">);</span>
Line 2,309: Line 2,602:
<span class="nf">writef</span><span class="p">(</span><span class="nf">field</span><span class="w"> </span><span class="ow">on</span><span class="w"> </span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">,</span><span class="w"> </span><span class="n">fieldno</span><span class="p">);</span>
<span class="nf">writef</span><span class="p">(</span><span class="nf">field</span><span class="w"> </span><span class="ow">on</span><span class="w"> </span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">,</span><span class="w"> </span><span class="n">fieldno</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>record.writec(file, key)</td><td><p>"Write cache" Writes a record and key into a memory cached "DB file".
<tr><td><p><code></code></p></td><td><p><code>record.writec(file, key)</code></p></td><td><p>Write a record and key into a memory cached "DB file".</p>
</p>
<p>The actual database file is NOT updated.</p>
<p>The actual database file is NOT updated.
<p>writec() either updates an existing cache record if the key already exists or otherwise inserts a new record into the cache.</p>
</p>
<p>It always succeeds so no result code is returned.</p>
<p>writec() either updates an existing cache record if the key already exists or otherwise inserts a new record into the cache.
<p>Neither the DB file nor the record key need to actually exist in the actual DB.</p>
</p>
<p>
<p>It always succeeds so no result code is returned.
</p>
Neither the DB file nor the record key need to actually exist in the actual DB.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">record</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Client XD^X^20855^30000^1001.00^20855.76539&quot;</span><span class="kt">_var</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">record</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Client XD^X^20855^30000^1001.00^20855.76539&quot;</span><span class="kt">_var</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;XD001&quot;</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;XD001&quot;</span><span class="p">;</span>
Line 2,325: Line 2,616:
<span class="nf">writec</span><span class="p">(</span><span class="n">record</span><span class="w"> </span><span class="ow">on</span><span class="w"> </span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">);</span>
<span class="nf">writec</span><span class="p">(</span><span class="n">record</span><span class="w"> </span><span class="ow">on</span><span class="w"> </span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>record.readc(file, key)</td><td><p>"Read cache" Same as "read() but first reads from a memory cache.
<tr><td><p><code>if</code></p></td><td><p><code>record.readc(file, key)</code></p></td><td><p>Read a DB record first looking in a memory cached "DB file".</p>
</p>
<p>Same as "read() but first reads from a memory cache held per connection.</p>
<p>1. Tries to read from a memory cache. Returns true if successful.
<ol>
</p>
<li>Tries to read from a memory cache. Returns true if successful.</li>
<p>2a. Tries to read from the actual DB file and returns false if unsuccessful.
</ol>
</p>
<p>2a. Tries to read from the actual DB file and returns false if unsuccessful.</p>
<p>2b. Writes the record and key to the memory cache and returns true.
<p>2b. Writes the record and key to the memory cache and returns true.</p>
</p>
<p>Cached DB file data lives in exodus process memory and is lost when the process terminates or clearcache() is called.</p>
Cached DB file data lives in exodus process memory and is lost when the process terminates or clearcache() is called.
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">record</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">record</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;XD001&quot;</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;XD001&quot;</span><span class="p">;</span>
Line 2,344: Line 2,636:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">read</span><span class="p">(</span><span class="n">record</span><span class="w"> </span><span class="ow">from</span><span class="w"> </span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">))</span><span class="w"> </span><span class="nf">abort</span><span class="p">(</span><span class="s">&quot;Error: &quot;</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="s">&quot; should not be in the actual database file&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// error</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">read</span><span class="p">(</span><span class="n">record</span><span class="w"> </span><span class="ow">from</span><span class="w"> </span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">))</span><span class="w"> </span><span class="nf">abort</span><span class="p">(</span><span class="s">&quot;Error: &quot;</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="s">&quot; should not be in the actual database file&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// error</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>dbfile.deletec(key)</td><td><p>Deletes a record and key from a memory cached "file".
<tr><td><p><code>if</code></p></td><td><p><code>dbfile.deletec(key)</code></p></td><td><p>Delete a record from a memory cached "DB file".</p>
</p>
<p>The actual database file is NOT updated.</p>
<p>The actual database file is NOT updated.
<p><em>return:</em> False if the key doesnt exist</p>
</p>
<p>
<em>Returns:</em> False if the key doesnt exist
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;XD001&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;XD001&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">file</span><span class="p">.</span><span class="nf">deletec</span><span class="p">(</span><span class="n">key</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">file</span><span class="p">.</span><span class="nf">deletec</span><span class="p">(</span><span class="n">key</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
Line 2,355: Line 2,647:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">deletec</span><span class="p">(</span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">deletec</span><span class="p">(</span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>conn.clearcache()</td><td><p>Clears the memory cache of all records for the given connection
<tr><td><p><code></code></p></td><td><p><code>dbconn.clearcache()</code></p></td><td><p>Clear the "DB file" memory cache.</p>
</p>
<p>All cached records for the given connection.</p>
All future cache readc() function calls will be forced to obtain records from the actual database and refresh the cache.
<p>All future cache readc() function calls will be forced to obtain records from the actual database and refresh the cache.</p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">conn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<p>
<span class="n">conn</span><span class="p">.</span><span class="nf">clearcache</span><span class="p">();</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">dbconn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;exodus&quot;</span><span class="p">;</span>
<span class="n">dbconn</span><span class="p">.</span><span class="nf">clearcache</span><span class="p">();</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">clearcache</span><span class="p">(</span><span class="n">conn</span><span class="p">);</span>
<span class="nf">clearcache</span><span class="p">(</span><span class="n">dbconn</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.xlate(filename, fieldno, mode)</td><td><p>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.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.xlate(filename, fieldno, mode)</code></p></td><td><p>Read a field given filename, key and field number or name.</p>
</p>
<p>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 named columns, functions and multivalued data.</p>
<p><em>Arguments:</em>
<p><em>strvar:</em> The primary key to lookup a field in a given file and field no or field name.</p>
</p>
<p><em>filename:</em> The DB file in which to look up data.</p>
<p>strvar: Used as the primary key to lookup a field in a given file and field no or field name.
<p>If var key is multivalued then a multivalued field is returned.</p>
</p>
<p><em>fieldno:</em> Which field of the record to return.</p>
<p><em>filename:</em> The DB file in which to look up data.
<dl>
</p>
<dt>nn</dt><dd>Field number nn</dd>
<p>If var key is multivalued then a multivalued field is returned.
<dt>0</dt><dd>The key.</dd>
</p>
<dt>""</dt><dd>The whole record.</dd>
<p><em>fieldno:</em> Determines which field of the record is returned.
</dl>
</p>
<p><em>mode:</em> If the record does not exist.</p>
<p>* Integer returns that field number
<dl>
</p>
<dt>"X"</dt><dd>Returns ""</dd>
<p>* 0 means return the key unchanged.
<dt>"C"</dt><dd>Returns the key unconverted.</dd>
</p>
</dl>
<p>* "" means return the whole record.
<p>
</p>
<p><em>mode:</em> Determines what is returned if the record does not exist for the given key and file.
</p>
<p>* "X" returns ""
</p>
* "C" returns the key unconverted.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;SB001&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;SB001&quot;</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">client_name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">key</span><span class="p">.</span><span class="nf">xlate</span><span class="p">(</span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;Client AAA&quot;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">client_name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">key</span><span class="p">.</span><span class="nf">xlate</span><span class="p">(</span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;Client AAA&quot;</span>
Line 2,393: Line 2,682:
<span class="nf">let</span><span class="w"> </span><span class="n">name_and_type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">xlate</span><span class="p">(</span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;NAME_AND_TYPE&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;Client AAA (A)&quot;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">name_and_type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">xlate</span><span class="p">(</span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;NAME_AND_TYPE&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;Client AAA (A)&quot;</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
</table>
</table>
Line 2,399: Line 2,689:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>if</td><td>dbfile.select(sort_select_command = "")</td><td><p>Create an active select list of keys of a database file.
<tr><td><p><code>if</code></p></td><td><p><code>dbfile.select(sort_select_command = "")</code></p></td><td><p>Create an active select list of DB keys.</p>
</p>
<p>The select(command) function searches and orders database records for subsequent processing given an English language-like command.</p>
<p>The select(command) function searches and orders database records for subsequent processing given an English language-like command.
<p>The primary job of a database, beyond mere storage and retrieval of information, is to allow rapid searching and ordering of information on demand.</p>
</p>
<p>In Exodus, searching and ordering of information is known as "sort/select" and is performed by the select() function.</p>
<p>The primary job of a database, beyond mere storage and retrieval of information, is to allow rapid searching and ordering of information on demand.
<p>Executing the select() function creates an "active select list" which can then be consumed by the readnext() function.</p>
</p>
<p><em>dbfile:</em> A opened database file or file name, or an open connection or an empty var for default connections. Subsequent readnext calls must use the same.</p>
<p>In Exodus, searching and ordering of information is known as "sort/select" and is performed by the select() function.
<p><em>sort_select_command:</em> A natural language command using dictionary field names. The command can be blank if a dbfile or filename is given in dbfile or just a file name and all keys will be selected in undefined order.</p>
</p>
<p><em>Example:</em> "select xo_clients with type 'B' and with balance ge 100 by type by name"</p>
<p>Executing the select() function creates an "active select list" which can then be consumed by the readnext() function.
<p><em>Option:</em> "(R)" appended to the sort_select_command acquires the database records as well.</p>
</p>
<p><em>return:</em> True if any records are selected or false if none.</p>
<p><em>dbfile:</em> A opened database file or file name, or an open connection or an empty var for default connections. Subsequent readnext calls must use the same.
<p><em>throw:</em> VarDBException in case of any syntax error in the command.</p>
</p>
<p>Active select lists created using var.select()'s member function syntax cannot be consumed by the free function form of readnext() and vice versa.</p>
<p><em>sort_select_command:</em> A natural language command using dictionary field names. The command can be blank if a dbfile or filename is given in dbfile or just a file name and all keys will be selected in undefined order.
<p>
</p>
<p><em>Example:</em> "select xo_clients with type 'B' and with balance ge 100 by type by name"
</p>
<p><em>Option:</em> "(R)" appended to the sort_select_command acquires the database records as well.
</p>
<p><em>Returns:</em> True if any records are selected or false if none.
</p>
<p><em>Throws:</em> VarDBException in case of any syntax error in the command.
</p>
Active select lists created using var.select()'s member function syntax cannot be consumed by the free function form of readnext() and vice versa.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">clients</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">clients</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">clients</span><span class="p">.</span><span class="nf">select</span><span class="p">(</span><span class="s">&quot;with type &#39;B&#39; and with balance ge 100 by type by name&quot;</span><span class="p">))</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">clients</span><span class="p">.</span><span class="nf">select</span><span class="p">(</span><span class="s">&quot;with type &#39;B&#39; and with balance ge 100 by type by name&quot;</span><span class="p">))</span>
<span class="w">    </span><span class="k">while</span><span class="w"> </span><span class="p">(</span><span class="n">clients</span><span class="p">.</span><span class="nf">readnext</span><span class="p">(</span><span class="n">ID</span><span class="p">))</span>
<span class="w">    </span><span class="k">while</span><span class="w"> </span><span class="p">(</span><span class="n">clients</span><span class="p">.</span><span class="nf">readnext</span><span class="p">(</span><span class="kc">ID</span><span class="p">))</span>
<span class="w">        </span><span class="nf">println</span><span class="p">(</span><span class="s">&quot;Client code is {}&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">ID</span><span class="p">);</span>
<span class="w">        </span><span class="nf">println</span><span class="p">(</span><span class="s">&quot;Client code is {}&quot;</span><span class="p">,</span><span class="w"> </span><span class="kc">ID</span><span class="p">);</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">select</span><span class="p">(</span><span class="s">&quot;xo_clients with type &#39;B&#39; and with balance ge 100 by type by name&quot;</span><span class="p">))</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">select</span><span class="p">(</span><span class="s">&quot;xo_clients with type &#39;B&#39; and with balance ge 100 by type by name&quot;</span><span class="p">))</span>
<span class="w">    </span><span class="k">while</span><span class="w"> </span><span class="p">(</span><span class="nf">readnext</span><span class="p">(</span><span class="n">ID</span><span class="p">))</span>
<span class="w">    </span><span class="k">while</span><span class="w"> </span><span class="p">(</span><span class="nf">readnext</span><span class="p">(</span><span class="kc">ID</span><span class="p">))</span>
<span class="w">        </span><span class="nf">println</span><span class="p">(</span><span class="s">&quot;Client code is {}&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">ID</span><span class="p">);</span>
<span class="w">        </span><span class="nf">println</span><span class="p">(</span><span class="s">&quot;Client code is {}&quot;</span><span class="p">,</span><span class="w"> </span><span class="kc">ID</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>dbfile.selectkeys(keys)</td><td><p>Create an active select list from a string of keys.
<tr><td><p><code>if</code></p></td><td><p><code>dbfile.selectkeys(keys)</code></p></td><td><p>Create an active select list from a string of DB keys.</p>
</p>
<p>Similar to select() but creates the list directly from a var.</p>
<p>Similar to select() but creates the list directly from a var.
<p><em>keys:</em> An FM separated list of keys or key^VM^valueno pairs.</p>
</p>
<p><em>return:</em> True if any keys are provided or false if not.</p>
<p><em>keys:</em> An FM separated list of keys or key^VM^valueno pairs.
<p>
</p>
<em>Returns:</em> True if any keys are provided or false if not.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">dbfile</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">dbfile</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;&quot;</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">keys</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;A01^B02^C03&quot;</span><span class="kt">_var</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">keys</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;A01^B02^C03&quot;</span><span class="kt">_var</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">dbfile</span><span class="p">.</span><span class="nf">selectkeys</span><span class="p">(</span><span class="n">keys</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">dbfile</span><span class="p">.</span><span class="nf">selectkeys</span><span class="p">(</span><span class="n">keys</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="n">assert</span><span class="p">(</span><span class="n">dbfile</span><span class="p">.</span><span class="nf">readnext</span><span class="p">(</span><span class="n">ID</span><span class="p">)</span><span class="w"> </span><span class="ow">and</span><span class="w"> </span><span class="n">ID</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="s">&quot;A01&quot;</span><span class="p">);</span>
<span class="n">assert</span><span class="p">(</span><span class="n">dbfile</span><span class="p">.</span><span class="nf">readnext</span><span class="p">(</span><span class="kc">ID</span><span class="p">)</span><span class="w"> </span><span class="ow">and</span><span class="w"> </span><span class="kc">ID</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="s">&quot;A01&quot;</span><span class="p">);</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">selectkeys</span><span class="p">(</span><span class="n">keys</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">selectkeys</span><span class="p">(</span><span class="n">keys</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="n">assert</span><span class="p">(</span><span class="nf">readnext</span><span class="p">(</span><span class="n">ID</span><span class="p">)</span><span class="w"> </span><span class="ow">and</span><span class="w"> </span><span class="n">ID</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="s">&quot;A01&quot;</span><span class="p">);</span>
<span class="n">assert</span><span class="p">(</span><span class="nf">readnext</span><span class="p">(</span><span class="kc">ID</span><span class="p">)</span><span class="w"> </span><span class="ow">and</span><span class="w"> </span><span class="kc">ID</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="s">&quot;A01&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>dbfile.hasnext()</td><td><p>Checks if a select list is active.
<tr><td><p><code>if</code></p></td><td><p><code>dbfile.hasnext()</code></p></td><td><p>Check if a select list is active.</p>
</p>
<p><em>dbfile:</em> A file or connection var used in a prior select, selectkeys or getlist function call.</p>
<p><em>dbfile:</em> A file or connection var used in a prior select, selectkeys or getlist function call.
<p><em>return:</em> True if a select list is active and false if not.</p>
</p>
<p>If it returns true then a call to readnext() will return a database record key, otherwise not.</p>
<p><em>Returns:</em> True if a select list is active and false if not.
<p>
</p>
If it returns true then a call to readnext() will return a database record key, otherwise not.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">clients</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">clients</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">clients</span><span class="p">.</span><span class="nf">select</span><span class="p">())</span><span class="w"> </span><span class="p">{</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">clients</span><span class="p">.</span><span class="nf">select</span><span class="p">())</span><span class="w"> </span><span class="p">{</span>
Line 2,464: Line 2,742:
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>dbfile.readnext(out key)</td><td><p>Acquires and consumes one key from an active select list of database record keys.
<tr><td><p><code>if</code></p></td><td><p><code>dbfile.readnext(out key)</code></p></td><td><p>Acquire and consume one key from an active select list.</p>
</p>
<p>Each call to readnext consumes one key from the list.</p>
<p><em>dbfile:</em> A file or connection var used in a prior select, selectkeys or getlist function call.
<p>Once all the keys in an active select list have been consumed by calls to readnext, the list becomes inactive.</p>
</p>
<p>See select() for example code.</p>
<p><em>key:</em> Returns the first (next) key present in an active select list or "" if no select list is active.
<p><em>dbfile:</em> A file or connection var used in a prior select, selectkeys or getlist function call.</p>
</p>
<p><em>key[out]:</em> Returns the first (next) key present in an active select list or "" if no select list is active.</p>
<p><em>Returns:</em> True if a list is active and a key is available, false if not.
<p><em>return:</em> True if a list was active and a key was acquired, false if not.</p>
</p>
<p>Each call to readnext consumes one key from the list.
</p>
<p>Once all the keys in an active select list have been consumed by calls to readnext, the list becomes inactive.
</p>
<p>See select() for example code.
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>dbfile.readnext(out key, out valueno)</td><td><p>Similar to readnext(key) but multivalued.
<tr><td><p><code>if</code></p></td><td><p><code>dbfile.readnext(out key, out valueno)</code></p></td><td><p>Acquire and consume one key and valueno pair from an active select list.</p>
</p>
<p>Similar to readnext(key) but multivalued.</p>
<p>If the active list was ordered by multivalued database fields then pairs of key and multivalue number will be available to the readnext function.
<p>If the active list was ordered by multivalued database fields then pairs of key and multivalue number will be available to the readnext function.</p>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>dbfile.readnext(out record, out key, out valueno)</td><td><p>Similar to readnext(key) but acquires the database record as well.
<tr><td><p><code>if</code></p></td><td><p><code>dbfile.readnext(out record, out key, out valueno)</code></p></td><td><p>Similar to readnext(key, valueno) but acquire the database record as well.</p>
</p>
<p><em>record[out]:</em> Returns the next database record from the select list assuming that the select list was created with the (R) option otherwise "" if not.</p>
<p><em>record:</em> Returns the next database record from the select list assuming that the select list was created with the (R) option otherwise "" if not.
<p><em>key[out]:</em> Returns the next database record key in the select list.</p>
</p>
<p><em>valueno[out]:</em> The multivalue number if the select list was ordered on multivalued database record fields or 1 if not.</p>
<p><em>key:</em> Returns the next database record key in the select list.
<p><em>return:</em> True if a list was active and a key was acquired, false if not.</p>
</p>
<p>
<em>valueno:</em> The multivalue number if the select list was ordered on multivalued database record fields or 1 if not.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">clients</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">clients</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">clients</span><span class="p">.</span><span class="nf">select</span><span class="p">(</span><span class="s">&quot;with type &#39;B&#39; and with balance ge 100 by type by name (R)&quot;</span><span class="p">))</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">clients</span><span class="p">.</span><span class="nf">select</span><span class="p">(</span><span class="s">&quot;with type &#39;B&#39; and with balance ge 100 by type by name (R)&quot;</span><span class="p">))</span>
<span class="w">    </span><span class="k">while</span><span class="w"> </span><span class="p">(</span><span class="n">clients</span><span class="p">.</span><span class="nf">readnext</span><span class="p">(</span><span class="n">RECORD</span><span class="p">,</span><span class="w"> </span><span class="n">ID</span><span class="p">,</span><span class="w"> </span><span class="n">MV</span><span class="p">))</span>
<span class="w">    </span><span class="k">while</span><span class="w"> </span><span class="p">(</span><span class="n">clients</span><span class="p">.</span><span class="nf">readnext</span><span class="p">(</span><span class="kc">RECORD</span><span class="p">,</span><span class="w"> </span><span class="kc">ID</span><span class="p">,</span><span class="w"> </span><span class="kc">MV</span><span class="p">))</span>
<span class="w">        </span><span class="nf">println</span><span class="p">(</span><span class="s">&quot;Code is {}, Name is {}&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">ID</span><span class="p">,</span><span class="w"> </span><span class="n">RECORD</span><span class="p">.</span><span class="nf">f</span><span class="p">(</span><span class="mi">1</span><span class="p">));</span>
<span class="w">        </span><span class="nf">println</span><span class="p">(</span><span class="s">&quot;Code is {}, Name is {}&quot;</span><span class="p">,</span><span class="w"> </span><span class="kc">ID</span><span class="p">,</span><span class="w"> </span><span class="kc">RECORD</span><span class="p">.</span><span class="nf">f</span><span class="p">(</span><span class="mi">1</span><span class="p">));</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="n">DICT</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;dict.xo_clients&quot;</span><span class="p">;</span>
<span class="kc">DICT</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;dict.xo_clients&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">select</span><span class="p">(</span><span class="s">&quot;xo_clients with type &#39;B&#39; and with balance ge 100 by type by name (R)&quot;</span><span class="p">))</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">select</span><span class="p">(</span><span class="s">&quot;xo_clients with type &#39;B&#39; and with balance ge 100 by type by name (R)&quot;</span><span class="p">))</span>
<span class="w">    </span><span class="k">while</span><span class="w"> </span><span class="p">(</span><span class="nf">readnext</span><span class="p">(</span><span class="n">RECORD</span><span class="p">,</span><span class="w"> </span><span class="n">ID</span><span class="p">,</span><span class="w"> </span><span class="n">MV</span><span class="p">))</span>
<span class="w">    </span><span class="k">while</span><span class="w"> </span><span class="p">(</span><span class="nf">readnext</span><span class="p">(</span><span class="kc">RECORD</span><span class="p">,</span><span class="w"> </span><span class="kc">ID</span><span class="p">,</span><span class="w"> </span><span class="kc">MV</span><span class="p">))</span>
<span class="w">        </span><span class="nf">println</span><span class="p">(</span><span class="s">&quot;Code is {}, Name is {}&quot;</span><span class="p">,</span><span class="w"> </span><span class="nf">calculate</span><span class="p">(</span><span class="s">&quot;CODE&quot;</span><span class="p">),</span><span class="w"> </span><span class="nf">calculate</span><span class="p">(</span><span class="s">&quot;NAME&quot;</span><span class="p">));</span>
<span class="w">        </span><span class="nf">println</span><span class="p">(</span><span class="s">&quot;Code is {}, Name is {}&quot;</span><span class="p">,</span><span class="w"> </span><span class="nf">calculate</span><span class="p">(</span><span class="s">&quot;CODE&quot;</span><span class="p">),</span><span class="w"> </span><span class="nf">calculate</span><span class="p">(</span><span class="s">&quot;NAME&quot;</span><span class="p">));</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>dbfile.clearselect()</td><td><p>Deactivates an active select list.
<tr><td><p><code></code></p></td><td><p><code>dbfile.clearselect()</code></p></td><td><p>Deactivate an active select list.</p>
</p>
<p><em>dbfile:</em> A file or connection var used in a prior select, selectkeys or getlist function call.</p>
<p><em>dbfile:</em> A file or connection var used in a prior select, selectkeys or getlist function call.
<p><em>return:</em> Nothing</p>
</p>
<p>Has no effect if no select list is active for dbfile.</p>
<p><em>Returns:</em> Nothing
<p>
</p>
Has no effect if no select list is active for dbfile.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">clients</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">clients</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">;</span>
<span class="n">clients</span><span class="p">.</span><span class="nf">clearselect</span><span class="p">();</span>
<span class="n">clients</span><span class="p">.</span><span class="nf">clearselect</span><span class="p">();</span>
Line 2,517: Line 2,786:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">hasnext</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">hasnext</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>dbfile.savelist(listname)</td><td><p>Stores an active select list for later retrieval.
<tr><td><p><code>if</code></p></td><td><p><code>dbfile.savelist(listname)</code></p></td><td><p>Save an active select list for later retrieval.</p>
</p>
<p><em>dbfile:</em> A file or connection var used in a prior select, selectkeys or getlist function call.</p>
<p><em>dbfile:</em> A file or connection var used in a prior select, selectkeys or getlist function call.
<p><em>listname:</em> A suitable name that will be required for later retrieval.</p>
</p>
<p><em>return:</em> True if saved successfully or false if there was no active list to be saved.</p>
<p><em>listname:</em> A suitable name that will be required for later retrieval.
<p>Any existing list with the same name will be overwritten.</p>
</p>
<p>Only the remaining unconsumed part of the active select list is saved.</p>
<p><em>Returns:</em> True if saved successfully or false if there was no active list to be saved.
<p>Saved lists are stand-alone and are not tied to specific database files although they usually hold keys related to specific files.</p>
</p>
<p>Saved lists can be created from one file and used to access another.</p>
<p>Any existing list with the same name will be overwritten.
<p>savelist() merely writes an FM separated string of keys as a record in the "lists" database file using the list name as the key of the record.</p>
</p>
<p>If a saved list is very long, additional blocks of keys for the same list may be stored with keys like listname*2, listname*3 etc.</p>
<p>Only the remaining unconsumed part of the active select list is saved.
<p>Select lists saved in the lists database file may be created, deleted and listed like database records in any other database file.</p>
</p>
<p>
<p>Saved lists are stand-alone and are not tied to specific database files although they usually hold keys related to specific files.
</p>
<p>Saved lists can be created from one file and used to access another.
</p>
<p>savelist() merely writes an FM separated string of keys as a record in the "lists" database file using the list name as the key of the record.
</p>
<p>If a saved list is very long, additional blocks of keys for the same list may be stored with keys like listname*2, listname*3 etc.
</p>
Select lists saved in the lists database file may be created, deleted and listed like database records in any other database file.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">clients</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">clients</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">clients</span><span class="p">.</span><span class="nf">select</span><span class="p">(</span><span class="s">&quot;with type &#39;B&#39; by name&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">{</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">clients</span><span class="p">.</span><span class="nf">select</span><span class="p">(</span><span class="s">&quot;with type &#39;B&#39; by name&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">{</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">select</span><span class="p">(</span><span class="s">&quot;xo_clients with type &#3#39;B&#39; by name&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">{</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">select</span><span class="p">(</span><span class="s">&quot;xo_clients with type &#39;B&#39; by name&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">savelist</span><span class="p">(</span><span class="s">&quot;mylist&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="w">    </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">savelist</span><span class="p">(</span><span class="s">&quot;mylist&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>dbfile.getlist(listname)</td><td><p>Retrieve and reactivate a saved select list.
<tr><td><p><code>if</code></p></td><td><p><code>dbfile.getlist(listname)</code></p></td><td><p>Retrieve and reactivate a saved select list.</p>
</p>
<p><em>dbfile:</em> A file or connection var to be used by subsequent readnext function calls.</p>
<p><em>dbfile:</em> A file or connection var to be used by subsequent readnext function calls.
<p><em>listname:</em> The name of an existing list in the "lists" database file, either created by savelist or manually.</p>
</p>
<p><em>return:</em> True if the list was successfully retrieved and activated, or false if the list name doesnt exist.</p>
<p><em>listname:</em> The name of an existing list in the "lists" database file, either created by savelist or manually.
<p>Any currently active select list is replaced.</p>
</p>
<p>Retrieving a list does not delete it and a list can be retrieved more than once until specifically deleted.</p>
<p><em>Returns:</em> True if the list was successfully retrieved and activated, or false if the list name doesnt exist.
<p>
</p>
<p>Any currently active select list is replaced.
</p>
Retrieving a list does not delete it and a list can be retrieved more than once until specifically deleted.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">file</span><span class="p">.</span><span class="nf">getlist</span><span class="p">(</span><span class="s">&quot;mylist&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">{</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">file</span><span class="p">.</span><span class="nf">getlist</span><span class="p">(</span><span class="s">&quot;mylist&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="k">while</span><span class="w"> </span><span class="p">(</span><span class="n">file</span><span class="p">.</span><span class="nf">readnext</span><span class="p">(</span><span class="n">ID</span><span class="p">))</span>
<span class="w">    </span><span class="k">while</span><span class="w"> </span><span class="p">(</span><span class="n">file</span><span class="p">.</span><span class="nf">readnext</span><span class="p">(</span><span class="kc">ID</span><span class="p">))</span>
<span class="w">        </span><span class="nf">println</span><span class="p">(</span><span class="s">&quot;Key is {}&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">ID</span><span class="p">);</span>
<span class="w">        </span><span class="nf">println</span><span class="p">(</span><span class="s">&quot;Key is {}&quot;</span><span class="p">,</span><span class="w"> </span><span class="kc">ID</span><span class="p">);</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">getlist</span><span class="p">(</span><span class="s">&quot;mylist&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">{</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">getlist</span><span class="p">(</span><span class="s">&quot;mylist&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="k">while</span><span class="w"> </span><span class="p">(</span><span class="nf">readnext</span><span class="p">(</span><span class="n">ID</span><span class="p">))</span>
<span class="w">    </span><span class="k">while</span><span class="w"> </span><span class="p">(</span><span class="nf">readnext</span><span class="p">(</span><span class="kc">ID</span><span class="p">))</span>
<span class="w">        </span><span class="nf">println</span><span class="p">(</span><span class="s">&quot;Key is {}&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">ID</span><span class="p">);</span>
<span class="w">        </span><span class="nf">println</span><span class="p">(</span><span class="s">&quot;Key is {}&quot;</span><span class="p">,</span><span class="w"> </span><span class="kc">ID</span><span class="p">);</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>dbfile.deletelist(listname)</td><td><p>Delete a saved select list.
<tr><td><p><code>if</code></p></td><td><p><code>dbfile.deletelist(listname)</code></p></td><td><p>Delete a saved select list.</p>
</p>
<p><em>dbfile:</em> A file or connection to the desired database.</p>
<p><em>dbfile:</em> A file or connection to the desired database.
<p><em>listname:</em> The name of an existing list in the "lists" database file.</p>
</p>
<p><em>return:</em> True if successful or false if the list name doesnt exist.</p>
<p><em>listname:</em> The name of an existing list in the "lists" database file.
<p>
</p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">dbconn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;&quot;</span><span class="p">;</span>
<em>Returns:</em> True if successful or false if the list name doesnt exist.
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">dbconn</span><span class="p">.</span><span class="nf">deletelist</span><span class="p">(</span><span class="s">&quot;mylist&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">conn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">conn</span><span class="p">.</span><span class="nf">deletelist</span><span class="p">(</span><span class="s">&quot;mylist&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">deletelist</span><span class="p">(</span><span class="s">&quot;mylist&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">deletelist</span><span class="p">(</span><span class="s">&quot;mylist&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
</table>
</table>
Line 2,589: Line 2,847:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>var=</td><td>var::date()</td><td><p>A date in internal format.
<tr><td><p><code>var=</code></p></td><td><p><code>var::date()</code></p></td><td><p>Get the current date in internal format.</p>
</p>
<p>Internal format is the number of whole days since pick epoch 1967-12-31 00:00:00 UTC. Dates prior to that are numbered negatively.</p>
<p>Internal format is the number of whole days since pick epoch 1967-12-31 00:00:00 UTC. Dates prior to that are numbered negatively.
<p><em>return:</em> A number. e.g. 20821 represents 2025-01-01 00:00:00 UTC for 24 hours.</p>
</p>
<p>
<em>Returns:</em> A number. e.g. 20821 represents 2025-01-01 00:00:00 UTC for 24 hours.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">today1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">date</span><span class="p">();</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">today1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">date</span><span class="p">();</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">today2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">date</span><span class="p">();</span>
<span class="nf">let</span><span class="w"> </span><span class="n">today2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">date</span><span class="p">();</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>var::time()</td><td><p>Number of whole seconds since last 00:00:00 (UTC).
<tr><td><p><code>var=</code></p></td><td><p><code>var::time()</code></p></td><td><p>Get the current time in internal format.</p>
</p>
<p>Internal time is the number of whole seconds since the last midnight 00:00:00 (UTC).</p>
<em>Returns:</em> A number in the range 0 - 86399 since there are 24*60*60 seconds in a day. e.g. 43200 if time is 12:00:00
<p><em>return:</em> A number in the range 0 - 86399 since there are 24*60*60 seconds in a day. e.g. 43200 if time is 12:00:00</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">now1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">time</span><span class="p">();</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">now1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">time</span><span class="p">();</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">now2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">time</span><span class="p">();</span>
<span class="nf">let</span><span class="w"> </span><span class="n">now2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">time</span><span class="p">();</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>var::ostime()</td><td><p>Number of fractional seconds since last 00:00:00 (UTC).
<tr><td><p><code>var=</code></p></td><td><p><code>var::ostime()</code></p></td><td><p>Get the current time in high resolution internal format.</p>
</p>
<p>High resolution internal time is the number of fractional seconds since the last midnight 00:00:00 (UTC).</p>
<p><em>Returns:</em> A floating point with approx. nanosecond resolution depending on hardware.
<p><em>return:</em> A floating point with approx. nanosecond resolution depending on hardware.</p>
</p>
<p>e.g. 23343.704387955 approx. 06:29:03 UTC</p>
e.g. 23343.704387955 approx. 06:29:03 UTC
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">now1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">ostime</span><span class="p">();</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">now1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">ostime</span><span class="p">();</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">now2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ostime</span><span class="p">();</span>
<span class="nf">let</span><span class="w"> </span><span class="n">now2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ostime</span><span class="p">();</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>var::ostimestamp()</td><td><p>Number of fractional days since pick epoch 1967-12-31 00:00:00 UTC. Negative for dates before.
<tr><td><p><code>var=</code></p></td><td><p><code>var::ostimestamp()</code></p></td><td><p>Get the current timestamp in internal format.</p>
</p>
<p>Internal timestamp is the number of fractional days since pick epoch 1967-12-31 00:00:00 UTC. Negative for dates before.</p>
<p><em>Returns:</em> A floating point with approx. nanosecond resolution depending on hardware.
<p><em>return:</em> A floating point with approx. nanosecond resolution depending on hardware.</p>
</p>
<p>e.g. Was 20821.99998842593 around 2025-01-01 23:59:59 UTC</p>
e.g. Was 20821.99998842593 around 2025-01-01 23:59:59 UTC
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">now1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">ostimestamp</span><span class="p">();</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">now1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">ostimestamp</span><span class="p">();</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">now2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ostimestamp</span><span class="p">();</span>
<span class="nf">let</span><span class="w"> </span><span class="n">now2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ostimestamp</span><span class="p">();</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>vardate.ostimestamp(ostime)</td><td><p>Get a timestamp for a given date and time
<tr><td><p><code>var=</code></p></td><td><p><code>vardate.ostimestamp(ostime)</code></p></td><td><p>Get the timestamp for a given date and time</p>
</p>
<p><em>vardate:</em> Internal date from date(), iconv("D") etc.</p>
<p><em>vardate:</em> Internal date from date(), iconv("D") etc.
<p><em>ostime:</em> Internal time from time(), ostime(), iconv("MT") etc.</p>
</p>
<p>
<em>ostime:</em> Internal time from time(), ostime(), iconv("MT") etc.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">idate</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">iconv</span><span class="p">(</span><span class="s">&quot;2025-01-01&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;D&quot;</span><span class="p">),</span><span class="w"> </span><span class="n">itime</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">iconv</span><span class="p">(</span><span class="s">&quot;23:59:59&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;MT&quot;</span><span class="p">);</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">idate</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">iconv</span><span class="p">(</span><span class="s">&quot;2025-01-01&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;D&quot;</span><span class="p">),</span><span class="w"> </span><span class="n">itime</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">iconv</span><span class="p">(</span><span class="s">&quot;23:59:59&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;MT&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">ts1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">idate</span><span class="p">.</span><span class="nf">ostimestamp</span><span class="p">(</span><span class="n">itime</span><span class="p">);</span><span class="w"> </span><span class="c1">// 20821.99998842593</span>
<span class="nf">let</span><span class="w"> </span><span class="n">ts1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">idate</span><span class="p">.</span><span class="nf">ostimestamp</span><span class="p">(</span><span class="n">itime</span><span class="p">);</span><span class="w"> </span><span class="c1">// 20821.99998842593</span>
Line 2,637: Line 2,898:
<span class="nf">let</span><span class="w"> </span><span class="n">ts2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ostimestamp</span><span class="p">(</span><span class="n">idate</span><span class="p">,</span><span class="w"> </span><span class="n">itime</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">ts2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ostimestamp</span><span class="p">(</span><span class="n">idate</span><span class="p">,</span><span class="w"> </span><span class="n">itime</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>var::ossleep(milliseconds)</td><td><p>Sleep/pause/wait
<tr><td><p><code></code></p></td><td><p><code>var::ossleep(milliseconds)</code></p></td><td><p>Sleep/pause/wait</p>
</p>
<p><em>milliseconds:</em> How to long to sleep.</p>
<p><em>milliseconds:</em> How to long to sleep.
<p>Release the processor if not needed for a period of time or a delay is required.</p>
</p>
<p>
Releases the processor if not needed for a period of time or a delay is required.
<div class="highlight light"><pre><span class="kt">var</span><span class="o">::</span><span class="nf">ossleep</span><span class="p">(</span><span class="mi">100</span><span class="p">);</span><span class="w"> </span><span class="c1">// sleep for 100ms</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="o">::</span><span class="nf">ossleep</span><span class="p">(</span><span class="mi">100</span><span class="p">);</span><span class="w"> </span><span class="c1">// sleep for 100ms</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">ossleep</span><span class="p">(</span><span class="mi">100</span><span class="p">);</span>
<span class="nf">ossleep</span><span class="p">(</span><span class="mi">100</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>file_dir_list.oswait(milliseconds)</td><td><p>Sleep/pause/wait up for a file system event
<tr><td><p><code>var=</code></p></td><td><p><code>file_dir_list.oswait(milliseconds)</code></p></td><td><p>Sleep/pause/wait up for a file system event</p>
</p>
<p><em>file_dir_list:</em> An FM delimited list of OS files and/or dirs to monitor.</p>
<p><em>file_dir_list:</em> An FM delimited list of OS files and/or dirs to monitor.
<p><em>milliseconds:</em> How long to wait. Any terminal input (e.g. a key press) will also terminate the wait.</p>
</p>
<p><em>return:</em> An FM array of event information is returned. See below.</p>
<p><em>milliseconds:</em> How long to wait. Any terminal input (e.g. a key press) will also terminate the wait.
<p>Multiple events may be captured and are returned in multivalues.</p>
</p>
<p>
<p><em>Returns:</em> An FM array of event information is returned. See below.
</p>
<p>Multiple events may be captured and are returned in multivalues.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;.^/etc/hosts&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">oswait</span><span class="p">(</span><span class="mi">100</span><span class="p">);</span><span class="w"> </span><span class="c1">/// e.g. &quot;IN_CLOSE_WRITE^/etc^hosts^f&quot;_var</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;.^/etc/hosts&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">oswait</span><span class="p">(</span><span class="mi">100</span><span class="p">);</span><span class="w"> </span><span class="c1">/// e.g. &quot;IN_CLOSE_WRITE^/etc^hosts^f&quot;_var</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">oswait</span><span class="p">(</span><span class="s">&quot;.^/etc/hosts&quot;</span><span class="kt">_var</span><span class="p">,</span><span class="w"> </span><span class="mi">100</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">oswait</span><span class="p">(</span><span class="s">&quot;.^/etc/hosts&quot;</span><span class="kt">_var</span><span class="p">,</span><span class="w"> </span><span class="mi">100</span><span class="p">);</span>
</pre></div>
</pre></div>
Returned dynamic array fields:
</p>
<p># Event type codes
</p>
<p># dirpaths
</p>
<p># filenames
</p>
<p># d=dir, f=file
</p>
<p>Possible event type codes:
</p>
<p>* IN_CLOSE_WRITE - A file opened for writing was closed
</p>
<p>* IN_ACCESS      - Data was read from file
</p>
<p>* IN_MODIFY      - Data was written to file
</p>
<p>* IN_ATTRIB      - File attributes changed
</p>
<p>* IN_CLOSE      - File was closed (read or write)
</p>
<p>* IN_MOVED_FROM  - File was moved away from watched directory
</p>
<p>* IN_MOVED_TO    - File was moved into watched directory
</p>
<p>* IN_MOVE        - File was moved (in or out of directory)
</p>
<p>* IN_CREATE      - A file was created in the directory
</p>
<p>* IN_DELETE      - A file was deleted from the directory
</p>
<p>* IN_DELETE_SELF - Directory or file under observation was deleted
</p>
<p>* IN_MOVE_SELF  - Directory or file under observation was moved
</p>
</p>
<p></p>
<p>Returned dynamic array fields:</p>
<ol>
<li>Event type codes</li>
<li>dirpaths</li>
<li>filenames</li>
<li>d=dir, f=file</li>
</ol>
<p></p>
<p>Possible event type codes:</p>
<dl>
<dt>IN_CLOSE_WRITE</dt><dd>A file opened for writing was closed</dd>
<dt>IN_ACCESS</dt><dd>Data was read from file</dd>
<dt>IN_MODIFY</dt><dd>Data was written to file</dd>
<dt>IN_ATTRIB</dt><dd>File attributes changed</dd>
<dt>IN_CLOSE</dt><dd>File was closed (read or write)</dd>
<dt>IN_MOVED_FROM</dt><dd>File was moved away from watched directory</dd>
<dt>IN_MOVED_TO</dt><dd>File was moved into watched directory</dd>
<dt>IN_MOVE</dt><dd>File was moved (in or out of directory)</dd>
<dt>IN_CREATE</dt><dd>A file was created in the directory</dd>
<dt>IN_DELETE</dt><dd>A file was deleted from the directory</dd>
<dt>IN_DELETE_SELF</dt><dd>Directory or file under observation was deleted</dd>
<dt>IN_MOVE_SELF</dt><dd>Directory or file under observation was moved</dd>
</dl>
</td></tr>
</td></tr>
</table>
</table>
Line 2,704: Line 2,951:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>if</td><td>osfilevar.osopen(osfilename, utf8 = true)</td><td><p>Opens an OS file handle for random read and write operations.
<tr><td><p><code>if</code></p></td><td><p><code>osfilevar.osopen(osfilename, utf8 = true)</code></p></td><td><p>Open an OS file handle.</p>
</p>
<p>Allow random read and write operations.</p>
<p><em>osfilevar:</em> [out] Handle for subsequent osbread() and osbwrite() calls.
<p>Open for writing if possible, otherwise read-only.</p>
</p>
<p><em>osfilevar[out]:</em> Handle for subsequent osbread() and osbwrite() calls.</p>
<p><em>osfilename:</em> Path and name of an existing OS file.
<p><em>osfilename:</em> Path and name of an existing OS file.</p>
</p>
<p><em>utf8:</em> True (default) removes partial UTF-8 sequences from osbread() ends; false returns raw data.</p>
<p><em>utf8:</em> True (default) removes partial UTF-8 sequences from osbread() ends; false returns raw data.
<p><em>return:</em> True if opened successfully, false if file doesn’t exist or isn’t accessible.</p>
</p>
<p>
<p><em>Returns:</em> True if opened successfully, false if file doesn’t exist or isn’t accessible.
</p>
Opens for writing if possible, otherwise read-only.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">osfilename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ostempdir</span><span class="p">()</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="s">&quot;xo_gendoc_test.conf&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">osfilename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ostempdir</span><span class="p">()</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="s">&quot;xo_gendoc_test.conf&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">oswrite</span><span class="p">(</span><span class="s">&quot;&quot;</span><span class="w"> </span><span class="ow">on</span><span class="w"> </span><span class="n">osfilename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">/// Create an empty OS file</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">oswrite</span><span class="p">(</span><span class="s">&quot;&quot;</span><span class="w"> </span><span class="ow">on</span><span class="w"> </span><span class="n">osfilename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">/// Create an empty OS file</span>
Line 2,722: Line 2,966:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">osopen</span><span class="p">(</span><span class="n">osfilename</span><span class="w"> </span><span class="ow">to</span><span class="w"> </span><span class="nf">ostempfile</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">osopen</span><span class="p">(</span><span class="n">osfilename</span><span class="w"> </span><span class="ow">to</span><span class="w"> </span><span class="nf">ostempfile</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>strvar.osbwrite(osfilevar, io offset)</td><td><p>Writes data to an OS file at a specified position.
<tr><td><p><code>if</code></p></td><td><p><code>strvar.osbwrite(osfilevar, io offset)</code></p></td><td><p>Random write data to an OS file.</p>
</p>
<p>At a specified position.</p>
<p><em>strvar:</em> Data to write.
<p><em>strvar:</em> Data to write.</p>
</p>
<p><em>osfilevar:</em> Handle from osopen() or a path/filename; creates file if offset is 0 and it’s new, fails if offset isn’t 0.</p>
<p><em>osfilevar:</em> Handle from osopen() or a path/filename; creates file if offset is 0 and it’s new, fails if offset isn’t 0.
<p><em>offset:</em> [in/out] Start position (0-based); updated to end of written data; -1 appends.</p>
</p>
<p><em>return:</em> True if write succeeds, false if file isn’t accessible, updateable, or creatable.</p>
<p><em>offset:</em> [in/out] Start position (0-based); updated to end of written data; -1 appends.
<p>
</p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">osfilename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ostempdir</span><span class="p">()</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="s">&quot;xo_gendoc_test.conf&quot;</span><span class="p">;</span>
<em>Returns:</em> True if write succeeds, false if file isn’t accessible, updateable, or creatable.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">osfilename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ostempdir</span><span class="p">()</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="s">&quot;xo_gendoc_test.conf&quot;</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">text</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aaa=123</span><span class="se">\n</span><span class="s">bbb=456</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">text</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aaa=123</span><span class="se">\n</span><span class="s">bbb=456</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">offset</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">-1</span><span class="p">;</span><span class="w"> </span><span class="c1">/// -1 means append.</span>
<span class="kt">var</span><span class="w"> </span><span class="n">offset</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">-1</span><span class="p">;</span><span class="w"> </span><span class="c1">/// -1 means append.</span>
Line 2,739: Line 2,982:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">osbwrite</span><span class="p">(</span><span class="n">text</span><span class="w"> </span><span class="ow">on</span><span class="w"> </span><span class="n">osfilename</span><span class="p">,</span><span class="w"> </span><span class="n">offset</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">osbwrite</span><span class="p">(</span><span class="n">text</span><span class="w"> </span><span class="ow">on</span><span class="w"> </span><span class="n">osfilename</span><span class="p">,</span><span class="w"> </span><span class="n">offset</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>strvar.osbread(osfilevar, io offset, length)</td><td><p>Reads data from an OS file at a specified position.
<tr><td><p><code>if</code></p></td><td><p><code>strvar.osbread(osfilevar, io offset, length)</code></p></td><td><p>Random read data from an OS file</p>
</p>
<p>From a specified position.</p>
<p><em>strvar:</em> [out] Data read.
<p><em>strvar[out]:</em> Data read.</p>
</p>
<p><em>osfilevar:</em> Handle from osopen() or a path/filename.</p>
<p><em>osfilevar:</em> Handle from osopen() or a path/filename.
<p><em>offset:</em> [in/out] Start position (0-based); updated to end of read data.</p>
</p>
<p><em>length:</em> Chars to read; with utf8=true (default), may return less to ensure complete UTF-8 code points.</p>
<p><em>offset:</em> [in/out] Start position (0-based); updated to end of read data.
<p><em>return:</em> True if read succeeds, false if file doesn’t exist or isn’t accessible or offset &gt;= file size.</p>
</p>
<p>
<p><em>length:</em> Chars to read; with utf8=true (default), may return less to ensure complete UTF-8 code points.
</p>
<em>Returns:</em> True if read succeeds, false if file doesn’t exist or isn’t accessible or offset >= file size.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">osfilename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ostempdir</span><span class="p">()</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="s">&quot;xo_gendoc_test.conf&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">osfilename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ostempdir</span><span class="p">()</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="s">&quot;xo_gendoc_test.conf&quot;</span><span class="p">;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">text</span><span class="p">,</span><span class="w"> </span><span class="n">offset</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">text</span><span class="p">,</span><span class="w"> </span><span class="n">offset</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
Line 2,757: Line 2,998:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">osbread</span><span class="p">(</span><span class="n">text</span><span class="w"> </span><span class="ow">from</span><span class="w"> </span><span class="n">osfilename</span><span class="p">,</span><span class="w"> </span><span class="n">offset</span><span class="p">,</span><span class="w"> </span><span class="mi">8</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">// text -&gt; &quot;bbb=456\n&quot; // offset -&gt; 16</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">osbread</span><span class="p">(</span><span class="n">text</span><span class="w"> </span><span class="ow">from</span><span class="w"> </span><span class="n">osfilename</span><span class="p">,</span><span class="w"> </span><span class="n">offset</span><span class="p">,</span><span class="w"> </span><span class="mi">8</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">// text -&gt; &quot;bbb=456\n&quot; // offset -&gt; 16</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>osfile << anything << std::endl;</td><td><p>Use convenient << syntax to output anything to an osfile.
<tr><td><p><code></code></p></td><td><p><code>osfile << anything << std::endl;</code></p></td><td><p>Use convenient &lt;&lt; syntax to output anything to an osfile.</p>
</p>
<p><em>osfile:</em> An OS path and filename or an osfilevar opened by osopen(). The file will be appended, or created if it does not already exist. osfile can be "stdout" or "stderr" to simulate cout/cerr/clog.</p>
<em>osfile:</em> An OS path and filename or an osfilevar opened by osopen(). The file will be appended, or created if it does not already exist. osfile can be "stdout" or "stderr" to simulate cout/cerr/clog.
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">txtfile</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;t_temp.txt&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">txtfile</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;t_temp.txt&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">osremove</span><span class="p">(</span><span class="n">txtfile</span><span class="p">))</span><span class="w"> </span><span class="p">{}</span><span class="w"> </span><span class="c1">// Remove any existing file.</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">osremove</span><span class="p">(</span><span class="n">txtfile</span><span class="p">))</span><span class="w"> </span><span class="p">{}</span><span class="w"> </span><span class="c1">// Remove any existing file.</span>
Line 2,766: Line 3,008:
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">osread</span><span class="p">(</span><span class="n">txtfile</span><span class="p">);</span><span class="w">  </span><span class="c1">// &quot;t_temp.txt 123.457 123\n&quot;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">osread</span><span class="p">(</span><span class="n">txtfile</span><span class="p">);</span><span class="w">  </span><span class="c1">// &quot;t_temp.txt 123.457 123\n&quot;</span>
</pre></div>
</pre></div>
All standard c++ io manipulators may be used e.g. std::setw, setfill etc.
</p>
<p></p>
<p>All standard c++ io manipulators may be used e.g. std::setw, setfill etc.</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">vout</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;t_std_iomanip_overview.txt&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">vout</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;t_std_iomanip_overview.txt&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">osremove</span><span class="p">(</span><span class="n">vout</span><span class="p">))</span><span class="w"> </span><span class="p">{}</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">osremove</span><span class="p">(</span><span class="n">vout</span><span class="p">))</span><span class="w"> </span><span class="p">{}</span>
Line 2,814: Line 3,059:
<span class="c1">// Verify actual v. expected.</span>
<span class="c1">// Verify actual v. expected.</span>
<span class="kt">var</span><span class="w"> </span><span class="n">act_v_exp</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">osread</span><span class="p">(</span><span class="n">vout</span><span class="p">);</span>
<span class="kt">var</span><span class="w"> </span><span class="n">act_v_exp</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">osread</span><span class="p">(</span><span class="n">vout</span><span class="p">);</span>
<span class="n">act_v_exp</span><span class="p">.</span><span class="nf">converter</span><span class="p">(</span><span class="s">&quot;</span><span class="se">\n\t</span><span class="s">&quot;</span><span class="p">,</span><span class="w"> </span><span class="kc">FM</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="kc">VM</span><span class="p">);</span><span class="w"> </span><span class="c1">// Text to dynamic array</span>
<span class="n">act_v_exp</span><span class="p">.</span><span class="nf">converter</span><span class="p">(</span><span class="s">&quot;</span><span class="se">\n\t</span><span class="s">&quot;</span><span class="p">,</span><span class="w"> </span><span class="nb">FM</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="nb">VM</span><span class="p">);</span><span class="w"> </span><span class="c1">/// Text to dynamic array</span>
<span class="n">act_v_exp</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">invertarray</span><span class="p">(</span><span class="n">act_v_exp</span><span class="p">);</span><span class="w">  </span><span class="c1">// Columns &lt;-&gt; Rows</span>
<span class="n">act_v_exp</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">invertarray</span><span class="p">(</span><span class="n">act_v_exp</span><span class="p">);</span><span class="w">  </span><span class="c1">/// Columns &lt;-&gt; Rows</span>
<span class="n">assert</span><span class="p">(</span><span class="n">act_v_exp</span><span class="p">.</span><span class="nf">f</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span><span class="w"> </span><span class="ow">eq</span><span class="w"> </span><span class="n">act_v_exp</span><span class="p">.</span><span class="nf">f</span><span class="p">(</span><span class="mi">2</span><span class="p">));</span>
<span class="n">assert</span><span class="p">(</span><span class="n">act_v_exp</span><span class="p">.</span><span class="nf">f</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span><span class="w"> </span><span class="ow">eq</span><span class="w"> </span><span class="n">act_v_exp</span><span class="p">.</span><span class="nf">f</span><span class="p">(</span><span class="mi">2</span><span class="p">));</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>var().osclose()</td><td><p>Removes an osfilevar handle from the internal memory cache of OS file handles. This frees up both exodus process memory and operating system resources.
<tr><td><p><code></code></p></td><td><p><code>var().osclose()</code></p></td><td><p>Close an osfilevar.</p>
</p>
<p>Remove an osfilevar handle from the internal memory cache of OS file handles. This frees up both exodus process memory and operating system resources.</p>
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.
<p>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.</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">osfilevar</span><span class="p">;</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">osfilevar</span><span class="p">.</span><span class="nf">osopen</span><span class="p">(</span><span class="nf">ostempfile</span><span class="p">()))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">osfilevar</span><span class="p">;</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">osfilevar</span><span class="p">.</span><span class="nf">osopen</span><span class="p">(</span><span class="nf">ostempfile</span><span class="p">()))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="n">osfilevar</span><span class="p">.</span><span class="nf">osclose</span><span class="p">();</span>
<span class="n">osfilevar</span><span class="p">.</span><span class="nf">osclose</span><span class="p">();</span>
Line 2,827: Line 3,074:
<span class="nf">osclose</span><span class="p">(</span><span class="n">osfilevar</span><span class="p">);</span>
<span class="nf">osclose</span><span class="p">(</span><span class="n">osfilevar</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>strvar.oswrite(osfilename, codepage = "")</td><td><p>Create a complete OS file from a var.
<tr><td><p><code>if</code></p></td><td><p><code>strvar.oswrite(osfilename, codepage = "")</code></p></td><td><p>Create a complete OS file from a var.</p>
</p>
<p><em>strvar:</em> The text or data to be used to create the file.</p>
<p><em>strvar:</em> The text or data to be used to create the file.
<p><em>osfilename:</em> Absolute or relative path and filename to be written. Any existing OS file is removed first.</p>
</p>
<p><em>codepage:</em> If specified then output is converted from UTF-8 to that codepage before being written. Otherwise no conversion is done.</p>
<p><em>osfilename:</em> Absolute or relative path and filename to be written. Any existing OS file is removed first.
<p><em>return:</em> True if successful or false if not possible for any reason. e.g. Path is not writeable, permissions etc</p>
</p>
<p>
<p><em>codepage:</em> If specified then output is converted from UTF-8 to that codepage before being written. Otherwise no conversion is done.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">text</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&qquot;aaa = 123</span><span class="se">\n</span><span class="s">bbb = 456&quot;</span><span class="p">;</span>
</p>
<em>Returns:</em> True if successful or false if not possible for any reason. e.g. Path is not writeable, permissions etc
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">text</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aaa = 123</span><span class="se">\n</span><span class="s">bbb = 456&quot;</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">osfilename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ostempdir</span><span class="p">()</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="s">&quot;xo_gendoc_test.conf&quot;</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">osfilename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ostempdir</span><span class="p">()</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="s">&quot;xo_gendoc_test.conf&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">text</span><span class="p">.</span><span class="nf">oswrite</span><span class="p">(</span><span class="n">osfilename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">text</span><span class="p">.</span><span class="nf">oswrite</span><span class="p">(</span><span class="n">osfilename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
Line 2,843: Line 3,088:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">oswrite</span><span class="p">(</span><span class="n">text</span><span class="w"> </span><span class="ow">on</span><span class="w"> </span><span class="n">osfilename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">oswrite</span><span class="p">(</span><span class="n">text</span><span class="w"> </span><span class="ow">on</span><span class="w"> </span><span class="n">osfilename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>strvar.osread(osfilename, codepage = "")</td><td><p>Read a complete OS file into a var.
<tr><td><p><code>if</code></p></td><td><p><code>strvar.osread(osfilename, codepage = "")</code></p></td><td><p>Read a complete OS file into a var.</p>
</p>
<p><em>osfilename:</em> Absolute or relative path and filename to be read.</p>
<p><em>osfilename:</em> Absolute or relative path and filename to be read.
<p><em>codepage:</em> If specified then input is converted from that codepage to UTF-8 after being read. Otherwise no conversion is done.</p>
</p>
<p><em>strvar[out]:</em> Is currently set to "" in case of any failure but this is may be changed in a future release to either force var to be unassigned or to leave it untouched. To guarantee future behaviour either add a line 'xxxx.defaulter("")' or set var manually in case osread() returns false. Or use the one argument free function version of osread() which always returns "" in case of failure to read.</p>
<p><em>codepage:</em> If specified then input is converted from that codepage to UTF-8 after being read. Otherwise no conversion is done.
<p><em>return:</em> True if successful or false if not possible for any reason. e.g. File doesnt exist, insufficient permissions etc.</p>
</p>
<p>
<p><em>strvar:</em> [out] is currently set to "" in case of any failure but this is may be changed in a future release to either force var to be unassigned or to leave it untouched. To guarantee future behaviour either add a line 'xxxx.defaulter("")' or set var manually in case osread() returns false. Or use the one argument free function version of osread() which always returns "" in case of failure to read.
</p>
<em>Returns:</em> True if successful or false if not possible for any reason. e.g. File doesnt exist, insufficient permissions etc.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">text</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">text</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">osfilename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ostempdir</span><span class="p">()</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="s">&quot;xo_gendoc_test.conf&quot;</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">osfilename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ostempdir</span><span class="p">()</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="s">&quot;xo_gendoc_test.conf&quot;</span><span class="p">;</span>
Line 2,860: Line 3,103:
<span class="nf">let</span><span class="w"> </span><span class="n">text2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">osread</span><span class="p">(</span><span class="n">osfilename</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">text2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">osread</span><span class="p">(</span><span class="n">osfilename</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>osfile_or_dirname.osrename(new_dirpath_or_filepath)</td><td><p>Renames an OS file or dir in the OS file system.
<tr><td><p><code>if</code></p></td><td><p><code>osfile_or_dirname.osrename(new_dirpath_or_filepath)</code></p></td><td><p>Rename an OS file or dir.</p>
</p>
<p>In the OS file system.</p>
<p>The source and target must exist in the same storage device.
<p>The source and target must exist in the same storage device.</p>
</p>
<p><em>osfile_or_dirname:</em> Absolute or relative path and file or dir name to be renamed.</p>
<p><em>osfile_or_dirname:</em> Absolute or relative path and file or dir name to be renamed.
<p><em>new_dirpath_or_filepath:</em> Will not overwrite an existing OS file or dir.</p>
</p>
<p><em>return:</em> True if successful or false if not possible for any reason. e.g. Target already exists, path is not writeable, permissions etc.</p>
<p><em>new_dirpath_or_filepath:</em> Will not overwrite an existing OS file or dir.
<p>Uses std::filesystem::rename internally.</p>
</p>
<p>
<p><em>Returns:</em> True if successful or false if not possible for any reason. e.g. Target already exists, path is not writeable, permissions etc.
</p>
Uses std::filesystem::rename internally.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">from_osfilename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ostempdir</span><span class="p">()</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="s">&quot;xo_gendoc_test.conf&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">from_osfilename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ostempdir</span><span class="p">()</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="s">&quot;xo_gendoc_test.conf&quot;</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">to_osfilename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">from_osfilename</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="s">&quot;.bak&quot;</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">to_osfilename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">from_osfilename</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="s">&quot;.bak&quot;</span><span class="p">;</span>
Line 2,880: Line 3,121:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">osrename</span><span class="p">(</span><span class="n">from_osfilename</span><span class="p">,</span><span class="w"> </span><span class="n">to_osfilename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">osrename</span><span class="p">(</span><span class="n">from_osfilename</span><span class="p">,</span><span class="w"> </span><span class="n">to_osfilename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>osfile_or_dirname.osmove(to_osfilename)</td><td><p>"Moves" an OS file or dir within the OS file system.
<tr><td><p><code>if</code></p></td><td><p><code>osfile_or_dirname.osmove(to_osfilename)</code></p></td><td><p>"Move" an OS file or dir.</p>
</p>
<p>Within the OS file system.</p>
<p>Attempts osrename first, then oscopy followed by osremove original.
<p>Attempt osrename first, then oscopy plus osremove original.</p>
</p>
<p><em>osfile_or_dirname:</em> Absolute or relative path and file or dir name to be moved.</p>
<p><em>osfile_or_dirname:</em> Absolute or relative path and file or dir name to be moved.
<p><em>to_osfilename:</em> Will not overwrite an existing OS file or dir.</p>
</p>
<p><em>return:</em> True if successful or false if not possible for any reason. e.g. Source doesnt exist or cannot be accessed, target already exists, source or target is not writeable, permissions, storage space etc.</p>
<p><em>to_osfilename:</em> Will not overwrite an existing OS file or dir.
<p>
</p>
<em>Returns:</em> True if successful or false if not possible for any reason. e.g. Source doesnt exist or cannot be accessed, target already exists, source or target is not writeable, permissions, storage space etc.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">from_osfilename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ostempdir</span><span class="p">()</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="s">&quot;xo_gendoc_test.conf.bak&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">from_osfilename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ostempdir</span><span class="p">()</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="s">&quot;xo_gendoc_test.conf.bak&quot;</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">to_osfilename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">from_osfilename</span><span class="p">.</span><span class="nf">cut</span><span class="p">(</span><span class="mi">-4</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">to_osfilename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">from_osfilename</span><span class="p">.</span><span class="nf">cut</span><span class="p">(</span><span class="mi">-4</span><span class="p">);</span>
Line 2,898: Line 3,138:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">osmove</span><span class="p">(</span><span class="n">from_osfilename</span><span class="p">,</span><span class="w"> </span><span class="n">to_osfilename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">osmove</span><span class="p">(</span><span class="n">from_osfilename</span><span class="p">,</span><span class="w"> </span><span class="n">to_osfilename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>osfile_or_dirname.oscopy(to_osfilename)</td><td><p>Copies an OS file or directory recursively within the OS file system.
<tr><td><p><code>if</code></p></td><td><p><code>osfile_or_dirname.oscopy(to_osfilename)</code></p></td><td><p>Copy an OS file or directory.</p>
</p>
<p>Including subdirs.</p>
<p><em>osfile_or_dirname:</em> Absolute or relative path and file or dir name to be copied.
<p><em>osfile_or_dirname:</em> Absolute or relative path and file or dir name to be copied.</p>
</p>
<p><em>to_osfilename:</em> Will overwrite an existing OS file or merge into an existing dir.</p>
<p><em>to_osfilename:</em> Will overwrite an existing OS file or merge into an existing dir.
<p><em>return:</em> True if successful or false if not possible for any reason. e.g. Source doesnt exist or cannot be accessed, target is not writeable, permissions, storage space, etc.</p>
</p>
<p>Uses std::filesystem::copy internally with recursive and overwrite options</p>
<p><em>Returns:</em> True if successful or false if not possible for any reason. e.g. Source doesnt exist or cannot be accessed, target is not writeable, permissions, storage space, etc.
<p>
</p>
Uses std::filesystem::copy internally with recursive and overwrite options
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">from_osfilename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ostempdir</span><span class="p">()</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="s">&quot;xo_gendoc_test.conf&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">from_osfilename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ostempdir</span><span class="p">()</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="s">&quot;xo_gendoc_test.conf&quot;</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">to_osfilename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">from_osfilename</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="s">&quot;.bak&quot;</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">to_osfilename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">from_osfilename</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="s">&quot;.bak&quot;</span><span class="p">;</span>
Line 2,915: Line 3,154:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">oscopy</span><span class="p">(</span><span class="n">from_osfilename</span><span class="p">,</span><span class="w"> </span><span class="n">to_osfilename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">oscopy</span><span class="p">(</span><span class="n">from_osfilename</span><span class="p">,</span><span class="w"> </span><span class="n">to_osfilename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>osfilename.osremove()</td><td><p>Removes/deletes an OS file from the OS file system.
<tr><td><p><code>if</code></p></td><td><p><code>osfilename.osremove()</code></p></td><td><p>Remove/delete an OS file.</p>
</p>
<p>From the OS file system.</p>
<p>Will not remove directories. Use osrmdir() to remove directories
<p>Will not remove directories. Use osrmdir() to remove directories</p>
</p>
<p><em>osfilename:</em> Absolute or relative path and file name to be removed.</p>
<p><em>osfilename:</em> Absolute or relative path and file name to be removed.
<p><em>return:</em> True if successful or false if not possible for any reason. e.g. Target doesnt exist, path is not writeable, permissions etc.</p>
</p>
<p>If osfilename is an osfilevar then it is automatically closed.</p>
<p><em>Returns:</em> True if successful or false if not possible for any reason. e.g. Target doesnt exist, path is not writeable, permissions etc.
<p>
</p>
If osfilename is an osfilevar then it is automatically closed.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">osfilename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ostempdir</span><span class="p">()</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="s">&quot;xo_gendoc_test.conf&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">osfilename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ostempdir</span><span class="p">()</span><span class="w"> </span><span class="o">^</span><span class="w"> </span><span class="s">&quot;xo_gendoc_test.conf&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">osfilename</span><span class="p">.</span><span class="nf">osremove</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">osfilename</span><span class="p">.</span><span class="nf">osremove</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
Line 2,930: Line 3,168:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">osremove</span><span class="p">(</span><span class="n">osfilename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">osremove</span><span class="p">(</span><span class="n">osfilename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
</table>
</table>
Line 2,936: Line 3,175:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>var=</td><td>dirpath.oslist(globpattern = "", mode = 0)</td><td><p>Get a list of OS files and/or dirs.
<tr><td><p><code>var=</code></p></td><td><p><code>dirpath.oslist(globpattern = "", mode = 0)</code></p></td><td><p>Get a list of OS files and/or dirs.</p>
</p>
<p><em>dirpath:</em> Absolute or relative dir path.</p>
<p><em>dirpath:</em> Absolute or relative dir path.
<p><em>globpattern:</em> e.g. *.conf to be appended to the dirpath or a complete path plus glob pattern e.g. /etc/ *.conf.</p>
</p>
<p><em>mode:</em> </p>
<p><em>globpattern:</em> e.g. *.conf to be appended to the dirpath or a complete path plus glob pattern e.g. /etc/ *.conf.
<dl>
</p>
<dt>0</dt><dd>Any regular OS file or dir (Default).</dd>
<p><em>mode:</em> 0: default - Any regular files or dirs. 1 - Only regular OS files. 2 - Only dirs.
<dt>1</dt><dd>Only regular OS files.</dd>
</p>
<dt>2</dt><dd>Only dirs.</dd>
<em>Returns:</em> An FM delimited string containing all matching dir entries given a dir path
</dl>
<p><em>return:</em> An FM delimited string containing all matching dir entries given a dir path</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">entries1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;/etc/&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">oslist</span><span class="p">(</span><span class="s">&quot;*.cfg&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">/// e.g. &quot;adduser.conf^ca-certificates.con^... etc.&quot;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">entries1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;/etc/&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">oslist</span><span class="p">(</span><span class="s">&quot;*.cfg&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">/// e.g. &quot;adduser.conf^ca-certificates.con^... etc.&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="kt">var</span><span class="w"> </span><span class="n">entries2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">oslist</span><span class="p">(</span><span class="s">&quot;/etc/&quot;</span><span class="w"> </span><span class="s">&quot;*.conf&quot;</span><span class="p">);</span>
<span class="kt">var</span><span class="w"> </span><span class="n">entries2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">oslist</span><span class="p">(</span><span class="s">&quot;/etc/&quot;</span><span class="w"> </span><span class="s">&quot;*.conf&quot;</span><span class="p">);</span>
</pre></div></td></tr>
</pre></div>
<tr><td>var=</td><td>dirpath.oslistf(globpattern = "")</td><td>Same as oslist for files only</td></tr>
<tr><td>var=</td><td>dirpath.oslistd(globpattern = "")</td><td>Same as oslist for files only</td></tr>
<tr><td>var=</td><td>osfile_or_dirpath.osinfo(mode = 0)</td><td><p>Get dir info about an OS file or dir.
</p>
</p>
<p><em>Returns:</em> A short string containing size ^ FM ^ modified_time ^ FM ^ modified_time or "" if not a regular file or dir.
</td></tr>
</p>
<tr><td><p><code>var=</code></p></td><td><p><code>dirpath.oslistf(globpattern = "")</code></p></td><td><p>Get a list of OS files.</p>
<p><em>mode:</em> 0: default. 1: Must be a regular OS file. 2: Must be an OS dir.
<p>See oslist() for info.</p>
</p>
</td></tr>
See also osfile() and osdir()
<tr><td><p><code>var=</code></p></td><td><p><code>dirpath.oslistd(globpattern = "")</code></p></td><td><p>Get a list of OS dirs.</p>
<p>See oslist() for info.</p>
</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>osfile_or_dirpath.osinfo(mode = 0)</code></p></td><td><p>Get dir info about an OS file or dir.</p>
<p><em>return:</em> A short string containing size ^ FM ^ modified_time ^ FM ^ modified_time or "" if not a regular file or dir.</p>
<p><em>mode:</em> 0: Default. 1: Must be a regular OS file. 2: Must be an OS dir.</p>
<p>See also osfile() and osdir()</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">info1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;/etc/hosts&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">osinfo</span><span class="p">();</span><span class="w"> </span><span class="c1">/// e.g. &quot;221^20597^78309&quot;_var</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">info1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;/etc/hosts&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">osinfo</span><span class="p">();</span><span class="w"> </span><span class="c1">/// e.g. &quot;221^20597^78309&quot;_var</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="kt">var</span><span class="w"> </span><span class="n">info2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">osinfo</span><span class="p">(</span><span class="s">&quot;/etc/hosts&quot;</span><span class="p">);</span>
<span class="kt">var</span><span class="w"> </span><span class="n">info2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">osinfo</span><span class="p">(</span><span class="s">&quot;/etc/hosts&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>osfilename.osfile()</td><td><p>Get dir info of an OS file.
<tr><td><p><code>var=</code></p></td><td><p><code>osfilename.osfile()</code></p></td><td><p>Get dir info of an OS file.</p>
</p>
<p><em>osfilename:</em> Absolute or relative path and file name.</p>
<p><em>osfilename:</em> Absolute or relative path and file name.
<p><em>return:</em> A short string containing size ^ FM ^ modified_time ^ FM ^ modified_time or "" if not a regular file.</p>
</p>
<p>Alias for osinfo(1)</p>
<p><em>Returns:</em> A short string containing size ^ FM ^ modified_time ^ FM ^ modified_time or "" if not a regular file.
<p>
</p>
Alias for osinfo(1)
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">fileinfo1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;/etc/hosts&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">osfile</span><span class="p">();</span><span class="w"> </span><span class="c1">/// e.g. &quot;221^20597^78309&quot;_var</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">fileinfo1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;/etc/hosts&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">osfile</span><span class="p">();</span><span class="w"> </span><span class="c1">/// e.g. &quot;221^20597^78309&quot;_var</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="kt">var</span><span class="w"> </span><span class="n">fileinfo2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">osfile</span><span class="p">(</span><span class="s">&quot;/etc/hosts&quot;</span><span class="p">);</span>
<span class="kt">var</span><span class="w"> </span><span class="n">fileinfo2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">osfile</span><span class="p">(</span><span class="s">&quot;/etc/hosts&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>dirpath.osdir()</td><td><p>Get dir info of an OS dir.
<tr><td><p><code>var=</code></p></td><td><p><code>dirpath.osdir()</code></p></td><td><p>Get dir info of an OS dir.</p>
</p>
<p><em>dirpath:</em> Absolute or relative path and dir name.</p>
<p><em>dirpath:</em> Absolute or relative path and dir name.
<p><em>return:</em> A short string containing FM ^ modified_time ^ FM ^ modified_time or "" if not a dir.</p>
</p>
<p>Alias for osinfo(2)</p>
<p><em>Returns:</em> A short string containing FM ^ modified_time ^ FM ^ modified_time or "" if not a dir.
<p>
</p>
Alias for osinfo(2)
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">dirinfo1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;/etc/&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">osdir</span><span class="p">();</span><span class="w"> </span><span class="c1">/// e.g. &quot;^20848^44464&quot;_var</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">dirinfo1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;/etc/&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">osdir</span><span class="p">();</span><span class="w"> </span><span class="c1">/// e.g. &quot;^20848^44464&quot;_var</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="kt">var</span><span class="w"> </span><span class="n">dirinfo2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">osfile</span><span class="p">(</span><span class="s">&quot;/etc/&quot;</span><span class="p">);</span>
<span class="kt">var</span><span class="w"> </span><span class="n">dirinfo2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">osfile</span><span class="p">(</span><span class="s">&quot;/etc/&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>dirpath.osmkdir()</td><td><p>Create a new OS file system directory.
<tr><td><p><code>if</code></p></td><td><p><code>dirpath.osmkdir()</code></p></td><td><p>Create a new OS file system directory.</p>
</p>
<p>Parent dirs wil be created if necessary.</p>
<p>Parent dirs wil be created if necessary.
<p><em>dirpath:</em> Absolute or relative path and dir name.</p>
</p>
<p><em>return:</em> True if successful.</p>
<p><em>dirpath:</em> Absolute or relative path and dir name.
<p>
</p>
<em>Returns:</em> True if successful.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">osdirname</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_test/aaa&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">osdirname</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_test/aaa&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">osrmdir</span><span class="p">(</span><span class="s">&quot;xo_test/aaa&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">{};</span><span class="w"> </span><span class="c1">// Cleanup first</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">osrmdir</span><span class="p">(</span><span class="s">&quot;xo_test/aaa&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">{};</span><span class="w"> </span><span class="c1">// Cleanup first</span>
Line 3,000: Line 3,242:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">osmkdir</span><span class="p">(</span><span class="n">osdirname</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">osmkdir</span><span class="p">(</span><span class="n">osdirname</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>var::oscwd(newpath)</td><td><p>Changes the current working dir.
<tr><td><p><code>if</code></p></td><td><p><code>var::oscwd(newpath)</code></p></td><td><p>Change the current working dir.</p>
</p>
<p><em>newpath:</em> An absolute or relative dir path and name.</p>
<p><em>newpath:</em> An absolute or relative dir path and name.
<p><em>return:</em> True if successful or false if not. e.g. Invalid dirpath, insufficient permission etc.</p>
</p>
<p>
<em>Returns:</em> True if successful or false if not. e.g. Invalid dirpath, insufficient permission etc.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">osdirname</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_test/aaa&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">osdirname</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_test/aaa&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">osdirname</span><span class="p">.</span><span class="nf">oscwd</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">osdirname</span><span class="p">.</span><span class="nf">oscwd</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
Line 3,012: Line 3,254:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">oscwd</span><span class="p">(</span><span class="s">&quot;../..&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">/// Change back to avoid errors in following code.</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">oscwd</span><span class="p">(</span><span class="s">&quot;../..&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">/// Change back to avoid errors in following code.</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>var::oscwd()</td><td><p>Gets the current dir path and name.
<tr><td><p><code>var=</code></p></td><td><p><code>var::oscwd()</code></p></td><td><p>Get the current working dir path and name.</p>
</p>
<p><em>return:</em> The current working dir path and name.</p>
<p><em>Returns:</em> The current working dir path and name.
<p>e.g. "/root/exodus/cli/src/xo_test/aaa"</p>
</p>
<p>
e.g. "/root/exodus/cli/src/xo_test/aaa"
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">cwd1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">().</span><span class="nf">oscwd</span><span class="p">();</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">cwd1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">().</span><span class="nf">oscwd</span><span class="p">();</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="kt">var</span><span class="w"> </span><span class="n">cwd2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">oscwd</span><span class="p">();</span>
<span class="kt">var</span><span class="w"> </span><span class="n">cwd2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">oscwd</span><span class="p">();</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>dirpath.osrmdir(evenifnotempty = false)</td><td><p>Removes (deletes) an OS dir,
<tr><td><p><code>if</code></p></td><td><p><code>dirpath.osrmdir(evenifnotempty = false)</code></p></td><td><p>Remove (deletes) an OS dir,</p>
</p>
<p><em>eventifnotempty:</em> If true any subdirs will also be removed/deleted recursively, otherwise the function will fail and return false.</p>
<p><em>eventifnotempty:</em> If true any subdirs will also be removed/deleted recursively, otherwise the function will fail and return false.
<p><em>return:</em> Returns true if successful or false if not. e.g dir doesnt exist, insufficient permission, not empty etc.</p>
</p>
<p>
<em>Returns:</em> Returns true if successful or false if not. e.g dir doesnt exist, insufficient permission, not empty etc.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">osdirname</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_test/aaa&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">osdirname</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_test/aaa&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">osdirname</span><span class="p">.</span><span class="nf">osrmdir</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">osdirname</span><span class="p">.</span><span class="nf">osrmdir</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
Line 3,033: Line 3,275:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">osrmdir</span><span class="p">(</span><span class="n">osdirname</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">osrmdir</span><span class="p">(</span><span class="n">osdirname</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
</table>
</table>
Line 3,039: Line 3,282:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>if</td><td>command.osshell()</td><td><p>Execute a shell command.
<tr><td><p><code>if</code></p></td><td><p><code>command.osshell()</code></p></td><td><p>Execute a shell command.</p>
</p>
<p><em>command:</em> An executable command to be interpreted by the default OS shell.</p>
<p><em>command:</em> An executable command to be interpreted by the default OS shell.
<p><em>return:</em> True if the process terminates with error status 0 and false otherwise.</p>
</p>
<p>Append "&amp;&gt;/dev/null" to the command to suppress terminal output.</p>
<p><em>Returns:</em> True if the process terminates with error status 0 and false otherwise.
<p>
</p>
Append "&>/dev/null" to the command to suppress terminal output.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">cmd</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;echo $HOME&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">cmd</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;echo $HOME&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">cmd</span><span class="p">.</span><span class="nf">osshell</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">cmd</span><span class="p">.</span><span class="nf">osshell</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
Line 3,051: Line 3,292:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">osshell</span><span class="p">(</span><span class="n">cmd</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">osshell</span><span class="p">(</span><span class="n">cmd</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>instr.osshellread(oscmd)</td><td><p>Same as osshell but captures and returns stdout
<tr><td><p><code>if</code></p></td><td><p><code>instr.osshellread(oscmd)</code></p></td><td><p>Execute a shell command and capture its stdout.</p>
</p>
<p><em>return:</em> The stout of the shell command.</p>
<p><em>Returns:</em> The stout of the shell command.
<p>Append "2&gt;&amp;1" to the command to capture stderr/stdlog output as well.</p>
</p>
<p>
Append "2>&1" to the command to capture stderr/stdlog output as well.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">cmd</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;echo $HOME&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">cmd</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;echo $HOME&quot;</span><span class="p">;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">text</span><span class="p">;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">text</span><span class="p">;</span>
Line 3,064: Line 3,305:
<span class="n">text</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">osshellread</span><span class="p">(</span><span class="n">cmd</span><span class="p">);</span>
<span class="n">text</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">osshellread</span><span class="p">(</span><span class="n">cmd</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>outstr.osshellwrite(oscmd)</td><td><p>Same as osshell but provides stdin to the process
<tr><td><p><code>if</code></p></td><td><p><code>outstr.osshellwrite(oscmd)</code></p></td><td><p>Execute a shell command and provide its stdin.</p>
</p>
<p><em>return:</em> True if the process terminates with error status 0 and false otherwise.</p>
<p><em>Returns:</em> True if the process terminates with error status 0 and false otherwise.
<p>Append "&amp;&gt; somefile" to the command to suppress and/or capture output.</p>
</p>
<p>
Append "&> somefile" to the command to suppress and/or capture output.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">outtext</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc xyz&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">outtext</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;abc xyz&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">outtext</span><span class="p">.</span><span class="nf">osshellwrite</span><span class="p">(</span><span class="s">&quot;grep xyz&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">outtext</span><span class="p">.</span><span class="nf">osshellwrite</span><span class="p">(</span><span class="s">&quot;grep xyz&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
Line 3,075: Line 3,316:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">osshellwrite</span><span class="p">(</span><span class="n">outtext</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;grep xyz&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">osshellwrite</span><span class="p">(</span><span class="n">outtext</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;grep xyz&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>var::osprocess(oscmd, stdin_for_process, out stdout_from_process, out stderr_from_process, out exit_status, timeout_secs = 0)</td><td><p>Run an OS program synchronously.
<tr><td><p><code>if</code></p></td><td><p><code>dirpath.osprocess(oscmd, stdin_for_process, out stdout_from_process, out stderr_from_process, out exit_status, timeout_secs = 0)</code></p></td><td><p>Run an OS program synchronously.</p>
</p>
<p>Provide its standard input and capture its output, errors, and exit status.</p>
<p>Executes an OS program passing input and capturing standard and error output, and exit status.
<p>Shell features (e.g., pipes, redirects) are unsupported but can be invoked via an oscmd like "bash -c 'abc|yy $HOME'".</p>
</p>
<p><em>oscmd:</em> Executable and arguments; must exist in OS PATH.</p>
<p>Shell features (e.g., pipes, redirects) are not supported but can be invoked using an oscmd like "bash -c \"abc|yyy $HOME\""
<p><em>stdin_for_process:</em> Optional; input data for the program’s standard input.</p>
</p>
<p><em>stdout_from_process[out]:</em> Standard output from the program.</p>
<p><em>oscmd:</em> The executable program and its arguments. Must exist in the OS PATH.
<p><em>stderr_from_process[out]:</em> Error/log output from the program.</p>
</p>
<p><em>exit_status[out]:</em> Program’s exit status: 0 (normal), -1 (timeout), else (error).</p>
<p><em>stdin_for_process:</em> Optional. Input data to send to the program's standard input.
<p><em>timeout_secs:</em> Optional; max runtime in seconds (default 0 = no timeout).</p>
</p>
<p><em>return:</em> True if program ran and exited with status 0 (success) or false if program failed to start, timed out, or exited with non-zero status.</p>
<p><em>stdout_from_process:</em> [out] Standard output produced by the program.
<p><em>throw:</em> Pipe creation failed, fork failed, poll failed.</p>
</p>
<p>
<p><em>stderr_from_process:</em> [out] Error or log output from the program.
</p>
<p><em>exit_status:</em> [out] Result of the program's execution:
</p>
<p>*  0 Program terminated normally.
</p>
<p>* -1 Timeout
</p>
<p>* nn Program reported an exit status.
</p>
<p><em>timeout_in_secs:</em> Optional. Maximum runtime in seconds (default 0 = no timeout).
</p>
<p><em>Returns:</em> Success or failure.
</p>
<p>* true    Program ran and exited with status 0 (success).
</p>
<p>* false   Program failed to start, timed out, or exited with non-zero status.
</p>
<p><em>Throws:</em> Various system errors are possible.
</p>
<p>* Pipe creation failed.
</p>
<p>* Fork failed.
</p>
* Poll failure.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v_stdout</span><span class="p">,</span><span class="w"> </span><span class="n">v_stderr</span><span class="p">,</span><span class="w"> </span><span class="n">v_exit_status</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v_stdout</span><span class="p">,</span><span class="w"> </span><span class="n">v_stderr</span><span class="p">,</span><span class="w"> </span><span class="n">v_exit_status</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="kt">var</span><span class="o">::</span><span class="n">osprocess</span><span class="p">(</span><span class="s">&quot;grep xyz&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;abc</span><span class="se">\n</span><span class="s">xyz 123</span><span class="se">\n</span><span class="s">def&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">v_stdout</span><span class="p">,</span><span class="w"> </span><span class="n">v_stderr</span><span class="p">,</span><span class="w"> </span><span class="n">v_exit_status</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">// v_stdout -&gt; &quot;xyz 123&quot; // v_exit_status = 0</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="kt">var</span><span class="o">::</span><span class="n">osprocess</span><span class="p">(</span><span class="s">&quot;grep xyz&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;abc</span><span class="se">\n</span><span class="s">xyz 123</span><span class="se">\n</span><span class="s">def&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">v_stdout</span><span class="p">,</span><span class="w"> </span><span class="n">v_stderr</span><span class="p">,</span><span class="w"> </span><span class="n">v_exit_status</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">// v_stdout -&gt; &quot;xyz 123&quot; // v_exit_status = 0</span>
Line 3,118: Line 3,335:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">osprocess</span><span class="p">(</span><span class="s">&quot;grep xyz&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;abc</span><span class="se">\n</span><span class="s">xyz 123</span><span class="se">\n</span><span class="s">def&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">v_stdout</span><span class="p">,</span><span class="w"> </span><span class="n">v_stderr</span><span class="p">,</span><span class="w"> </span><span class="n">v_exit_status</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">osprocess</span><span class="p">(</span><span class="s">&quot;grep xyz&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;abc</span><span class="se">\n</span><span class="s">xyz 123</span><span class="se">\n</span><span class="s">def&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">v_stdout</span><span class="p">,</span><span class="w"> </span><span class="n">v_stderr</span><span class="p">,</span><span class="w"> </span><span class="n">v_exit_status</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>var::ostempdir()</td><td><p>Get the tmp dir path and name.
<tr><td><p><code>var=</code></p></td><td><p><code>var::ostempdir()</code></p></td><td><p>Get the tmp dir path.</p>
</p>
<p><em>return:</em> A string e.g. "/tmp/"</p>
<em>Returns:</em> A string e.g. "/tmp/"
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">ostempdir</span><span class="p">();</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">ostempdir</span><span class="p">();</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ostempdir</span><span class="p">();</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ostempdir</span><span class="p">();</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>var::ostempfile()</td><td><p>Create a temporary file
<tr><td><p><code>var=</code></p></td><td><p><code>var::ostempfile()</code></p></td><td><p>Create a temporary file.</p>
</p>
<p><em>return:</em> The name of new temporary file e.g. "/tmp/~exoEcLj3C"</p>
<em>Returns:</em> The name of new temporary file e.g. "/tmp/~exoEcLj3C"
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">temposfilename1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">ostempfile</span><span class="p">();</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">temposfilename1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">ostempfile</span><span class="p">();</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="kt">var</span><span class="w"> </span><span class="n">temposfilename2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ostempfile</span><span class="p">();</span>
<span class="kt">var</span><span class="w"> </span><span class="n">temposfilename2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ostempfile</span><span class="p">();</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>envvalue.ossetenv(envcode)</td><td><p>Set the value of an environment variable
<tr><td><p><code>if</code></p></td><td><p><code>envvalue.osgetenv(envcode)</code></p></td><td><p>Get the value of an environment variable.</p>
<p><em>envcode:</em> The code of the env variable to get or "" for all.</p>
<p><em>envvalue[out]:</em> Set to the value of the env variable if set otherwise "". If envcode is "" then envvalue is set to a dynamic array of all environment variables LIKE CODE1=VALUE1^CODE2=VALUE2...</p>
<p><em>return:</em> True if the envcode is set or false if not.</p>
<p>osgetenv and ossetenv work with a per thread copy of the OS process environment. This avoids multithreading issues but does not change the process environment. Child processes created by var::osshell() will not inherit any env variables set using ossetenv() so the oscommand will need to be prefixed to achieve the desired result.</p>
<p>For the actual system environment, see "man environ". extern char **environ; // environ is a pointer to an array of pointers to char* env pairs like xxx=yyy and the last pointer in the array is nullptr.</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">envvalue1</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">envvalue1</span><span class="p">.</span><span class="nf">osgetenv</span><span class="p">(</span><span class="s">&quot;HOME&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">// e.g. &quot;/home/exodus&quot;</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">envvalue2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">osgetenv</span><span class="p">(</span><span class="s">&quot;EXO_ABC&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;XYZ&quot;</span>
</pre></div>
</p>
</p>
<p><em>envcode:</em> The code of the env variable to set.
</td></tr>
</p>
<tr><td><p><code></code></p></td><td><p><code>envvalue.ossetenv(envcode)</code></p></td><td><p>Set the value of an environment variable.</p>
<em>envvalue:</em> The new value to set the env code to.
<p><em>envcode:</em> The code of the env variable to set.</p>
<p><em>envvalue:</em> The new value to set the env code to.</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">envcode</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;EXO_ABC&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">envvalue</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;XYZ&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">envcode</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;EXO_ABC&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">envvalue</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;XYZ&quot;</span><span class="p">;</span>
<span class="n">envvalue</span><span class="p">.</span><span class="nf">ossetenv</span><span class="p">(</span><span class="n">envcode</span><span class="p">);</span>
<span class="n">envvalue</span><span class="p">.</span><span class="nf">ossetenv</span><span class="p">(</span><span class="n">envcode</span><span class="p">);</span>
Line 3,145: Line 3,378:
<span class="nf">ossetenv</span><span class="p">(</span><span class="n">envcode</span><span class="p">,</span><span class="w"> </span><span class="n">envvalue</span><span class="p">);</span>
<span class="nf">ossetenv</span><span class="p">(</span><span class="n">envcode</span><span class="p">,</span><span class="w"> </span><span class="n">envvalue</span><span class="p">);</span>
</pre></div>
</pre></div>
</td></tr>
<tr><td>if</td><td>envvalue.osgetenv(envcode)</td><td><p>Get the value of an environment variable.
</p>
</p>
<p><em>envcode:</em> The code of the env variable to get or "" for all.
</p>
<p><em>envvalue:</em> [out] Set to the value of the env variable if set otherwise "". If envcode is "" then envvalue is set to a dynamic array of all environment variables LIKE CODE1=VALUE1^CODE2=VALUE2...
</p>
<p><em>Returns:</em> True if the envcode is set or false if not.
</p>
<p>osgetenv and ossetenv work with a per thread copy of the OS process environment. This avoids multithreading issues but does not change the process environment. Child processes created by var::osshell() will not inherit any env variables set using ossetenv() so the oscommand will need to be prefixed to achieve the desired result.
</p>
For the actual system environment, see "man environ". extern char **environ; // environ is a pointer to an array of pointers to char* env pairs like xxx=yyy and the last pointer in the array is nullptr.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">envvalue1</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">envvalue1</span><span class="p">.</span><span class="nf">osgetenv</span><span class="p">(</span><span class="s">&quot;HOME&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">// e.g. &quot;/home/exodus&quot;</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">envvalue2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">osgetenv</span><span class="p">(</span><span class="s">&quot;EXO_ABC&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;XYZ&quot;</span>
</pre></div>
</td></tr>
</td></tr>
<tr><td>var=</td><td>var::ospid()</td><td><p>Get the current OS process id
<tr><td><p><code>var=</code></p></td><td><p><code>var::ospid()</code></p></td><td><p>Get the current OS process id.</p>
</p>
<p><em>return:</em> A number e.g. 663237.</p>
<em>Returns:</em> A number e.g. 663237.
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">pid1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">ospid</span><span class="p">();</span><span class="w"> </span><span class="c1">/// e.g. 663237</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">pid1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">ospid</span><span class="p">();</span><span class="w"> </span><span class="c1">/// e.g. 663237</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">pid2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ospid</span><span class="p">();</span>
<span class="nf">let</span><span class="w"> </span><span class="n">pid2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ospid</span><span class="p">();</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>var::ostid()</td><td><p>Get the current OS thread process id
<tr><td><p><code>var=</code></p></td><td><p><code>var::ostid()</code></p></td><td><p>Get the current OS thread process id.</p>
</p>
<p><em>return:</em> A number e.g. 663237.</p>
<em>Returns:</em> A number e.g. 663237.
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">tid1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">ostid</span><span class="p">();</span><span class="w"> </span><span class="c1">/// e.g. 663237</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">tid1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">ostid</span><span class="p">();</span><span class="w"> </span><span class="c1">/// e.g. 663237</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">tid2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ostid</span><span class="p">();</span>
<span class="nf">let</span><span class="w"> </span><span class="n">tid2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">ostid</span><span class="p">();</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>var::version()</td><td><p>Get the exodus library version info.
<tr><td><p><code>var=</code></p></td><td><p><code>var::version()</code></p></td><td><p>Get the exodus library version info.</p>
</p>
<p><em>return:</em> The git commit details as at the time the library was built.</p>
<em>Returns:</em> The git commit details as at the time the library was built.
<p>
<div class="highlight light"><pre><span class="c1">// e.g.</span>
<div class="highlight light"><pre><span class="c1">// e.g.</span>
<span class="c1">// Local:  doc 2025-03-19 18:15:31 +0000 219cdad8a</span>
<span class="c1">// Local:  doc 2025-03-19 18:15:31 +0000 219cdad8a</span>
Line 3,192: Line 3,411:
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">version</span><span class="p">();</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">version</span><span class="p">();</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>strvar.setxlocale(newlocalecode)</td><td><p>Sets the current thread's default locale.
<tr><td><p><code>if</code></p></td><td><p><code>strvar.setxlocale(newlocalecode)</code></p></td><td><p>Set the current thread's default locale.</p>
</p>
<p><em>strvar:</em> The new locale codepage code.</p>
<p><em>strvar:</em> The new locale codepage code.
<p>True if successful</p>
</p>
<p>
True if successful
<div class="highlight light"><pre><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="kt">var</span><span class="o">::</span><span class="nf">setxlocale</span><span class="p">(</span><span class="s">&quot;en_US.utf8&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<div class="highlight light"><pre><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="kt">var</span><span class="o">::</span><span class="nf">setxlocale</span><span class="p">(</span><span class="s">&quot;en_US.utf8&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">setxlocale</span><span class="p">(</span><span class="s">&quot;en_US.utf8&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">setxlocale</span><span class="p">(</span><span class="s">&quot;en_US.utf8&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>var.getxlocale()</td><td><p>Gets the current thread's default locale.
<tr><td><p><code>var=</code></p></td><td><p><code>var.getxlocale()</code></p></td><td><p>Get the current thread's default locale.</p>
</p>
<p><em>return:</em> A locale codepage code string.</p>
<em>Returns:</em> A locale codepage code string.
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">getxlocale</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;en_US.utf8&quot;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">getxlocale</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;en_US.utf8&quot;</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">getxlocale</span><span class="p">();</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">getxlocale</span><span class="p">();</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
</table>
</table>
Line 3,216: Line 3,437:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>expr</td><td>strvar.outputl(prefix = "")</td><td><p>Output to stdout with optional prefix.
<tr><td><p><code>expr</code></p></td><td><p><code>strvar.outputl(prefix = "")</code></p></td><td><p>Output to stdout with optional prefix.</p>
</p>
<p>Append an NL char.</p>
<p>Appends an NL char.
<p>Is FLUSHED, not buffered.</p>
</p>
<p>The raw string bytes are output. No character or byte conversion is performed.</p>
<p>Is FLUSHED, not buffered.
<p>
</p>
The raw string bytes are output. No character or byte conversion is performed.
<div class="highlight light"><pre><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">outputl</span><span class="p">(</span><span class="s">&quot;xyz = &quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">/// Sends &quot;xyz = abc\n&quot; to stdout and flushes.</span>
<div class="highlight light"><pre><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">outputl</span><span class="p">(</span><span class="s">&quot;xyz = &quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">/// Sends &quot;xyz = abc\n&quot; to stdout and flushes.</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">outputl</span><span class="p">(</span><span class="s">&quot;xyz = &quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">/// Any number of arguments is allowed. All will be output.</span>
<span class="nf">outputl</span><span class="p">(</span><span class="s">&quot;xyz = &quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">/// Any number of arguments is allowed. All will be output.</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>expr</td><td>strvar.output(prefix = "")</td><td> Same as outputl() but doesnt append an NL char and is BUFFERED, not flushed.</td></tr>
<tr><td><p><code>expr</code></p></td><td><p><code>strvar.output(prefix = "")</code></p></td><td> <p>Same as outputl() but doesnt append an NL char and is BUFFERED, not flushed.</p>
<tr><td>expr</td><td>strvar.outputt(prefix = "")</td><td> Same as outputl() but appends a tab char instead of an NL char and is BUFFERED, not flushed.</td></tr>
</td></tr>
<tr><td>expr</td><td>strvar.logputl(prefix = "")</td><td><p>Output to stdlog with optional prefix.
<tr><td><p><code>expr</code></p></td><td><p><code>strvar.outputt(prefix = "")</code></p></td><td> <p>Same as outputl() but appends a tab char instead of an NL char and is BUFFERED, not flushed.</p>
</p>
</td></tr>
<p>Appends an NL char.
<tr><td><p><code>expr</code></p></td><td><p><code>strvar.logputl(prefix = "")</code></p></td><td><p>Output to stdlog with optional prefix.</p>
</p>
<p>Appends an NL char.</p>
<p>Is BUFFERED not flushed.
<p>Is BUFFERED not flushed.</p>
</p>
<p>Any of the six types of field mark chars present are converted to their visible versions,</p>
Any of the six types of field mark chars present are converted to their visible versions,
<p>
<div class="highlight light"><pre><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">logputl</span><span class="p">(</span><span class="s">&quot;xyz = &quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">/// Sends &quot;xyz = abc\n&quot; to stdlog buffer and is not flushed.</span>
<div class="highlight light"><pre><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">logputl</span><span class="p">(</span><span class="s">&quot;xyz = &quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">/// Sends &quot;xyz = abc\n&quot; to stdlog buffer and is not flushed.</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">logputl</span><span class="p">(</span><span class="s">&quot;xyz = &quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="p">);;</span><span class="w"> </span><span class="c1">/// Any number of arguments is allowed. All will be output.</span>
<span class="nf">logputl</span><span class="p">(</span><span class="s">&quot;xyz = &quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="p">);;</span><span class="w"> </span><span class="c1">/// Any number of arguments is allowed. All will be output.</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>expr</td><td>strvar.logput(prefix = "")</td><td> Same as logputl() but doesnt append an NL char.</td></tr>
<tr><td><p><code>expr</code></p></td><td><p><code>strvar.logput(prefix = "")</code></p></td><td> <p>Same as logputl() but doesnt append an NL char.</p>
<tr><td>expr</td><td>strvar.errputl(prefix = "")</td><td><p>Output to stderr with optional prefix.
</td></tr>
</p>
<tr><td><p><code>expr</code></p></td><td><p><code>strvar.errputl(prefix = "")</code></p></td><td><p>Output to stderr with optional prefix.</p>
<p>Appends an NL char.
<p>Appends an NL char.</p>
</p>
<p>Is FLUSHED not buffered.</p>
<p>Is FLUSHED not buffered.
<p>Any of the six types of field mark chars present are converted to their visible versions,</p>
</p>
<p>
Any of the six types of field mark chars present are converted to their visible versions,
<div class="highlight light"><pre><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">errputl</span><span class="p">(</span><span class="s">&quot;xyz = &quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">/// Sends &quot;xyz = abc\n&quot; to stderr</span>
<div class="highlight light"><pre><span class="s">&quot;abc&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">errputl</span><span class="p">(</span><span class="s">&quot;xyz = &quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">/// Sends &quot;xyz = abc\n&quot; to stderr</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">errputl</span><span class="p">(</span><span class="s">&quot;xyz = &quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">/// Any number of arguments is allowed. All will be output.</span>
<span class="nf">errputl</span><span class="p">(</span><span class="s">&quot;xyz = &quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;abc&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">/// Any number of arguments is allowed. All will be output.</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>expr</td><td>strvar.errput(prefix = "")</td><td> Same as errputl() but doesnt append an NL char and is BUFFERED not flushed.</td></tr>
<tr><td><p><code>expr</code></p></td><td><p><code>strvar.errput(prefix = "")</code></p></td><td> <p>Same as errputl() but doesnt append an NL char and is BUFFERED not flushed.</p>
<tr><td>expr</td><td>strvar.put(std::ostream& ostream1)</td><td><p>Output to a given stream.
</td></tr>
</p>
<tr><td><p><code>expr</code></p></td><td><p><code>strvar.put(std::ostream& ostream1)</code></p></td><td><p>Output to a given stream.</p>
<p>Is BUFFERED not flushed.
<p>Is BUFFERED not flushed.</p>
</p>
<p>The raw string bytes are output. No character or byte conversion is performed.</p>
<p>The raw string bytes are output. No character or byte conversion is performed.
</p>
</td></tr>
</td></tr>
<tr><td></td><td>var().osflush()</td><td>Flush any and all buffered output to stdout and stdlog.
<tr><td><p><code></code></p></td><td><p><code>var().osflush()</code></p></td><td><p>Flush any and all buffered output to stdout and stdlog.</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="p">().</span><span class="nf">osflush</span><span class="p">();</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="p">().</span><span class="nf">osflush</span><span class="p">();</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">osflush</span><span class="p">();</span>
<span class="nf">osflush</span><span class="p">();</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
</table>
</table>
Line 3,274: Line 3,495:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>if</td><td>var.input(prompt = "")</td><td><p>Returns one line of input from stdin.
<tr><td><p><code>if</code></p></td><td><p><code>var.input(prompt = "")</code></p></td><td><p>Read one line of input from stdin.</p>
</p>
<p><em>return:</em> True if successful or false if EOF or user pressed Esc or Ctrl+X in a terminal.</p>
<p><em>Returns:</em> True if successful or false if EOF or user pressed Esc or Ctrl+X in a terminal.
<p><em>var[in]:</em> The default value for terminal input and editing. Ignored if not a terminal.</p>
</p>
<p><em>var[out]:</em> Raw bytes up to but excluding the first new line char. In case of EOF or user pressed Esc or Ctrl+X in a terminal it will be changed to "".</p>
<p><em>var:</em> [in] The default value for terminal input and editing. Ignored if not a terminal.
<p><em>Prompt:</em> If provided, it will be displayed on the terminal.</p>
</p>
<p>Multibyte/UTF8 friendly.</p>
<p><em>var:</em> [out] Raw bytes up to but excluding the first new line char. In case of EOF or user pressed Esc or Ctrl+X in a terminal it will be changed to "".
<p>
</p>
<p><em>Prompt:</em> If provided, it will be displayed on the terminal.
</p>
Multibyte/UTF8 friendly.
<div class="highlight light"><pre><span class="c1">// var v1 = &quot;defaultvalue&quot;;</span>
<div class="highlight light"><pre><span class="c1">// var v1 = &quot;defaultvalue&quot;;</span>
<span class="c1">// if (v1.input(&quot;Prompt:&quot;)) ... ok</span>
<span class="c1">// if (v1.input(&quot;Prompt:&quot;)) ... ok</span>
Line 3,290: Line 3,507:
<span class="c1">// var v2 = input();</span>
<span class="c1">// var v2 = input();</span>
</pre></div>
</pre></div>
</td></tr>
<tr><td>expr</td><td>var.inputn(nchars)</td><td><p>Get raw bytes from standard input.
</p>
<p>Any new line chars are treated like any other bytes.
</p>
<p>Care must be taken to handle incomplete UTF8 byte sequences at the end of one block and the beginning of the next block.
</p>
<p><em>Returns:</em> The requested number of bytes or fewer if not available.
</p>
<p><em>nchars:</em>
</p>
<p>99 : Get up to 99 bytes or fewer if not available. Caution required with UTF8.
</p>
<p>⋅0 : Get all bytes presently available.
</p>
<p>⋅1 : Same as keypressed(true). Deprecated.
</p>
<p>-1 : Same as keypressed(). Deprecated.
</p>
</p>
</td></tr>
</td></tr>
<tr><td>expr</td><td>var.keypressed(wait = false)</td><td><p>Return the code of the current terminal key pressed.
<tr><td><p><code>expr</code></p></td><td><p><code>var.keypressed(wait = false)</code></p></td><td><p>Return the code of the current terminal key pressed.</p>
</p>
<p><em>wait:</em> Defaults to false. True means wait for a key to be pressed if not already pressed.</p>
<p><em>wait:</em> Defaults to false. True means wait for a key to be pressed if not already pressed.
<p><em>return:</em> ASCII or key code defined according to terminal protocol.</p>
</p>
<p><em>return:</em> "" if stdin is not a terminal.</p>
<p><em>Returns:</em> ASCII or key code defined according to terminal protocol.
<p>e.g. The PgDn key if pressed might return an escape sequence like "\x1b[6~"</p>
</p>
<p>It only takes a few µsecs to return false if no key is pressed.
<p><em>Returns:</em> "" if stdin is not a terminal.
</p>
<p>e.g. The PgDn key if pressed might return an escape sequence like "\x1b[6~"
</p>
It only takes a few µsecs to return false if no key is pressed.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="p">;</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">keypressed</span><span class="p">();</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="p">;</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">keypressed</span><span class="p">();</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">keypressed</span><span class="p">();</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">keypressed</span><span class="p">();</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>var().isterminal(arg = 1)</td><td><p>Checks if one of stdin, stdout, stderr is a terminal or a file/pipe.
<tr><td><p><code>if</code></p></td><td><p><code>var().isterminal(in_out_err = 1)</code></p></td><td><p>Check if is a terminal or a file/pipe.</p>
</p>
<p>Can check stdin, stdout, stderr.</p>
<p><em>arg:</em> 0 - stdin, 1 - stdout (Default), 2 - stderr.
<p><em>in_out_err:</em> </p>
</p>
<dl>
<p><em>Returns:</em> True if it is a terminal or false if it is a file or pipe.
<dt>0</dt><dd>stdin</dd>
</p>
<dt>1</dt><dd>stdout (Default)</dd>
<p>Note that if the process is at the start or end of a pipeline, then only stdin or stdout will be a terminal.
<dt>2</dt><dd>stderr.</dd>
</p>
</dl>
The type of stdout terminal can be obtained from the TERM environment variable.
<p><em>return:</em> True if it is a terminal or false if it is a file or pipe.</p>
<p>Note that if the process is at the start or end of a pipeline, then only stdin or stdout will be a terminal.</p>
<p>The type of stdout terminal can be obtained from the TERM environment variable.</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">().</span><span class="nf">isterminal</span><span class="p">();</span><span class="w"> </span><span class="c1">/// 1 or 0</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">().</span><span class="nf">isterminal</span><span class="p">();</span><span class="w"> </span><span class="c1">/// 1 or 0</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">isterminal</span><span class="p">();</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">isterminal</span><span class="p">();</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>var().hasinput(milliseconds = 0)</td><td><p>Checks if stdin has any bytes available for input.
<tr><td><p><code>if</code></p></td><td><p><code>var().hasinput(milliseconds = 0)</code></p></td><td><p>Check if stdin has any bytes available for input.</p>
</p>
<p>If no bytes are immediately available, the process sleeps for up to the given number of milliseconds, returning true immediately any bytes become available or false if the period expires without any bytes becoming available.</p>
<p>If no bytes are immediately available, the process sleeps for up to the given number of milliseconds, returning true immediately any bytes become available or false if the period expires without any bytes becoming available.
<p><em>return:</em> True if any bytes are available otherwise false.</p>
</p>
<p>It only takes a few µsecs to return false if no bytes are available and no wait time has been requested.</p>
<p><em>Returns:</em> True if any bytes are available otherwise false.
</p>
<p>It only takes a few µsecs to return false if no bytes are available and no wait time has been requested.
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>var().eof()</td><td><p>True if stdin is at end of file
<tr><td><p><code>if</code></p></td><td><p><code>var().eof()</code></p></td><td><p>True if stdin is at end of file</p>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>var().echo(on_off = true)</td><td><p>Sets terminal echo on or off.
<tr><td><p><code>if</code></p></td><td><p><code>var().echo(on_off = true)</code></p></td><td><p>Set terminal echo on or off.</p>
</p>
<p>"On" causes all stdin data to be reflected to stdout if stdin is a terminal.</p>
<p>"On" causes all stdin data to be reflected to stdout if stdin is a terminal.
<p>Turning terminal echo off can be used to prevent display of confidential information.</p>
</p>
<p><em>return:</em> True if successful.</p>
<p>Turning terminal echo off can be used to prevent display of confidential information.
</p>
<p><em>Returns:</em> True if successful.
</p>
</td></tr>
</td></tr>
<tr><td></td><td>var().breakon()</td><td><p>Install various interrupt handlers.
<tr><td><p><code></code></p></td><td><p><code>var().breakon()</code></p></td><td><p>Install various interrupt handlers.</p>
</p>
<p>Automatically called in program/thread initialisation by exodus_main.</p>
<p>Automatically called in program/thread initialisation by exodus_main.
<dl>
</p>
<dt>SIGINT</dt><dd>Ctrl+C -&gt; "Interrupted. (C)ontinue (Q)uit (B)acktrace (D)ebug (A)bort ?"</dd>
<p>* SIGINT - Ctrl+C -> "Interrupted. (C)ontinue (Q)uit (B)acktrace (D)ebug (A)bort ?"
<dt>SIGHUP</dt><dd>Sets a variable "RELOAD_req" which may be handled or ignored by the program.</dd>
</p>
<dt>SIGTERM</dt><dd>Sets a variable "TERMINATE_req" which may be handled or ignored by the program.</dd>
<p>* SIGHUP - Sets a variable "RELOAD_req" which may be handled or ignored by the program.
</dl>
</p>
<p>* SIGTERM - Sets a variable "TERMINATE_req" which may be handled or ignored by the program.
</p>
</td></tr>
</td></tr>
<tr><td></td><td>var().breakoff()</td><td><p>Disable keyboard interrupt.
<tr><td><p><code></code></p></td><td><p><code>var().breakoff()</code></p></td><td><p>Disable keyboard interrupt.</p>
</p>
<p>Ctrl+C becomes inactive in terminal.</p>
<p>Ctrl+C becomes inactive in terminal.
</p>
</td></tr>
</td></tr>
</table>
</table>
Line 3,382: Line 3,567:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>var=</td><td>varnum.abs()</td><td>Absolute value
<tr><td><p><code>var=</code></p></td><td><p><code>varnum.abs()</code></p></td><td><p>Absolute value.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">-12.34</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">-12.34</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">abs</span><span class="p">();</span><span class="w"> </span><span class="c1">// 12.34</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">abs</span><span class="p">();</span><span class="w"> </span><span class="c1">// 12.34</span>
Line 3,388: Line 3,573:
<span class="nf">let</span><span class="w"> </span><span class="n">v3</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">abs</span><span class="p">(</span><span class="n">v1</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v3</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">abs</span><span class="p">(</span><span class="n">v1</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>varnum.pwr(exponent)</td><td>Power
<tr><td><p><code>var=</code></p></td><td><p><code>varnum.pwr(exponent)</code></p></td><td><p>Power.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mi">2</span><span class="p">).</span><span class="nf">pwr</span><span class="p">(</span><span class="mi">8</span><span class="p">);</span><span class="w"> </span><span class="c1">// 256</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mi">2</span><span class="p">).</span><span class="nf">pwr</span><span class="p">(</span><span class="mi">8</span><span class="p">);</span><span class="w"> </span><span class="c1">// 256</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">pwr</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">8</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">pwr</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">8</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>varnum.initrnd()</td><td><p>Initialise the seed for rnd()
<tr><td><p><code></code></p></td><td><p><code>varnum.initrnd()</code></p></td><td><p>Initialise the seed for rnd().</p>
</p>
<p>Allow the stream of pseudo random numbers generated by rnd() to be reproduced.</p>
<p>Allows the stream of pseudo random numbers generated by rnd() to be reproduced.
<p>Seeded from std::chrono::high_resolution_clock::now() if the argument is 0;</p>
</p>
<p>
Seeded from std::chrono::high_resolution_clock::now() if the argument is 0;
<div class="highlight light"><pre><span class="kt">var</span><span class="p">(</span><span class="mi">123</span><span class="p">).</span><span class="nf">initrnd</span><span class="p">();</span><span class="w"> </span><span class="c1">/// Set seed to 123</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="p">(</span><span class="mi">123</span><span class="p">).</span><span class="nf">initrnd</span><span class="p">();</span><span class="w"> </span><span class="c1">/// Set seed to 123</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">initrnd</span><span class="p">(</span><span class="mi">123</span><span class="p">);</span>
<span class="nf">initrnd</span><span class="p">(</span><span class="mi">123</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>varnum.rnd()</td><td><p>Pseudo random number generator
<tr><td><p><code>var=</code></p></td><td><p><code>varnum.rnd()</code></p></td><td><p>Pseudo random number generator.</p>
</p>
<p><em>return:</em> A pseudo random integer between 0 and the provided maximum minus 1.</p>
<p><em>Returns:</em> a pseudo random integer between 0 and the provided maximum minus 1.
<p>Uses std::mt19937 and std::uniform_int_distribution&lt;int&gt;</p>
</p>
<p>
Uses std::mt19937 and std::uniform_int_distribution<int>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mi">100</span><span class="p">).</span><span class="nf">rnd</span><span class="p">();</span><span class="w"> </span><span class="c1">/// Random 0 to 99</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mi">100</span><span class="p">).</span><span class="nf">rnd</span><span class="p">();</span><span class="w"> </span><span class="c1">/// Random 0 to 99</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">rnd</span><span class="p">(</span><span class="mi">100</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">rnd</span><span class="p">(</span><span class="mi">100</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>varnum.exp()</td><td>Power of e
<tr><td><p><code>var=</code></p></td><td><p><code>varnum.exp()</code></p></td><td><p>Power of e.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mi">1</span><span class="p">).</span><span class="nf">exp</span><span class="p">();</span><span class="w"> </span><span class="c1">// 2.718281828459045</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mi">1</span><span class="p">).</span><span class="nf">exp</span><span class="p">();</span><span class="w"> </span><span class="c1">// 2.718281828459045</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">exp</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">exp</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>varnum.sqrt()</td><td>Square root
<tr><td><p><code>var=</code></p></td><td><p><code>varnum.sqrt()</code></p></td><td><p>Square root.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mi">100</span><span class="p">).</span><span class="nf">sqrt</span><span class="p">();</span><span class="w"> </span><span class="c1">// 10</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mi">100</span><span class="p">).</span><span class="nf">sqrt</span><span class="p">();</span><span class="w"> </span><span class="c1">// 10</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">sqrt</span><span class="p">(</span><span class="mi">100</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">sqrt</span><span class="p">(</span><span class="mi">100</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>varnum.sin()</td><td>Sine of degrees
<tr><td><p><code>var=</code></p></td><td><p><code>varnum.sin()</code></p></td><td><p>Sine of degrees.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mi">30</span><span class="p">).</span><span class="nf">sin</span><span class="p">();</span><span class="w"> </span><span class="c1">// 0.5</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mi">30</span><span class="p">).</span><span class="nf">sin</span><span class="p">();</span><span class="w"> </span><span class="c1">// 0.5</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">sin</span><span class="p">(</span><span class="mi">30</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">sin</span><span class="p">(</span><span class="mi">30</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>varnum.cos()</td><td>Cosine of degrees
<tr><td><p><code>var=</code></p></td><td><p><code>varnum.cos()</code></p></td><td><p>Cosine of degrees.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mi">60</span><span class="p">).</span><span class="nf">cos</span><span class="p">();</span><span class="w"> </span><span class="c1">// 0.5</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mi">60</span><span class="p">).</span><span class="nf">cos</span><span class="p">();</span><span class="w"> </span><span class="c1">// 0.5</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">cos</span><span class="p">(</span><span class="mi">60</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">cos</span><span class="p">(</span><span class="mi">60</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>varnum.tan()</td><td>Tangent of degrees
<tr><td><p><code>var=</code></p></td><td><p><code>varnum.tan()</code></p></td><td><p>Tangent of degrees.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mi">45</span><span class="p">).</span><span class="nf">tan</span><span class="p">();</span><span class="w"> </span><span class="c1">// 1</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mi">45</span><span class="p">).</span><span class="nf">tan</span><span class="p">();</span><span class="w"> </span><span class="c1">// 1</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">tan</span><span class="p">(</span><span class="mi">45</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">tan</span><span class="p">(</span><span class="mi">45</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>varnum.atan()</td><td>Arctangent of degrees
<tr><td><p><code>var=</code></p></td><td><p><code>varnum.atan()</code></p></td><td><p>Arctangent of degrees.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mi">1</span><span class="p">).</span><span class="nf">atan</span><span class="p">();</span><span class="w"> </span><span class="c1">// 45</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mi">1</span><span class="p">).</span><span class="nf">atan</span><span class="p">();</span><span class="w"> </span><span class="c1">// 45</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">atan</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">atan</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>varnum.loge()</td><td><p>Natural logarithm
<tr><td><p><code>var=</code></p></td><td><p><code>varnum.loge()</code></p></td><td><p>Natural logarithm.</p>
</p>
<p><em>return:</em> Floating point var (double)
<em>Returns:</em> Floating point ver (double)
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mf">2.718281828459045</span><span class="p">).</span><span class="nf">loge</span><span class="p">();</span><span class="w"> </span><span class="c1">// 1</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mf">2.718281828459045</span><span class="p">).</span><span class="nf">loge</span><span class="p">();</span><span class="w"> </span><span class="c1">// 1</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">loge</span><span class="p">(</span><span class="mf">2.718281828459045</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">loge</span><span class="p">(</span><span class="mf">2.718281828459045</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>varnum.integer()</td><td><p>Truncate decimal numbers towards zero
<tr><td><p><code>var=</code></p></td><td><p><code>varnum.integer()</code></p></td><td><p>Truncate decimals.</p>
</p>
<p>Convert decimal to nearest integer towards zero.</p>
<em>Returns:</em> An integer var
<p>Remove decimal fraction.</p>
<p><em>return:</em> An integer var
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mf">2.9</span><span class="p">).</span><span class="nf">integer</span><span class="p">();</span><span class="w"> </span><span class="c1">// 2</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mf">2.9</span><span class="p">).</span><span class="nf">integer</span><span class="p">();</span><span class="w"> </span><span class="c1">// 2</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
Line 3,470: Line 3,664:
<span class="kt">var</span><span class="w"> </span><span class="n">v4</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">integer</span><span class="p">(</span><span class="mf">-2.9</span><span class="p">);</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v4</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">integer</span><span class="p">(</span><span class="mf">-2.9</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>varnum.floor()</td><td><p>Truncate decimal numbers towards negative
<tr><td><p><code>var=</code></p></td><td><p><code>varnum.floor()</code></p></td><td><p>Floor decimals.</p>
</p>
<p>Convert decimal to nearest integer towards negative infinity.</p>
<em>Returns:</em> An integer var
<p><em>return:</em> An integer var
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mf">2.9</span><span class="p">).</span><span class="nf">floor</span><span class="p">();</span><span class="w"> </span><span class="c1">// 2</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mf">2.9</span><span class="p">).</span><span class="nf">floor</span><span class="p">();</span><span class="w"> </span><span class="c1">// 2</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
Line 3,482: Line 3,677:
<span class="kt">var</span><span class="w"> </span><span class="n">v4</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">floor</span><span class="p">(</span><span class="mf">-2.9</span><span class="p">);</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v4</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">floor</span><span class="p">(</span><span class="mf">-2.9</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>varnum.mod(modulus)</td><td><p>Modulus function
<tr><td><p><code>var=</code></p></td><td><p><code>varnum.mod(modulus)</code></p></td><td><p>Modulus function.</p>
</p>
<p>Identical to C++ % operator only for positive numbers and modulus</p>
<p>Identical to C++ % operator only for positive numbers and modulus
<p>Negative denominators are considered as periodic with positive numbers</p>
</p>
<p>Result is between [0, modulus) if modulus is positive</p>
<p>Negative denominators are considered as periodic with positiive numbers
<p>Result is between (modulus, 0] if modulus is negative (symmetric)</p>
</p>
<p><em>throw:</em> VarDivideByZero if modulus is zero.</p>
<p>Result is between [0, modulus) if modulus is positive
<p>Floating point works.
</p>
<p>Result is between (modulus, 0] if modulus is negative (symmetric)
</p>
<p><em>Throws:</em> VarDivideByZero if modulus is zero.
</p>
Floating point works.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mi">11</span><span class="p">).</span><span class="nf">mod</span><span class="p">(</span><span class="mi">5</span><span class="p">);</span><span class="w"> </span><span class="c1">// 1</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mi">11</span><span class="p">).</span><span class="nf">mod</span><span class="p">(</span><span class="mi">5</span><span class="p">);</span><span class="w"> </span><span class="c1">// 1</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
Line 3,503: Line 3,693:
<span class="nf">let</span><span class="w"> </span><span class="n">v5</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">mod</span><span class="p">(</span><span class="mi">-11</span><span class="p">,</span><span class="w"> </span><span class="mi">-5</span><span class="p">);</span><span class="w"> </span><span class="c1">// -1</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v5</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">mod</span><span class="p">(</span><span class="mi">-11</span><span class="p">,</span><span class="w"> </span><span class="mi">-5</span><span class="p">);</span><span class="w"> </span><span class="c1">// -1</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>int=</td><td>var::setprecision(newprecision)</td><td><p>Set the maximum floating point precision.
<tr><td><p><code>int=</code></p></td><td><p><code>var::setprecision(newprecision)</code></p></td><td><p>Set floating point precision.</p>
</p>
<p>This is the number of post-decimal point digits to consider for floating point comparison and implicit conversion to strings.</p>
<p>This is the number of post-decimal point digits to consider for floating point comparison and implicit conversion to strings.
<p>The default precision is 4 which is 0.0001.</p>
</p>
<p>NUMBERS AND DIFFERENCES SMALLER THAN 0.0001 ARE TREATED AS ZERO UNLESS PRECISION IS INCREASED.</p>
<p>The default precision is 4 which is 0.0001.
<p>With the default precision, Exodus handles, without assistance, conversion to and from strings for positive and negative numbers between 0.0001 and 999'999'999'999.9999 (12 digits).</p>
</p>
<p><em>newprecision:</em> New precision between -307 and 308 inclusive.</p>
<p>NUMBERS AND DIFFERENCES SMALLER THAN 0.0001 ARE TREATED AS ZERO UNLESS PRECISION IS INCREASED.
<p><em>return:</em> The new precision if successful or the old precision if not.</p>
</p>
<p>Not required if using common numbers or using the explicit rounding and formatting functions to convert numbers to strings.</p>
<p><em>newprecision:</em> New precision between -307 and 308 inclusive.
<p>Increasing the precision allows comparing and outputting smaller numbers but creates errors handling large numbers.</p>
</p>
<p>Setting precision inside a perform, execute or dictionary function lasts until termination of the function.</p>
<p><em>Returns:</em> The new precision if successful or the old precision if not.
<p>See cli/demo_precision for more info.</p>
</p>
<p>
<p>Not required if using common numbers or using the explicit rounding and formatting functions to convert numbers to strings.
</p>
<p>Increasing the precision allows comparing and outputting smaller numbers but creates errors handling large numbers.
</p>
<p>Setting precision inside a perform, execute or dictionary function lasts until termination of the function.
</p>
See cli/demo_precision for more info.
<div class="highlight light"><pre><span class="n">assert</span><span class="p">(</span><span class="mf">0.000001</span><span class="kt">_var</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="mi">0</span><span class="p">);</span><span class="w"> </span><span class="c1">/// NOTE WELL: Default precision 4.</span>
<div class="highlight light"><pre><span class="n">assert</span><span class="p">(</span><span class="mf">0.000001</span><span class="kt">_var</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="mi">0</span><span class="p">);</span><span class="w"> </span><span class="c1">/// NOTE WELL: Default precision 4.</span>
<span class="nf">let</span><span class="w"> </span><span class="n">new_precision1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">setprecision</span><span class="p">(</span><span class="mi">6</span><span class="p">);</span><span class="w"> </span><span class="c1">// 6 // Increase the precision.</span>
<span class="nf">let</span><span class="w"> </span><span class="n">new_precision1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">setprecision</span><span class="p">(</span><span class="mi">6</span><span class="p">);</span><span class="w"> </span><span class="c1">// 6 // Increase the precision.</span>
Line 3,529: Line 3,713:
<span class="n">assert</span><span class="p">(</span><span class="mf">0.000001</span><span class="kt">_var</span><span class="w"> </span><span class="o">!=</span><span class="w"> </span><span class="mi">0</span><span class="p">);</span><span class="w"> </span><span class="c1">/// NOTE: Precision 6.</span>
<span class="n">assert</span><span class="p">(</span><span class="mf">0.000001</span><span class="kt">_var</span><span class="w"> </span><span class="o">!=</span><span class="w"> </span><span class="mi">0</span><span class="p">);</span><span class="w"> </span><span class="c1">/// NOTE: Precision 6.</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>int=</td><td>var::getprecision()</td><td>
<tr><td><p><code>int=</code></p></td><td><p><code>var::getprecision()</code></p></td><td><p>Get current floating point precision.</p>
<p><em>Returns:</em> The current precision setting.
<p><em>return:</em> The current precision setting.</p>
</p>
<p>See setprecision() for more info.</p>
See setprecision() for more info.
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">curr_precision1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">getprecision</span><span class="p">();</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">curr_precision1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="o">::</span><span class="nf">getprecision</span><span class="p">();</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">curr_precision2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">getprecision</span><span class="p">();</span>
<span class="nf">let</span><span class="w"> </span><span class="n">curr_precision2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">getprecision</span><span class="p">();</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
</table>
</table>
Line 3,544: Line 3,730:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>var=</td><td>vardate.oconv("D")</td><td><p>Date output: Convert internal date format to human readable date or calendar info in text format.
<tr><td><p><code>var=</code></p></td><td><p><code>vardate.oconv("D")</code></p></td><td><p>oconv "D" Convert internal date to external format.</p>
</p>
<p>Date output: Convert internal date format to human readable date or calendar info in text format.</p>
<p><em>Returns:</em> Human readable date or calendar info, or the original value unconverted if non-numeric.
<p><em>return:</em> Human readable date or calendar info, or the original value unconverted if non-numeric.</p>
</p>
<p><em>flags:</em> See examples below.</p>
<p><em>flags:</em> See examples below.
<p>Any Dynamic array structure is preserved.</p>
</p>
<p>
Any Dynamic array structure is preserved.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">19002</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">19002</span><span class="p">;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="p">;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="p">;</span>
Line 3,579: Line 3,764:
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w">  </span><span class="n">v1</span><span class="p">.</span><span class="nf">oconv</span><span class="p">(</span><span class="w"> </span><span class="s">&quot;DW&quot;</span><span class="w">  </span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  &quot;4&quot;            // Weekday number (1-7)</span>
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w">  </span><span class="n">v1</span><span class="p">.</span><span class="nf">oconv</span><span class="p">(</span><span class="w"> </span><span class="s">&quot;DW&quot;</span><span class="w">  </span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  &quot;4&quot;            // Weekday number (1-7)</span>
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w">  </span><span class="n">v1</span><span class="p">.</span><span class="nf">oconv</span><span class="p">(</span><span class="w"> </span><span class="s">&quot;DWA&quot;</span><span class="w"> </span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  &quot;THURSDAY&quot;      // Weekday name</span>
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w">  </span><span class="n">v1</span><span class="p">.</span><span class="nf">oconv</span><span class="p">(</span><span class="w"> </span><span class="s">&quot;DWA&quot;</span><span class="w"> </span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  &quot;THURSDAY&quot;      // Weekday name</span>
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w">  </span><span class="n">v1</span><span class="p">.</span><span class="nf">oconv</span><span class="p">(</span><span class="w"> </span><span class="s">&quot;</span><span class="kc">DQ</span><span class="s">&quot;</span><span class="w">  </span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  &quot;1&quot;            // Quarter number</span>
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w">  </span><span class="n">v1</span><span class="p">.</span><span class="nf">oconv</span><span class="p">(</span><span class="w"> </span><span class="s">&quot;</span><span class="nb">DQ</span><span class="s">&quot;</span><span class="w">  </span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  &quot;1&quot;            // Quarter number</span>
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w">  </span><span class="n">v1</span><span class="p">.</span><span class="nf">oconv</span><span class="p">(</span><span class="w"> </span><span class="s">&quot;DJ&quot;</span><span class="w">  </span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  &quot;9&quot;            // Day number in year</span>
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w">  </span><span class="n">v1</span><span class="p">.</span><span class="nf">oconv</span><span class="p">(</span><span class="w"> </span><span class="s">&quot;DJ&quot;</span><span class="w">  </span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  &quot;9&quot;            // Day number in year</span>
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w">  </span><span class="n">v1</span><span class="p">.</span><span class="nf">oconv</span><span class="p">(</span><span class="w"> </span><span class="s">&quot;DL&quot;</span><span class="w">  </span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  &quot;31&quot;            // Last day number of month (28-31)</span>
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w">  </span><span class="n">v1</span><span class="p">.</span><span class="nf">oconv</span><span class="p">(</span><span class="w"> </span><span class="s">&quot;DL&quot;</span><span class="w">  </span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  &quot;31&quot;            // Last day number of month (28-31)</span>
Line 3,587: Line 3,772:
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v3</span><span class="p">.</span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;D&quot;</span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  &quot;18 OCT 2001^19 OCT 2001]20 OCT 2001&quot;_var</span>
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v3</span><span class="p">.</span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;D&quot;</span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  &quot;18 OCT 2001^19 OCT 2001]20 OCT 2001&quot;_var</span>


<span class="w"> </span><span class="c1">// or</span>
<span class="c1">// or</span>
<span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w">  </span><span class="nf">oconv</span><span class="p">(</span><span class="n">v3</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;D&quot;</span><span class="w">  </span><span class="p">)</span><span class="w"> </span><span class="p">;</span>
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w">  </span><span class="nf">oconv</span><span class="p">(</span><span class="n">v3</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;D&quot;</span><span class="w">  </span><span class="p">)</span><span class="w"> </span><span class="p">;</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.iconv("D")</td><td><p>Date input: Convert human readable date to internal date format.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.iconv("D")</code></p></td><td><p>iconv "D" Convert external date format to internal.</p>
</p>
<p>Date input: Convert human readable date to internal date format.</p>
<p><em>Returns:</em> Internal date or "" if the input is an invalid date.
<p><em>return:</em> Internal date or "" if the input is an invalid date.</p>
</p>
<p>Internal date format is whole days since 1967-12-31 00:00:00 which is day 0.</p>
<p>Internal date format is whole days since 1967-12-31 00:00:00 which is day 0.
<p>Any Dynamic array structure is preserved.</p>
</p>
<p>
Any Dynamic array structure is preserved.
<div class="highlight light"><pre><span class="c1">// International order &quot;DE&quot;</span>
<div class="highlight light"><pre><span class="c1">// International order &quot;DE&quot;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="p">;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="p">;</span>
Line 3,625: Line 3,810:
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">iconv</span><span class="p">(</span><span class="s">&quot;12/1/2020&quot;</span><span class="kt">_var</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;DE&quot;</span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  19005</span>
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">iconv</span><span class="p">(</span><span class="s">&quot;12/1/2020&quot;</span><span class="kt">_var</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;DE&quot;</span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  19005</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>vartime.oconv("MT")</td><td><p>Time output: Convert internal time format to human readable time e.g. "10:30:59".
<tr><td><p><code>var=</code></p></td><td><p><code>vartime.oconv("MT")</code></p></td><td><p>oconv "MT" Convert internal time to external format.</p>
</p>
<p>Time output: Convert internal time format to human readable time e.g. "10:30:59".</p>
<p><em>Returns:</em> Human readable time or the original value unconverted if non-numeric.
<p><em>return:</em> Human readable time or the original value unconverted if non-numeric.</p>
</p>
<p>Conversion code (e.g. "MTHS") is "MT" ^ flags ...</p>
<p>Conversion code (e.g. "MTHS") is "MT" + flags ...
<p><em>flags:</em> </p>
</p>
<dl>
<p><em>flags:</em>
<dt>H</dt><dd>Show AM/PM otherwise 24 hour clock is used.</dd>
</p>
<dt>S</dt><dd>Output seconds</dd>
<p>* "H" - Show AM/PM otherwise 24 hour clock is used.
<dt>2</dt><dd>Ignored (used in iconv)</dd>
</p>
<dt>:</dt><dd>Any other flag is used as the separator char instead of ":"</dd>
<p>* "S" - Output seconds
</dl>
</p>
<p>Any Dynamic array structure is preserved.</p>
<p>* "2" = Ignored (used in iconv)
<p>
</p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w">  </span><span class="o">=</span><span class="w"> </span><span class="mi">62000</span><span class="p">;</span>
<p>* ":" - Any other flag is used as the separator char instead of ":"
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="p">;</span>
</p>
Any Dynamic array structure is preserved.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w">  </span><span class="o">=</span><span class="w"> </span><span class="mi">62000</span><span class="p">;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="p">;</span>
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;MT&quot;</span><span class="w">  </span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;17:13&quot;      // Default</span>
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;MT&quot;</span><span class="w">  </span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;17:13&quot;      // Default</span>
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;MTH&quot;</span><span class="w"> </span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;05:13PM&quot;    // &#39;H&#39; flag for AM/PM</span>
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;MTH&quot;</span><span class="w"> </span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;05:13PM&quot;    // &#39;H&#39; flag for AM/PM</span>
Line 3,663: Line 3,845:
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">oconv</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;MT&quot;</span><span class="p">);</span><span class="w">    </span><span class="c1">// &quot;17:13&quot;</span>
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">oconv</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;MT&quot;</span><span class="p">);</span><span class="w">    </span><span class="c1">// &quot;17:13&quot;</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.iconv("MT")</td><td><p>Time input: Convert human readable time (e.g. "10:30:59") to internal time format.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.iconv("MT")</code></p></td><td><p>iconv "MT" Convert external time format to internal.</p>
</p>
<p>Time input: Convert human readable time (e.g. "10:30:59") to internal time format.</p>
<p><em>Returns:</em> Internal time or "" if the input is an invalid time.
<p><em>return:</em> Internal time or "" if the input is an invalid time.</p>
</p>
<p>Internal time format is whole seconds since midnight.</p>
<p>Internal time format is whole seconds since midnight.
<p><em>Accepts:</em> Two or three groups of digits surrounded and separated by any non-digits char(s).</p>
</p>
<p>Any Dynamic array structure is preserved.</p>
<p><em>Accepts:</em> Two or three groups of digits surrounded and separated by any non-digits char(s).
<p>
</p>
Any Dynamic array structure is preserved.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="p">;</span>
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w">      </span><span class="s">&quot;17:13&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">iconv</span><span class="p">(</span><span class="w"> </span><span class="s">&quot;MT&quot;</span><span class="w"> </span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  61980</span>
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w">      </span><span class="s">&quot;17:13&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">iconv</span><span class="p">(</span><span class="w"> </span><span class="s">&quot;MT&quot;</span><span class="w"> </span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  61980</span>
Line 3,691: Line 3,872:
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">iconv</span><span class="p">(</span><span class="s">&quot;17:13&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;MT&quot;</span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  61980</span>
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">iconv</span><span class="p">(</span><span class="s">&quot;17:13&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;MT&quot;</span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  61980</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>varnum.oconv("MD")</td><td><p>Number output: Convert internal numbers to external text format after rounding and optional scaling.
<tr><td><p><code>var=</code></p></td><td><p><code>varnum.oconv("MD")</code></p></td><td><p>oconv "MD" Convert internal numbers to external format.</p>
</p>
<p>Number output: Convert internal numbers to external text format after rounding and optional scaling.</p>
<p><em>Returns:</em> A string or, if the value is not numeric, then no conversion is performed and the original value is returned.
<p><em>return:</em> A string or, if the value is not numeric, then no conversion is performed and the original value is returned.</p>
</p>
<p><em>conversion_code:</em> (e.g. "MD20Z") is "MD" or "MC", 1st digit, 2nd digit, flags ...</p>
<p><em>conversion_code:</em> (e.g. "MD20Z") is "MD" or "MC", 1st digit, 2nd digit, flags ...
<dl>
</p>
<dt>"MD"</dt><dd>Outputs like 123.45 (International)</dd>
<p>* MD outputs like 123.45 (International)
<dt>"MC"</dt><dd>Outputs like 123,45 (European)</dd>
</p>
</dl>
<p>* MC outputs like 123,45 (European)
<p>1st digit * Decimal places to display. Also decimal places to move if 2nd digit not present and no P flag present.</p>
</p>
<p>2nd digit * Optional decimal places to move left if P flag not present.</p>
<p>* 1st digit = Decimal places to display. Also decimal places to move if 2nd digit not present and no P flag present.
<p></p>
</p>
<p><em>flags:</em> </p>
<p>* 2nd digit = Optional decimal places to move left if P flag not present.
<dl>
</p>
<dt>P</dt><dd>Preserve decimal places. Same as 2nd digit = 0;</dd>
 
<dt>Z</dt><dd>Zero flag - return "" if zero.</dd>
<p><em>flags:</em>
<dt>X</dt><dd>No conversion - return as is.</dd>
</p>
<dt>.</dt><dd>Separate thousands depending on MD or MC.</dd>
<p>* "P" - Preserve decimal places. Same as 2nd digit = 0;
<dt>,</dt><dd>Ditto</dd>
</p>
<dt>-</dt><dd>Suffix negatives with "-" and positives with " " (space).</dd>
<p>* "Z" - Zero flag - return "" if zero.
<dt>&lt;</dt><dd>Wrap negatives in "&lt;" and "&gt;" chars.</dd>
</p>
<dt>C</dt><dd>Suffix negatives with "CR" and positives or zero with "DB".</dd>
<p>* "X" - No conversion - return as is.
<dt>D</dt><dd>Suffix negatives with "DB" and positives or zero with "CR".</dd>
</p>
</dl>
<p>* "." or "," - Separate thousands depending on MD or MC.
<p> <p>Any Dynamic array structure is preserved.</p>
</p>
<p>* "-" means suffix negatives with "-" and positives with " " (space).
</p>
<p>* "<" means wrap negatives in "<" and ">" chars.
</p>
</p>
<p>* "C" means suffix negatives with "CR" and positives or zero with "DB".
<p>
</p>
<p>* "D" means suffix negatives with "DB" and positives or zero with "CR".
</p>
 
Any Dynamic array structure is preserved.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">-1234.567</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">-1234.567</span><span class="p">;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="p">;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="p">;</span>
Line 3,743: Line 3,916:
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w">  </span><span class="nf">oconv</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;MD20&quot;</span><span class="w">  </span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  &quot;-1234.57&quot;  </span>
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w">  </span><span class="nf">oconv</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;MD20&quot;</span><span class="w">  </span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  &quot;-1234.57&quot;  </span>
</pre></div></td></tr>
</pre></div>
<tr><td>var=</td><td>var.oconv("LRC")</td><td><p>Text justification: Left, right and center. Padding and truncating. See Procrustes.
</p>
</p>
<p>e.g. "L#10", "R#10", "C#10"
</td></tr>
</p>
<tr><td><p><code>var=</code></p></td><td><p><code>var.oconv("LRC")</code></p></td><td><p>oconv "L" "R" "C" Justify text and numbers.</p>
<p>Useful when outputting to terminal devices where spaces are used for alignment.
<p>Text justification: Left, right and center. Padding and truncating. See Procrustes.</p>
</p>
<p>e.g. "L#10", "R#10", "C#10"</p>
<p>Dynamic array structure is preserved.
<p>Useful when outputting to terminal devices where spaces are used for alignment.</p>
</p>
<p>Dynamic array structure is preserved.</p>
ASCII only.
<p>ASCII only.</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="p">;</span>
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w">      </span><span class="s">&quot;abcde&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">oconv</span><span class="p">(</span><span class="w"> </span><span class="s">&quot;L#3&quot;</span><span class="w"> </span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  &quot;abc&quot;  // Truncating</span>
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w">      </span><span class="s">&quot;abcde&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">oconv</span><span class="p">(</span><span class="w"> </span><span class="s">&quot;L#3&quot;</span><span class="w"> </span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  &quot;abc&quot;  // Truncating</span>
Line 3,776: Line 3,949:
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w">      </span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;abcd&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;L#3&quot;</span><span class="w"> </span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  &quot;abc&quot; </span>
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w">      </span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;abcd&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;L#3&quot;</span><span class="w"> </span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  &quot;abc&quot; </span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.oconv("T")</td><td><p>Text folding and justification.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.oconv("T")</code></p></td><td><p>oconv "T" Justify and fold text.</p>
</p>
<p>e.g. T#20</p>
<p>e.g. T#20
<p>Useful when outputting to terminal devices where spaces are used for alignment.</p>
</p>
<p>Split text into multiple fixed length lines by inserting spaces and TM chars.</p>
<p>Useful when outputting to terminal devices where spaces are used for alignment.
<p>ASCII only.</p>
</p>
<p>
<p>Splits text into multiple fixed length lines by inserting spaces and TM chars.
</p>
ASCII only.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Have a nice day&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Have a nice day&quot;</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;T#10&quot;</span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  &quot;Have a␣␣␣␣|nice day␣␣&quot;_var</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;T#10&quot;</span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  &quot;Have a␣␣␣␣|nice day␣␣&quot;_var</span>
Line 3,791: Line 3,962:
<span class="nf">let</span><span class="w"> </span><span class="n">v3</span><span class="w">  </span><span class="o">=</span><span class="w"> </span><span class="nf">oconv</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;T#10&quot;</span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  &quot;Have a␣␣␣␣|nice day␣␣&quot;_var </span>
<span class="nf">let</span><span class="w"> </span><span class="n">v3</span><span class="w">  </span><span class="o">=</span><span class="w"> </span><span class="nf">oconv</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;T#10&quot;</span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  &quot;Have a␣␣␣␣|nice day␣␣&quot;_var </span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>expr</td><td>varnum.oconv("MR")</td><td><p>Character replacement
<tr><td><p><code>expr</code></p></td><td><p><code>varnum.oconv("MR")</code></p></td><td><p>oconv "MR" Replace characters.</p>
</p>
<p>e.g. MRU
e.g. MRU
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;123/abC.&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;123/abC.&quot;</span><span class="p">;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="p">;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="p">;</span>
Line 3,807: Line 3,978:
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;MR/B&quot;</span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  &quot;/.&quot;      // Remove alphanumeric</span>
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">v1</span><span class="p">.</span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;MR/B&quot;</span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  &quot;/.&quot;      // Remove alphanumeric</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.oconv("HEX")</td><td><p>Convert the chars of a string to a string of pairs of hexadecimal digits.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.oconv("HEX")</code></p></td><td><p>oconv "HEX" Convert a string of chars to a string of pairs of hexadecimal digits.</p>
</p>
<p><em>strvar:</em> A string. Numbers will be converted to strings for conversion. 1.2 -&gt; "1.2" -&gt; hex "312E32"</p>
<p><em>strvar:</em> A string. Numbers will be converted to strings for conversion. 1.2 -> "1.2" -> hex "312E32"
<p>Dynamic array structure is not preserved. Field marks are converted to HEX as for all other bytes.</p>
</p>
<p>The size of the output is always precisely double that of the input.</p>
<p>Dynamic array structure is not preserved. Field marks are converted to HEX as for all other bytes.
<p>This function is the exact inverse of iconv("HEX").</p>
</p>
<p>
<p>The size of the output is always precisely double that of the input.
</p>
This function is the exact inverse of iconv("HEX").
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="p">;</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v2</span><span class="p">;</span>
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w">      </span><span class="s">&quot;ab01&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">oconv</span><span class="p">(</span><span class="w"> </span><span class="s">&quot;HEX&quot;</span><span class="w"> </span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  &quot;61&quot; &quot;62&quot; &quot;30&quot; &quot;31&quot;</span>
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w">      </span><span class="s">&quot;ab01&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">oconv</span><span class="p">(</span><span class="w"> </span><span class="s">&quot;HEX&quot;</span><span class="w"> </span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  &quot;61&quot; &quot;62&quot; &quot;30&quot; &quot;31&quot;</span>
Line 3,826: Line 3,995:
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w">      </span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;ab01&quot;</span><span class="kt">_var</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;HEX&quot;</span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  &quot;61&quot; &quot;62&quot; &quot;30&quot; &quot;31&quot;</span>
<span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w">      </span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;ab01&quot;</span><span class="kt">_var</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;HEX&quot;</span><span class="p">)</span><span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="c1">//  &quot;61&quot; &quot;62&quot; &quot;30&quot; &quot;31&quot;</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.iconv("HEX")</td><td><p>Convert a string of pairs of hexadecimal digits to a string of chars.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.iconv("HEX")</code></p></td><td><p>iconv "HEX" Convert a string of pairs of hexadecimal digits to a string of chars.</p>
</p>
<p><em>strvar:</em> Must be a string of only hex digits 0-9, a-f or A-F.</p>
<p><em>strvar:</em> Must be a string of only hex digits 0-9, a-f or A-F.
<p><em>return:</em> A string if all input was hex digits otherwise "".</p>
</p>
<p>Dynamic array structure is not preserved. Any field marks prevent conversion.</p>
<p><em>Returns:</em> A string if all input was hex digits otherwise "".
<p>This function is the exact inverse of oconv("HEX").</p>
</p>
<p>After prefixing a "0" to an odd sized input, the size of the output is always precisely half that of the input.</p>
<p>Dynamic array structure is not preserved. Any field marks prevent conversion.
</p>
<p>This function is the exact inverse of oconv("HEX").
</p>
<p>After prefixing a "0" to an odd sized input, the size of the output is always precisely half that of the input.
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>varnum.oconv("MX")</td><td><p>Convert number to hexadecimal string.
<tr><td><p><code>var=</code></p></td><td><p><code>varnum.oconv("MX")</code></p></td><td><p>oconv "MX" Convert a number to hexadecimal string.</p>
</p>
<dl>
<p>* "MX"Convert and trim leading zeros                      e.g. oconv(1025, "MX")  -> "401"
<dt>"MX"</dt><dd>Convert and trim leading zeros                      e.g. oconv(1025, "MX")  -&gt; "401"</dd>
</p>
<dt>"MXn"</dt><dd>Pad with up to n leading zeros but do not truncate. e.g. oconv(1025, "MX8") -&gt; "00000401"</dd>
<p>* "MXn"Pad with up to n leading zeros but do not truncate. e.g. oconv(1025, "MX8") -> "00000401"
<dt>"MXnT"</dt><dd>Pad and truncate to n characters.                  e.g. oconv(1025, "MX2") -&gt; "01"</dd>
</p>
</dl>
<p>* "MXnT": Pad and truncate to n characters.                  e.g. oconv(1025, "MX2") -> "01"
<p>"n":    Width. 0-9, A-G = 10 - 16.</p>
</p>
<p><em>varnum:</em> A number or dynamic array of numbers. Floating point numbers are rounded to integers before conversion.</p>
<p>"n":    Width. 0-9, A-G = 10 - 16.
<p><em>return:</em> A string of hexadecimal digits or a dynamic array of the same. Elements that are not numeric are left untouched and unconverted.</p>
</p>
<p>Dynamic array structure is preserved.</p>
<p><em>varnum:</em> A number or dynamic array of numbers. Floating point numbers are rounded to integers before conversion.
<p>Negative numbers are treated as unsigned 8 byte integers (uint64).</p>
</p>
<dl>
<p><em>Returns:</em> A string of hexadecimal digits or a dynamic array of the same. Elements that are not numeric are left untouched and unconverted.
<dt> 0 -&gt;</dt><dd>"00"</dd>
</p>
<dt> 1 -&gt;</dt><dd>"01"</dd>
<p>Dynamic array structure is preserved.
<dt>15 -&gt;</dt><dd>"0F"</dd>
</p>
<dt>-1 -&gt;</dt><dd>"FFFF" "FFFF" "FFFF" "FFFF" (8 x "FF")</dd>
<p>Negative numbers are treated as unsigned 8 byte integers (uint64).
</dl>
</p>
<p>This function is a near inverse of iconv("MX").</p>
<p>* 0 -> "00"
<p>
</p>
<p>* 1 -> "01"
</p>
<p>* 15 -> "0F"
</p>
<p>* -1 -> "FFFF" "FFFF" "FFFF" "FFFF" (8 x "FF")
</p>
This function is a near inverse of iconv("MX").
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;14.5]QQ]65535&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;MX&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;F]QQ]FFFF&quot;_var</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;14.5]QQ]65535&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;MX&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;F]QQ]FFFF&quot;_var</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;14.5]QQ]65535&quot;</span><span class="kt">_var</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;MX&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;14.5]QQ]65535&quot;</span><span class="kt">_var</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;MX&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.iconv("MX")</td><td><p>Convert hexadecimal string to number.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.iconv("MX")</code></p></td><td><p>iconv "MX" Convert a hexadecimal string to number.</p>
</p>
<p><em>strvar:</em> A string or dynamic array of up to 16 hex digits: 0-9, a-f, A-F.</p>
<p><em>strvar:</em> A string or dynamic array of up to 16 hex digits: 0-9, a-f, A-F.
<p><em>return:</em> An integer or dynamic array of integers. Invalid elements are converted to "".</p>
</p>
<p>Dynamic array structure is preserved.</p>
<p><em>Returns:</em> An integer or dynamic array of integers. Invalid elements are converted to "".
<p>Hex strings are converted to unsigned 8 byte integers (uint64)</p>
</p>
<p>Leading zeros are ignored.</p>
<p>Dynamic array structure is preserved.
<dl>
</p>
<dt>"0" -&gt;</dt><dd>0</dd>
<p>Hex strings are converted to unsigned 8 byte integers (uint64)
<dt>"00" -&gt;</dt><dd>0</dd>
</p>
<dt>"1" -&gt;</dt><dd>1</dd>
<p>Leading zeros are ignored.
</dl>
</p>
<p></p>
<p>* "0" -> 0
<p>Hex "FFFF" "FFFF" "FFFF" "FFFF" (8 x "FF") -&gt; -1.</p>
</p>
<p>Hex "7FFF" "FFFF" "FFFF" "FFFF" -&gt; The maximum positive integer: 9223372036854775805.</p>
<p>* "00"-> 0
<p>Hex "8000" "0000" "0000" "0000" -&gt; The maximum negative integer: -9223372036854775808.</p>
</p>
<p>This function is the exact inverse of oconv("MX").</p>
<p>* "1" -> 1
<p>
</p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;F]QQ]FFFF&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">iconv</span><span class="p">(</span><span class="s">&quot;MX&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;15]]65535&quot;_var</span>
<p>* Hex "FFFFFFFFFFFFFFFF" (8 x "FF") -> -1.
</p>
<p>* Hex "7FFFFFFFFFFFFFFF" is the maximum positive integer: 9223372036854775805.
</p>
<p>* Hex "8000000000000000" is the maximum negative integer: -9223372036854775808.
</p>
This function is the exact inverse of oconv("MX").
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;F]QQ]FFFF&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">iconv</span><span class="p">(</span><span class="s">&quot;MX&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;15]]65535&quot;_var</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">iconv</span><span class="p">(</span><span class="s">&quot;F]QQ]FFFF&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;MX&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">iconv</span><span class="p">(</span><span class="s">&quot;F]QQ]FFFF&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;MX&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>varnum.oconv("MB")</td><td><p>Number to binary format: Convert number to strings of 1s and 0s
<tr><td><p><code>var=</code></p></td><td><p><code>varnum.oconv("MB")</code></p></td><td><p>oconv "MB" Convert a number to a binary string of "1"s and "0"s,</p>
</p>
<p><em>varnum:</em> If not numeric then no conversion is performed and the original value is returned.</p>
<em>varnum:</em> If not numeric then no conversion is performed and the original value is returned.
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mi">255</span><span class="p">).</span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;MB&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// 1111&#39;1111</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="mi">255</span><span class="p">).</span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;MB&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// 1111&#39;1111</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">oconv</span><span class="p">(</span><span class="mi">255</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;MB&quot;</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">oconv</span><span class="p">(</span><span class="mi">255</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;MB&quot;</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.oconv("TX")</td><td><p>Convert dynamic arrays to standard text format.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.oconv("TX")</code></p></td><td><p>oconv "TX" Convert a dynamic array to text.</p>
</p>
<p>Convert dynamic arrays to standard text format.</p>
<p>Useful for using text editors on dynamic arrays.
<p>Useful for using text editors on dynamic arrays.</p>
</p>
<dl>
<p>FMs -> \n after escaping any embedded NL
<dt>FMs -&gt;</dt><dd>\n after escaping any embedded NL</dd>
</p>
<dt>VMs -&gt;</dt><dd>literal "\" \n</dd>
<p>VMs -> literal "\" \n
<dt>SMs -&gt;</dt><dd>literal "\\" \n</dd>
</p>
</dl>
<p>SMs -> literal "\\" \n
<p>etc.</p>
</p>
<p>
etc.
<div class="highlight light"><pre><span class="c1">// 1. Backslash in text remains backslash</span>
<div class="highlight light"><pre><span class="c1">// 1. Backslash in text remains backslash</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="kc">_BS</span><span class="p">).</span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;TX&quot;</span><span class="p">);</span><span class="w">    </span><span class="c1">// _BS</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="nb">_BS</span><span class="p">).</span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;TX&quot;</span><span class="p">);</span><span class="w">    </span><span class="c1">// _BS</span>


<span class="c1">// 2. Literal &quot;\n&quot; -&gt; literal &quot;\\n&quot; (Double escape any escaped NL chars)</span>
<span class="c1">// 2. Literal &quot;\n&quot; -&gt; literal &quot;\\n&quot; (Double escape any escaped NL chars)</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="kc">_BS</span><span class="w"> </span><span class="s">&quot;n&quot;</span><span class="p">).</span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;TX&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// _BS _BS &quot;n&quot;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="nb">_BS</span><span class="w"> </span><span class="s">&quot;n&quot;</span><span class="p">).</span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;TX&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// _BS _BS &quot;n&quot;</span>


<span class="c1">// 3. \n becomes literal &quot;\n&quot; (Single escape any NL chars)</span>
<span class="c1">// 3. \n becomes literal &quot;\n&quot; (Single escape any NL chars)</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v3</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="kc">_NL</span><span class="p">).</span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;TX&quot;</span><span class="p">);</span><span class="w">    </span><span class="c1">// _BS &quot;n&quot;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v3</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kt">var</span><span class="p">(</span><span class="nb">_NL</span><span class="p">).</span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;TX&quot;</span><span class="p">);</span><span class="w">    </span><span class="c1">// _BS &quot;n&quot;</span>


<span class="c1">// 4. FM -&gt; \n</span>
<span class="c1">// 4. FM -&gt; \n</span>
Line 3,945: Line 4,095:
<span class="nf">let</span><span class="w"> </span><span class="n">v8</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;st1~st2&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;TX&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;st1&quot; _BS _BS _BS _BS _NL &quot;st2&quot;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v8</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;st1~st2&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;TX&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;st1&quot; _BS _BS _BS _BS _NL &quot;st2&quot;</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>strvar.iconv("TX")</td><td><p>Convert standard text format to dynamic array.
<tr><td><p><code>var=</code></p></td><td><p><code>strvar.iconv("TX")</code></p></td><td><p>iconv "TX" Convert text to a dynamic array.</p>
</p>
<p>Convert standard text format to dynamic array.</p>
<p>Reverse of oconv("TX") above.
<p>Reverse of oconv("TX") above.</p>
</p>
</td></tr>
</td></tr>
</table>
</table>
Line 3,972: Line 4,122:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td></td><td>dim d1;</td><td>Create an undimensioned array of vars pending actual dimensions.
<tr><td><p><code></code></p></td><td><p><code>dim d1;</code></p></td><td><p>Create an undimensioned array of vars.</p>
<p>Pending actual dimensions by redim, read, osread or split.</p>
<p>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="n">d1</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="n">d1</span><span class="p">;</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>dim d1(nrows, ncols = 1);</td><td>Create an array of vars with a fixed number of columns and rows. All vars are unassigned.
<tr><td><p><code></code></p></td><td><p><code>dim d1(nrows, ncols = 1);</code></p></td><td><p>Create a dimensioned array of vars.</p>
<p>Specify a fixed number of columns and rows. All vars are unassigned.</p>
<p>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="nf">d1</span><span class="p">(</span><span class="mi">10</span><span class="p">);</span>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="nf">d1</span><span class="p">(</span><span class="mi">10</span><span class="p">);</span>
<span class="nf">dim</span><span class="w"> </span><span class="nf">d2</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">);</span>
<span class="nf">dim</span><span class="w"> </span><span class="nf">d2</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>dim d1 = d2; // Copy</td><td>Create a copy of an array.
<tr><td><p><code></code></p></td><td><p><code>dim d1 = d2; // Copy</code></p></td><td><p>Copy a dimensioned array.</p>
<p>Unassigned elements are copied as is.</p>
<p>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="n">d1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">4</span><span class="p">,</span><span class="w"> </span><span class="mi">6</span><span class="p">,</span><span class="w"> </span><span class="mi">8</span><span class="p">};</span>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="n">d1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">4</span><span class="p">,</span><span class="w"> </span><span class="mi">6</span><span class="p">,</span><span class="w"> </span><span class="mi">8</span><span class="p">};</span>
<span class="nf">dim</span><span class="w"> </span><span class="n">d2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">d1</span><span class="p">;</span>
<span class="nf">dim</span><span class="w"> </span><span class="n">d2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">d1</span><span class="p">;</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>dim d1 = dim(); // Move</td><td><p>Save an array created elsewhere.
<tr><td><p><code></code></p></td><td><p><code>dim d1 = dim(); // Move</code></p></td><td><p>Save a dimensioned array created elsewhere.</p>
</p>
<p>Use C++ "move" semantics.</p>
Uses C++ "move" semantics.
<p>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="n">d1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;f1^f2^f3&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">split</span><span class="p">();</span>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="n">d1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;f1^f2^f3&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">split</span><span class="p">();</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>dim d1 = {"a", "b", "c" ...}; // Initializer list</td><td>Create an array from a list. All elements must be the same type, var, string, double, int, etc.. but all end up as vars which are a flexible type.
<tr><td><p><code></code></p></td><td><p><code>dim d1 = {"a", "b", "c" ...}; // Initializer list</code></p></td><td><p>Create a dimensioned array from a literal list.</p>
<p>All elements must be the same type, var, string, double, int, etc. All end up as vars which are flexible.</p>
<p>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="n">d1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="mi">4</span><span class="p">,</span><span class="w"> </span><span class="mi">5</span><span class="p">};</span>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="n">d1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="mi">4</span><span class="p">,</span><span class="w"> </span><span class="mi">5</span><span class="p">};</span>
<span class="nf">dim</span><span class="w"> </span><span class="n">d2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="s">&quot;A&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;B&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;C&quot;</span><span class="p">};</span>
<span class="nf">dim</span><span class="w"> </span><span class="n">d2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="s">&quot;A&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;B&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;C&quot;</span><span class="p">};</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>dim d1 = v1;</td><td>Initialise all elements of an array to some single value or constant. A var, "", 0 etc.
<tr><td><p><code></code></p></td><td><p><code>dim d1 = v1;</code></p></td><td><p>Initialise all elements of an dimensioned array.</p>
<p>To some single value. e.g. a var, "", 0 etc.</p>
<p>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="nf">d1</span><span class="p">(</span><span class="mi">10</span><span class="p">);</span>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="nf">d1</span><span class="p">(</span><span class="mi">10</span><span class="p">);</span>
<span class="n">d1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;&quot;</span><span class="p">;</span>
<span class="n">d1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;&quot;</span><span class="p">;</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>dim d1 = sourceint;</td><td>Undocumented</td></tr>
<tr><td><p><code></code></p></td><td><p><code>d1.redim(nrows, ncols = 1)</code></p></td><td><p>Resize a dimensioned array.</p>
<tr><td></td><td>operator=(double sourcedbl)</td><td>Undocumented</td></tr>
<p>To a different number of rows and columns.</p>
<tr><td></td><td>d1.redim(nrows, ncols = 1)</td><td><p>Resize an array to a different number of rows and columns.
<p>Existing data will be retained. Any additional elements are unassigned.</p>
</p>
<p>Resizing rows to 0 clears all data.</p>
<p>Existing data will be retained as far as possible. Any additional elements are unassigned.
<p>Resizing cols to 0 clears all data and changes its status to "undimensioned".</p>
</p>
<p>
<p>Resizing rows to 0 clears all data.
</p>
Resizing cols to 0 clears all data and changes its status to "undimensioned".
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="n">d1</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="n">d1</span><span class="p">;</span>
<span class="n">d1</span><span class="p">.</span><span class="nf">redim</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">);</span>
<span class="n">d1</span><span class="p">.</span><span class="nf">redim</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>d1.swap(d2) </td><td><p>Swap one array with another.
<tr><td><p><code></code></p></td><td><p><code>d1.swap(d2) </code></p></td><td><p>Swap two arrays.</p>
</p>
<p>Either or both may be undimensioned.</p>
Either or both may be undimensioned.
<p>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="nf">d1</span><span class="p">(</span><span class="mi">5</span><span class="p">);</span>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="nf">d1</span><span class="p">(</span><span class="mi">5</span><span class="p">);</span>
<span class="nf">dim</span><span class="w"> </span><span class="nf">d2</span><span class="p">(</span><span class="mi">10</span><span class="p">);</span>
<span class="nf">dim</span><span class="w"> </span><span class="nf">d2</span><span class="p">(</span><span class="mi">10</span><span class="p">);</span>
<span class="n">d1</span><span class="p">.</span><span class="nf">swap</span><span class="p">(</span><span class="n">d2</span><span class="p">);</span>
<span class="n">d1</span><span class="p">.</span><span class="nf">swap</span><span class="p">(</span><span class="n">d2</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
</table>
</table>
Line 4,028: Line 4,193:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td></td><td>var v1 = d1[rowno];</br>d1[rowno] = v1;</td><td>Access and update elements of a one dimensional array using [] brackets
<tr><td><p><code></code></p></td><td><p><code>var v1 = d1[rowno];</br>d1[rowno] = v1;</code></p></td><td><p>[row] Access and update dimensioned array elements.</p>
<p>Two dimensioned arrays can be traversed, columnwise then rowwise, using one dimension array access.</p>
<p>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="n">d1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="mi">4</span><span class="p">,</span><span class="w"> </span><span class="mi">5</span><span class="p">};</span>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="n">d1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="mi">4</span><span class="p">,</span><span class="w"> </span><span class="mi">5</span><span class="p">};</span>
<span class="n">d1</span><span class="p">[</span><span class="mi">3</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">;</span>
<span class="n">d1</span><span class="p">[</span><span class="mi">3</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;X&quot;</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">d1</span><span class="p">[</span><span class="mi">3</span><span class="p">];</span><span class="w"> </span><span class="c1">// &quot;X&quot;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">d1</span><span class="p">[</span><span class="mi">3</span><span class="p">];</span><span class="w"> </span><span class="c1">// &quot;X&quot;</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>var v1 = d1[rowno, colno];</br>d1[rowno, colno] = v1;</td><td>Access and update elements of an two dimensional array using [] brackets
<tr><td><p><code></code></p></td><td><p><code>var v1 = d1[rowno, colno];</br>d1[rowno, colno] = v1;</code></p></td><td><p>[row, col] Access and update dimensioned array elements.</p>
<p>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="nf">d1</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span><span class="w"> </span><span class="mi">5</span><span class="p">);</span>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="nf">d1</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span><span class="w"> </span><span class="mi">5</span><span class="p">);</span>
<span class="n">d1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;&quot;</span><span class="p">;</span>
<span class="n">d1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;&quot;</span><span class="p">;</span>
Line 4,040: Line 4,209:
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">d1</span><span class="p">[</span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="mi">4</span><span class="p">];</span><span class="w"> </span><span class="c1">// &quot;X&quot;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">d1</span><span class="p">[</span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="mi">4</span><span class="p">];</span><span class="w"> </span><span class="c1">// &quot;X&quot;</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>VARREF</td><td>d2(rowno);      d1(rowno) = v2</td><td></td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>d1.rows()</code></p></td><td><p>Get the number of rows in the dimensioned array</p>
<tr><td>VARREF</td><td>d2(rowno, colno);      d1(rowno, colno) = v2</td><td></td></tr>
<p><em>return:</em> A count. Can be zero, indicating an empty or undimensioned array.</p>
<tr><td>var=</td><td>d1.rows()</td><td><p>Get the number of rows in the dimensioned array
<p>
</p>
<em>Returns:</em> A count. Can be zero, indicating an empty array.
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="nf">d1</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span><span class="mi">3</span><span class="p">);</span>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="nf">d1</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span><span class="mi">3</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">d1</span><span class="p">.</span><span class="nf">rows</span><span class="p">();</span><span class="w"> </span><span class="c1">// 5</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">d1</span><span class="p">.</span><span class="nf">rows</span><span class="p">();</span><span class="w"> </span><span class="c1">// 5</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>d1.cols()</td><td><p>Get the number of columns in the dimensioned array
<tr><td><p><code>var=</code></p></td><td><p><code>d1.cols()</code></p></td><td><p>Get the number of columns in the dimensioned array</p>
</p>
<p><em>return:</em> A count.  0 if the array is undimensioned.</p>
<em>Returns:</em> A count.  0 if the array is undimensioned.
<p>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="nf">d1</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span><span class="mi">3</span><span class="p">);</span>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="nf">d1</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span><span class="mi">3</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">d1</span><span class="p">.</span><span class="nf">cols</span><span class="p">();</span><span class="w"> </span><span class="c1">// 3</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">d1</span><span class="p">.</span><span class="nf">cols</span><span class="p">();</span><span class="w"> </span><span class="c1">// 3</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>d1.join(delimiter = FM)</td><td><p>Joins all elements into a single delimited string
<tr><td><p><code>var=</code></p></td><td><p><code>d1.join(delimiter = FM)</code></p></td><td><p>Get a delimited string concatenating all elements of a dimensioned array.</p>
</p>
<p>Unassigned elements on the end are omitted.</p>
<p><em>delimiter:</em> Default is FM.
<p><em>delimiter:</em> Default is FM.</p>
</p>
<p><em>return:</em> A string var.</p>
<em>Returns:</em> A string var.
<p>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="n">d1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="s">&quot;f1&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;f2&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;f3&quot;</span><span class="p">};</span>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="n">d1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="s">&quot;f1&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;f2&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;f3&quot;</span><span class="p">};</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">d1</span><span class="p">.</span><span class="nf">join</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;f1^f2^f3&quot;_var</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">d1</span><span class="p">.</span><span class="nf">join</span><span class="p">();</span><span class="w"> </span><span class="c1">// &quot;f1^f2^f3&quot;_var</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
</table>
</table>
Line 4,071: Line 4,242:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td></td><td>d1.splitter(str1, delimiter = FM)</td><td><p>Creates or updates the array from a given string.
<tr><td><p><code></code></p></td><td><p><code>d1.splitter(str1, delimiter = FM)</code></p></td><td><p>Create or update a dimensioned array using a string with delimiters.</p>
</p>
<p>If the dim array is undimensioned it will be dimensioned with the number of elements that the string has fields.</p>
<p>If the dim array is undimensioned it will be dimensioned with the number of elements that the string has fields.
<p>If the dim array is dimensioned and has more elements than there are fields in the string, the excess array elements are initialised to "". If the record has more fields than there are elements in the array, the excess fields are all left unsplit in the final element of the array.</p>
</p>
<p>Predimensioning arrays allows the efficient reuse of arrays in loops and ensures that all elements are assigned values, useful when reading records from DB files.</p>
<p>If the dim array is dimensioned and has more elements than there are fields in the string, the excess array elements are initialised to "". If the record has more fields than there are elements in the array, the excess fields are all left unsplit in the final element of the array.
<p>Using undimensioned arrays allows the efficient handling of arrays with a very variable number of elements. e.g. OS text files.</p>
</p>
<p>
<p>Predimensioning arrays allows the efficient reuse of arrays in loops and ensures that all elements are assigned values, useful when reading records from db files.
</p>
Using undimensioned arrays allows the efficient handling of arrays with a very variable number of elements. e.g. os text files.
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="n">d1</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="n">d1</span><span class="p">;</span>
<span class="n">d1</span><span class="p">.</span><span class="nf">splitter</span><span class="p">(</span><span class="s">&quot;f1^f2^f3&quot;</span><span class="kt">_var</span><span class="p">);</span><span class="w"> </span><span class="c1">// d1.rows() -&gt; 3  //// Automatically dimensioned.</span>
<span class="n">d1</span><span class="p">.</span><span class="nf">splitter</span><span class="p">(</span><span class="s">&quot;f1^f2^f3&quot;</span><span class="kt">_var</span><span class="p">);</span><span class="w"> </span><span class="c1">// d1.rows() -&gt; 3  //// Automatically dimensioned.</span>
Line 4,086: Line 4,254:
<span class="n">d2</span><span class="p">.</span><span class="nf">splitter</span><span class="p">(</span><span class="s">&quot;f1^f2^f3&quot;</span><span class="kt">_var</span><span class="p">);</span><span class="w"> </span><span class="c1">// d2.rows() -&gt; 10 /// Predimensioned. Excess elements become &quot;&quot;</span>
<span class="n">d2</span><span class="p">.</span><span class="nf">splitter</span><span class="p">(</span><span class="s">&quot;f1^f2^f3&quot;</span><span class="kt">_var</span><span class="p">);</span><span class="w"> </span><span class="c1">// d2.rows() -&gt; 10 /// Predimensioned. Excess elements become &quot;&quot;</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>d1.sorter(reverse = false)</td><td><p>Sort the elements of the array in place.
<tr><td><p><code></code></p></td><td><p><code>d1.sorter(reverse = false)</code></p></td><td><p>Sort a dimensioned array.</p>
</p>
<p>The order of the elements is adjusted so that each element is &lt;= the next.</p>
<em>reverse:</em> Defaults to false. If true, then the order is reversed.
<p><em>reverse:</em> If true, then the order is reversed. The default is false.</p>
<p>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="n">d1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;2,20,10,1&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">split</span><span class="p">(</span><span class="s">&quot;,&quot;</span><span class="p">);</span>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="n">d1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;2,20,10,1&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">split</span><span class="p">(</span><span class="s">&quot;,&quot;</span><span class="p">);</span>
<span class="n">d1</span><span class="p">.</span><span class="nf">sorter</span><span class="p">();</span>
<span class="n">d1</span><span class="p">.</span><span class="nf">sorter</span><span class="p">();</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">d1</span><span class="p">.</span><span class="nf">join</span><span class="p">(</span><span class="s">&quot;,&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;1,2,10,20&quot;_var</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">d1</span><span class="p">.</span><span class="nf">join</span><span class="p">(</span><span class="s">&quot;,&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;1,2,10,20&quot;_var</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>d1.reverser()</td><td>Reverse the elements of the array in place.
<tr><td><p><code></code></p></td><td><p><code>d1.reverser()</code></p></td><td><p>Reverse a dimensioned array.</p>
<p>The order of the elements is reversed.</p>
<p>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="n">d1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;2,20,10,1&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">split</span><span class="p">(</span><span class="s">&quot;,&quot;</span><span class="p">);</span>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="n">d1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;2,20,10,1&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">split</span><span class="p">(</span><span class="s">&quot;,&quot;</span><span class="p">);</span>
<span class="n">d1</span><span class="p">.</span><span class="nf">reverser</span><span class="p">();</span>
<span class="n">d1</span><span class="p">.</span><span class="nf">reverser</span><span class="p">();</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">d1</span><span class="p">.</span><span class="nf">join</span><span class="p">(</span><span class="s">&quot;,&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;1,10,20,2&quot;_var</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">d1</span><span class="p">.</span><span class="nf">join</span><span class="p">(</span><span class="s">&quot;,&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;1,10,20,2&quot;_var</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>d1.shuffler()</td><td>Randomly shuffle the order of the elements of the array in place.
<tr><td><p><code></code></p></td><td><p><code>d1.randomizer()</code></p></td><td><p>Randomise a dimensioned array.</p>
<p>The order of the elements is randomised.</p>
<p>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="n">d1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;2,20,10,1&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">split</span><span class="p">(</span><span class="s">&quot;,&quot;</span><span class="p">);</span>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="n">d1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;2,20,10,1&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">split</span><span class="p">(</span><span class="s">&quot;,&quot;</span><span class="p">);</span>
<span class="n">d1</span><span class="p">.</span><span class="nf">shuffler</span><span class="p">();</span>
<span class="n">d1</span><span class="p">.</span><span class="nf">randomizer</span><span class="p">();</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">d1</span><span class="p">.</span><span class="nf">join</span><span class="p">(</span><span class="s">&quot;,&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// random</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">d1</span><span class="p">.</span><span class="nf">join</span><span class="p">(</span><span class="s">&quot;,&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// random</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
</table>
</table>
Line 4,112: Line 4,289:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>dim=</td><td>d1.sort(reverse = false)</td><td>Same as sorter() but returns a new array leaving the original untouched.</td></tr>
<tr><td><p><code>dim=</code></p></td><td><p><code>d1.sort(reverse = false)</code></p></td><td><p>Get a sorted copy of a dimensioned array.</p>
<tr><td>dim=</td><td>d1.reverse()</td><td>Same as reverser() but returns a new array leaving the original untouched.</td></tr>
</td></tr>
<tr><td>dim=</td><td>d1.shuffle()</td><td>Same as shuffler() but returns a new array leaving the original untouched.</td></tr>
<tr><td><p><code>dim=</code></p></td><td><p><code>d1.reverse()</code></p></td><td><p>Get a reversed copy of a dimensioned array;</p>
</td></tr>
<tr><td><p><code>dim=</code></p></td><td><p><code>d1.randomize()</code></p></td><td><p>Get a randomised copy of a dimensioned array.</p>
</td></tr>
</table>
</table>
<h5 id=Array_DB_I/O>Array DB I/O</h5>
<h5 id=Array_DB_I/O>Array DB I/O</h5>
Line 4,120: Line 4,300:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td></td><td>d1.write(dbfile, key)</td><td><p>Writes a db file record created from an array.
<tr><td><p><code></code></p></td><td><p><code>d1.write(dbfile, key)</code></p></td><td><p>Write a DB file record created from a dimensioned array.</p>
</p>
<p>Each element in the array becomes a separate field in the DB record.</p>
Each element in the array becomes a separate field in the db record. Any redundant trailing FMs are suppressed.
<p>Redundant trailing FMs are omitted.</p>
<p>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="n">d1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Client GD^G^20855^30000^1001.00^20855.76539&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">split</span><span class="p">();</span>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="n">d1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Client GD^G^20855^30000^1001.00^20855.76539&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">split</span><span class="p">();</span>
<span class="nf">let</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;GD001&quot;</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;GD001&quot;</span><span class="p">;</span>
Line 4,130: Line 4,311:
<span class="nf">write</span><span class="p">(</span><span class="n">d1</span><span class="w"> </span><span class="ow">on</span><span class="w"> </span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">);</span>
<span class="nf">write</span><span class="p">(</span><span class="n">d1</span><span class="w"> </span><span class="ow">on</span><span class="w"> </span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">);</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>d1.read(dbfile, key)</td><td><p>Read a db file record into an array.
<tr><td><p><code>if</code></p></td><td><p><code>d1.read(dbfile, key)</code></p></td><td><p>Read a DB file record into a dimensioned array.</p>
</p>
<p>Each field in the database record becomes a single element in the array.</p>
<p>Each field in the database record becomes a single element in the array.
<p><em>return:</em> True if the record exists or false if not,</p>
</p>
<p>If the array is predimensioned then any excess array elements are initialised to "" and any excess record fields are left unsplit in the final array element. See dim splitter for more info.</p>
<p><em>Returns:</em> True if the record exists or false if not,
<p>If the array is not predimensioned (rows and cols = 0) then it will be dimensioned to have exactly the same number of rows as there are fields in the record being read.</p>
</p>
<p>
<p>If the array is predimensioned then any excess array elements are initialised to "" and any excess record fields are left unsplit in the final array element. See dim splitter for more info.
</p>
If the array is not predimensioned (rows and cols = 0) then it will be dimensioned to have exactly the same number of rows as there are fields in the record being read.
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="nf">d1</span><span class="p">(</span><span class="mi">10</span><span class="p">);</span>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="nf">d1</span><span class="p">(</span><span class="mi">10</span><span class="p">);</span>
<span class="nf">let</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;GD001&quot;</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;GD001&quot;</span><span class="p">;</span>
Line 4,146: Line 4,325:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">read</span><span class="p">(</span><span class="n">d1</span><span class="w"> </span><span class="ow">from</span><span class="w"> </span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">read</span><span class="p">(</span><span class="n">d1</span><span class="w"> </span><span class="ow">from</span><span class="w"> </span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
</table>
</table>
Line 4,152: Line 4,332:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>if</td><td>d1.oswrite(osfilename, codepage = "")</td><td><p>Creates an entire os text file from an array
<tr><td><p><code>if</code></p></td><td><p><code>d1.oswrite(osfilename, codepage = "")</code></p></td><td><p>Create an entire OS text file from a dimensioned array</p>
</p>
<p>Each element of the array becomes one line in the OS file delimited by \n</p>
<p>Each element of the array becomes one line in the os file delimited by \n
<p>Any existing OS file is overwritten and replaced.</p>
</p>
<p><em>codepage:</em> Optional: Data is converted from UTF8 to the required codepage/encoding before output. If the conversion cannot be performed then return false.</p>
<p>Any existing os file is overwritten and replaced.
<p><em>return:</em> True if successful or false if not.</p>
</p>
<p>
<p><em>codepage:</em> Optional: Data is converted from UTF8 to the required codepage/encoding before output. If the conversion cannot be performed then return false.
</p>
<em>Returns:</em> True if successful or false if not.
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="n">d1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aaa=1</span><span class="se">\n</span><span class="s">bbb=2</span><span class="se">\n</span><span class="s">ccc=3</span><span class="se">\n</span><span class="s">&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">split</span><span class="p">(</span><span class="s">&quot;</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">);</span>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="n">d1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;aaa=1</span><span class="se">\n</span><span class="s">bbb=2</span><span class="se">\n</span><span class="s">ccc=3</span><span class="se">\n</span><span class="s">&quot;</span><span class="kt">_var</span><span class="p">.</span><span class="nf">split</span><span class="p">(</span><span class="s">&quot;</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">);</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">osremove</span><span class="p">(</span><span class="s">&quot;xo_conf.txt&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">{};</span><span class="w"> </span><span class="c1">// Cleanup first</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">osremove</span><span class="p">(</span><span class="s">&quot;xo_conf.txt&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">{};</span><span class="w"> </span><span class="c1">// Cleanup first</span>
Line 4,168: Line 4,345:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">oswrite</span><span class="p">(</span><span class="n">d1</span><span class="w"> </span><span class="ow">on</span><span class="w"> </span><span class="n">osfilename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">oswrite</span><span class="p">(</span><span class="n">d1</span><span class="w"> </span><span class="ow">on</span><span class="w"> </span><span class="n">osfilename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>d1.osread(osfilename, codepage = "")</td><td><p>Read an entire os text file into an array.
<tr><td><p><code>if</code></p></td><td><p><code>d1.osread(osfilename, codepage = "")</code></p></td><td><p>Read an entire OS text file into a dimensioned array.</p>
</p>
<p>Each line in the OS file, delimited by \n or \r\n, becomes a separate element in the array.</p>
<p>Each line in the os file, delimited by \n or \r\n, becomes a separate element in the array.
<p>Existing data in the array is lost and the array is redimensioned to the number of lines in the input data.</p>
</p>
<p><em>codepage:</em> Optional. Data will be converted from the specified codepage/encoding to UTF8 after being read. If the conversion cannot be performed then return false.</p>
<p>Existing data in the array is lost and the array is redimensioned to the number of lines in the input data.
<p><em>return:</em> True if successful or false if not.</p>
</p>
<p>If the first \n in the file is \r\n then the whole file will be split using \r\n as delimiter.</p>
<p><em>codepage:</em> Optional. Data will be converted from the specified codepage/encoding to UTF8 after being read. If the conversion cannot be performed then return false.
<p>
</p>
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="n">d1</span><span class="p">;</span>
<p><em>Returns:</em> True if successful or false if not.
<span class="nf">let</span><span class="w"> </span><span class="n">osfilename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_conf.txt&quot;</span><span class="p">;</span>
</p>
If the first \n in the file is \r\n then the whole file will be split using \r\n as delimiter.
<div class="highlight light"><pre><span class="nf">dim</span><span class="w"> </span><span class="n">d1</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">osfilename</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_conf.txt&quot;</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="n">d1</span><span class="p">.</span><span class="nf">osread</span><span class="p">(</span><span class="n">osfilename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="c1">// d1.join(&quot;\n&quot;) -&gt; &quot;aaa=1\nbbb=2\nccc=3\n&quot;_var0</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="n">d1</span><span class="p">.</span><span class="nf">osread</span><span class="p">(</span><span class="n">osfilename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="c1">// d1.join(&quot;\n&quot;) -&gt; &quot;aaa=1\nbbb=2\nccc=3\n&quot;_var0</span>
<span class="c1">// or</span>
<span class="c1">// or</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">osread</span><span class="p">(</span><span class="n">d1</span><span class="w"> </span><span class="ow">from</span><span class="w"> </span><span class="n">osfilename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">osread</span><span class="p">(</span><span class="n">d1</span><span class="w"> </span><span class="ow">from</span><span class="w"> </span><span class="n">osfilename</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
</table>
</table>
Line 4,212: Line 4,387:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>if</td><td>select(sortselectclause_or_filehandle = "")</td><td><p>Create an active select list using a natural language sort/select command.
<tr><td><p><code>if</code></p></td><td><p><code>select(sortselectclause_or_filehandle = "")</code></p></td><td><p>Create an active select list using a natural language sort/select command.</p>
</p>
<p>This and all the following exoprog member functions work on an environment variable CURSOR.</p>
<p>This and all the following exoprog member functions work on an environment variable CURSOR.
<p>Identical functions are available directly on plain var objects but vars have less functionality regarding dictionaries and environment variables which are built-in to exoprog.</p>
</p>
<p><em>return:</em> True if an active select list was created, false otherwise.</p>
<p>Identical functions are available directly on plain var objects but vars have less functionality regarding dictionaries and environment variables which are built-in to exoprog.
<p>In the following examples, various environment variables like RECORD, ID and MV are used instead of declaring and using named vars. In actual code, either may be freely used.</p>
</p>
<p>
<p><em>Returns:</em> True if an active select list was created, false otherwise.
</p>
In the following examples, various environment variables like RECORD, ID and MV are used instead of declaring and using named vars. In actual code, either may be freely used.
<div class="highlight light"><pre><span class="nf">select</span><span class="p">(</span><span class="s">&quot;xo_clients by name by type with type &#39;A&#39; &#39;B&#39; and with balance between 0 and 2000&quot;</span><span class="p">);</span>
<div class="highlight light"><pre><span class="nf">select</span><span class="p">(</span><span class="s">&quot;xo_clients by name by type with type &#39;A&#39; &#39;B&#39; and with balance between 0 and 2000&quot;</span><span class="p">);</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">readnext</span><span class="p">(</span><span class="n">ID</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">readnext</span><span class="p">(</span><span class="kc">ID</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>selectkeys(keys)</td><td>Create an active select list from some given keys.
<tr><td><p><code>if</code></p></td><td><p><code>selectkeys(keys)</code></p></td><td><p>Create an active select list from a dynamic array of keys.</p>
<p>
<div class="highlight light"><pre><span class="nf">selectkeys</span><span class="p">(</span><span class="s">&quot;SB001^JB001^JB002&quot;</span><span class="kt">_var</span><span class="p">);</span>
<div class="highlight light"><pre><span class="nf">selectkeys</span><span class="p">(</span><span class="s">&quot;SB001^JB001^JB002&quot;</span><span class="kt">_var</span><span class="p">);</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">readnext</span><span class="p">(</span><span class="n">ID</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">// ID -&gt; &quot;SB001&quot;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">readnext</span><span class="p">(</span><span class="kc">ID</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">// ID -&gt; &quot;SB001&quot;</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>hasnext()</td><td>Check if a select list is active.
<tr><td><p><code>if</code></p></td><td><p><code>hasnext()</code></p></td><td><p>Check if a select list is active.</p>
<p>
<div class="highlight light"><pre><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">hasnext</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
<div class="highlight light"><pre><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">hasnext</span><span class="p">())</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>readnext(out key)</td><td><p>Get the next key from an active select list.
<tr><td><p><code>if</code></p></td><td><p><code>readnext(out key)</code></p></td><td><p>Get the next key from an active select list.</p>
</p>
<p><em>key[out]:</em> A string. Typically the key of a db file record.</p>
<p><em>key:</em> [out] A string. Typically the key of a db file record.
<p><em>return:</em> True if an active select list was available and the next key in the list was obtained.</p>
</p>
<p>
<em>Returns:</em> True if an active select list was available and the next key in the list was obtained.
<div class="highlight light"><pre><span class="nf">selectkeys</span><span class="p">(</span><span class="s">&quot;SB001^JB001^JB002&quot;</span><span class="kt">_var</span><span class="p">);</span>
<div class="highlight light"><pre><span class="nf">selectkeys</span><span class="p">(</span><span class="s">&quot;SB001^JB001^JB002&quot;</span><span class="kt">_var</span><span class="p">);</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">readnext</span><span class="p">(</span><span class="n">ID</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">// ID -&gt; &quot;SB001&quot;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">readnext</span><span class="p">(</span><span class="kc">ID</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">// ID -&gt; &quot;SB001&quot;</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>readnext(out key, out valueno)</td><td><p>Get the next key and value number pair from an active select list.
<tr><td><p><code>if</code></p></td><td><p><code>readnext(out key, out valueno)</code></p></td><td><p>Get the next key and value number pair from an active select list.</p>
</p>
<p><em>key[out]:</em> A string. Typically the key of a db file record.</p>
<p><em>key:</em> [out] A string. Typically the key of a db file record.
<p><em>valueno[out]:</em> Is only available in select lists that have been created by sort/select commands that refer to multi-valued db dictionary fields where db records have multiple values for a specific field. In this case, a record key will appear multiple times in the select list since each multivalue is exploded for the purpose of sorting and selecting. This can be viewed as a process of "normalising" multivalues so they appear as multiple records instead of being held in a single record.</p>
</p>
<p><em>return:</em> True if an active select list was available and the next key in the list was obtained.</p>
<p><em>valueno:</em> [out] Is only available in select lists that have been created by sort/select commands that refer to multi-valued db dictionary fields where db records have multiple values for a specific field. In this case, a record key will appear multiple times in the select list since each multivalue is exploded for the purpose of sorting and selecting. This can be viewed as a process of "normalising" multivalues so they appear as multiple records instead of being held in a single record.
<p>
</p>
<em>Returns:</em> True if an active select list was available and the next key in the list was obtained.
<div class="highlight light"><pre><span class="nf">selectkeys</span><span class="p">(</span><span class="s">&quot;SB001]2^SB001]1^JB001]2&quot;</span><span class="kt">_var</span><span class="p">);</span>
<div class="highlight light"><pre><span class="nf">selectkeys</span><span class="p">(</span><span class="s">&quot;SB001]2^SB001]1^JB001]2&quot;</span><span class="kt">_var</span><span class="p">);</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">readnext</span><span class="p">(</span><span class="n">ID</span><span class="p">,</span><span class="w"> </span><span class="n">MV</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">// ID -&gt; &quot;SB001&quot; // MV -&gt; 2</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">readnext</span><span class="p">(</span><span class="kc">ID</span><span class="p">,</span><span class="w"> </span><span class="kc">MV</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="w"> </span><span class="c1">// ID -&gt; &quot;SB001&quot; // MV -&gt; 2</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>readnext(out record, out key, out valueno)</td><td><p>Get the next record, key and value no from an active select list.
<tr><td><p><code>if</code></p></td><td><p><code>readnext(out record, out key, out valueno)</code></p></td><td><p>Get the next record, key and value no from an active select list.</p>
</p>
<p><em>record[out]:</em> Is only available in select lists that have been created with the final (R) option. Otherwise the record will be returned as an empty string and must be obtained using a db read() function.</p>
<p><em>record:</em> [out] Is only available in select lists that have been created with the final (R) option. Otherwise the record will be returned as an empty string and must be obtained using a db read() function.
<p><em>key[out]:</em> A string. Typically the key of a db file record.</p>
</p>
<p><em>valueno[out]:</em> Is only available in select lists that have been created by sort/select commands that refer to multi-valued db dictionary fields where db records have multiple values for a specific field.</p>
<p><em>key:</em> [out] A string. Typically the key of a db file record.
<p><em>return:</em> True if an active select list was available and the next key in the list was obtained.</p>
</p>
<p>
<p><em>valueno:</em> [out] Is only available in select lists that have been created by sort/select commands that refer to multi-valued db dictionary fields where db records have multiple values for a specific field.
</p>
<em>Returns:</em> True if an active select list was available and the next key in the list was obtained.
<div class="highlight light"><pre><span class="nf">select</span><span class="p">(</span><span class="s">&quot;xo_clients by name (R)&quot;</span><span class="p">);</span>
<div class="highlight light"><pre><span class="nf">select</span><span class="p">(</span><span class="s">&quot;xo_clients by name (R)&quot;</span><span class="p">);</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">readnext</span><span class="p">(</span><span class="n">RECORD</span><span class="p">,</span><span class="w"> </span><span class="n">ID</span><span class="p">,</span><span class="w"> </span><span class="n">MV</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">readnext</span><span class="p">(</span><span class="kc">RECORD</span><span class="p">,</span><span class="w"> </span><span class="kc">ID</span><span class="p">,</span><span class="w"> </span><span class="kc">MV</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">ok</span><span class="p">;</span>
<span class="n">assert</span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="n">RECORD</span><span class="p">.</span><span class="nf">empty</span><span class="p">());</span>
<span class="n">assert</span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="kc">RECORD</span><span class="p">.</span><span class="nf">empty</span><span class="p">());</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>pushselect(out cursor)</td><td><p>Saves a pointer to the currently active select list.
<tr><td><p><code></code></p></td><td><p><code>pushselect(out cursor)</code></p></td><td><p>Get a reference to the currently active select list and suspend it.</p>
</p>
<p>Allow another select list to be activated and used temporarily before the original select list is reactivated.</p>
<p>This allows another select list to be activated and used temporarily before the original select list is reactivated.
<p>Multiple levels of pushselect/popselect can be used.</p>
</p>
<p><em>cursor[out]:</em> A var that can be passed later on to the popselect() function to reactivate the saved list.</p>
<em>cursor:</em> [out] A var that can be passed later on to the popselect() function to reactivate the saved list.
<p>
<div class="highlight light"><pre><span class="nf">select</span><span class="p">(</span><span class="s">&quot;xo_clients by name&quot;</span><span class="p">);</span>
<div class="highlight light"><pre><span class="nf">select</span><span class="p">(</span><span class="s">&quot;xo_clients by name&quot;</span><span class="p">);</span>
<span class="kt">var</span><span class="w"> </span><span class="n">saved_xo_clients_cursor</span><span class="p">;</span>
<span class="kt">var</span><span class="w"> </span><span class="n">saved_xo_clients_cursor</span><span class="p">;</span>
Line 4,281: Line 4,455:
<span class="nf">popselect</span><span class="p">(</span><span class="n">saved_xo_clients_cursor</span><span class="p">);</span><span class="w"> </span><span class="c1">// Reactivate the original select list.</span>
<span class="nf">popselect</span><span class="p">(</span><span class="n">saved_xo_clients_cursor</span><span class="p">);</span><span class="w"> </span><span class="c1">// Reactivate the original select list.</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>popselect(cursor)</td><td><p>Re-establish an active select list saved by pushselect().
<tr><td><p><code></code></p></td><td><p><code>popselect(cursor)</code></p></td><td><p>Re-activate a select list using a reference provided by pushselect().</p>
</p>
<p><em>cursor:</em> A var created by the pushselect() function.</p>
<p><em>cursor:</em> A var created by the pushselect() function.
<p>See pushselect() for more info.</p>
</p>
</td></tr>
See pushselect() for more info.</td></tr>
<tr><td><p><code></code></p></td><td><p><code>clearselect()</code></p></td><td><p>Deactivate an active select list.</p>
<tr><td></td><td>clearselect()</td><td><p>Deactivate an active select list.
<p>If no select list is active then nothing is done.</p>
</p>
<p>
If no select list is active then nothing is done.
<div class="highlight light"><pre><span class="nf">clearselect</span><span class="p">();</span>
<div class="highlight light"><pre><span class="nf">clearselect</span><span class="p">();</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>deleterecord(filename)</td><td><p>Use an active select list to delete db records.
<tr><td><p><code>if</code></p></td><td><p><code>deleterecord(filename)</code></p></td><td><p>Delete multiple DB records using an active select list.</p>
</p>
<p><em>return:</em> False if any records could not be deleted.</p>
<p><em>Returns:</em> False if any records could not be deleted.
<p>Contrast this function with the two argument "deleterecord(file, key)" function that deletes a single record.</p>
</p>
<p>
Contrast this function with the two argument "deleterecord(file, key)" function that deletes a single record.
<div class="highlight light"><pre><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">select</span><span class="p">(</span><span class="s">&quot;xo_clients with type &#39;Q&#39; and with balance between 0 and 100&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">{</span>
<div class="highlight light"><pre><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">select</span><span class="p">(</span><span class="s">&quot;xo_clients with type &#39;Q&#39; and with balance between 0 and 100&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">{</span>
<span class="w">  </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">deleterecord</span><span class="p">(</span><span class="s">&quot;xo_clients&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="w">  </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">deleterecord</span><span class="p">(</span><span class="s">&quot;xo_clients&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>deleterecord(dbfile, key)</td><td>Delete a single database file record.
<tr><td><p><code>if</code></p></td><td><p><code>deleterecord(dbfile, key)</code></p></td><td><p>Delete a single DB record.</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;QQ001&quot;</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;xo_clients&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;QQ001&quot;</span><span class="p">;</span>
<span class="nf">write</span><span class="p">(</span><span class="s">&quot;&quot;</span><span class="w"> </span><span class="ow">on</span><span class="w"> </span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">);</span>
<span class="nf">write</span><span class="p">(</span><span class="s">&quot;&quot;</span><span class="w"> </span><span class="ow">on</span><span class="w"> </span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="n">key</span><span class="p">);</span>
Line 4,311: Line 4,487:
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="n">file</span><span class="p">.</span><span class="nf">deleterecord</span><span class="p">(</span><span class="n">key</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="n">file</span><span class="p">.</span><span class="nf">deleterecord</span><span class="p">(</span><span class="n">key</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>savelist(listname)</td><td><p>Save a currently active select list under a given name.
<tr><td><p><code>if</code></p></td><td><p><code>savelist(listname)</code></p></td><td><p>Save the current active select list under a given name.</p>
</p>
<p>Select lists are saved in the DB file "lists". They are accessible to any Exodus process and remain until specifically deleted.</p>
<p>After saving, the list is no longer active and hasnext() will return false.
<p>After saving, the list is no longer active and hasnext() will return false.</p>
</p>
<p><em>return:</em> True if an active select list was saved, false if there was no active select list.</p>
<p><em>Returns:</em> True if an active select list was saved, false if there was no active select list.
<p>
</p>
Lists are saved as a record in the "lists" file.
<div class="highlight light"><pre><span class="nf">selectkeys</span><span class="p">(</span><span class="s">&quot;SB001^SB002&quot;</span><span class="kt">_var</span><span class="p">);</span>
<div class="highlight light"><pre><span class="nf">selectkeys</span><span class="p">(</span><span class="s">&quot;SB001^SB002&quot;</span><span class="kt">_var</span><span class="p">);</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">savelist</span><span class="p">(</span><span class="s">&quot;my_list&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">savelist</span><span class="p">(</span><span class="s">&quot;my_list&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>getlist(listname)</td><td><p>Reactivate a saved select list of a given name.
<tr><td><p><code>if</code></p></td><td><p><code>getlist(listname)</code></p></td><td><p>Create an active select list using a saved select list of a given name.</p>
</p>
<p>A saved list is obtained from the "lists" file and activated. The list remains in the lists file for multiple use.</p>
<p>A saved list is obtained from the "lists" file and activated.
<p><em>return:</em> True if an active select list was successfully reactivated, otherwise false.</p>
</p>
<p>
<em>Returns:</em> True if an active select list was successfully reactivated, otherwise false.
<div class="highlight light"><pre><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">getlist</span><span class="p">(</span><span class="s">&quot;my_list&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<div class="highlight light"><pre><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">getlist</span><span class="p">(</span><span class="s">&quot;my_list&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>if</td><td>deletelist(listname)</td><td><p>Remove a saved select list by name.
<tr><td><p><code>if</code></p></td><td><p><code>deletelist(listname)</code></p></td><td><p>Remove a saved select list by name.</p>
</p>
<p>A saved list is deleted from the "lists" file.</p>
A saved list is deleted from the "lists" file.
<p>
<div class="highlight light"><pre><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">deletelist</span><span class="p">(</span><span class="s">&quot;my_list&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
<div class="highlight light"><pre><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="ow">not</span><span class="w"> </span><span class="nf">deletelist</span><span class="p">(</span><span class="s">&quot;my_list&quot;</span><span class="p">))</span><span class="w"> </span><span class="p">...</span>
</pre></div>
</pre></div>
</p>
</td></tr>
<tr><td><p><code>if</code></p></td><td><p><code>formlist(filename_or_command, keys = "", fieldno = 0)</code></p></td><td>
</td></tr>
<tr><td><p><code>if</code></p></td><td><p><code>makelist(listname, keys)</code></p></td><td>
</td></tr>
</td></tr>
<tr><td>if</td><td>formlist(filename_or_command, keys = "", fieldno = 0)</td><td></td></tr>
<tr><td>if</td><td>makelist(listname, keys)</td><td></td></tr>
</table>
</table>
<h5 id=Perform/Execute>Perform/Execute</h5>
<h5 id=Perform/Execute>Perform/Execute</h5>
Line 4,344: Line 4,523:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>var=</td><td>perform(command_line)</td><td><p>Run an exodus program/library's main function using a command like syntax similar to that of os executable programs.
<tr><td><p><code>var=</code></p></td><td><p><code>perform(command_line)</code></p></td><td><p>Run an Exodus program/library.</p>
</p>
<p>Creates a new instance of an Exodus program library function object and calls its main() function using a command-like syntax, similar to that of running an OS executable program, and passes its arguments through the COMMAND and OPTIONS variables.</p>
<p><em>command_line:</em> Used to initialise the COMMAND, SENTENCE and OPTIONS environment variables of the performed exodus program/library. Analogous to passing function arguments. The first word of command_line is used as the name of the program/library to be loaded and run.
<p>A performed program/library's main function should have no arguments otherwise they appear unassigned and a segfault or core dump may occur.</p>
</p>
<p>The Exodus program class member variables of a performed or executed program/library are all, as might be expected, initially unassigned unless specifically initialised inline. Note that this is not the same as calling a program library function (using function call syntax and round brackets funcx()), where the program/library/function's member variables are initially unassigned but retain their state between calls.</p>
<p>The program/library's main function should have zero arguments. Performing a program/library function with main arguments results in them being unassigned and in some case core dump may occur.
<p><em>command_line:</em> Used to initialise the COMMAND, SENTENCE and OPTIONS environment variables of the performed exodus program/library. Analogous to passing function arguments. The first word of command_line is used as the name of the program/library to be loaded and run.</p>
</p>
<p><em>return:</em> Whatever the program returns from main() or passes as an argument to stop(). If the program terminates abnormally then it will return "" and lasterror() will contain some error message. The return value may be ignored so there is no need so wrap perform statements in if clauses to avoid compiler warnings.</p>
<p><em>Returns:</em> Whatever var the program/library returns, or "" if it calls stop() or abort((). The return value can be ignored and discarded without any compiler warning.
<p><em>throw:</em> All the various runtime errors based on VarError e.g. VarUnassigned.</p>
</p>
<p><em>environment:</em> The following environment variables are initialised on entry to the main function of the program/library and are preserved untouched (actually restored) in the calling program.</p>
<p>The following environment variables are initialised on entry to the main function of the program/library and are preserved untouched in the calling program.
<ul>
</p>
<li>COMMAND, OPTIONS, SENTENCE.</li>
<p>RECUR0, RECUR1, RECUR2, RECUR3, RECUR4 to "".
<li>RECUR0, RECUR1, RECUR2, RECUR3, RECUR4 to "".</li>
</p>
<li>ID, RECORD, MV, DICT initialised to "".</li>
<p>ID, RECORD, MV, DICT initialised to "".
<li>LEVEL is incremented by one.</li>
</p>
<li>All other environment variables are shared between the caller and callee. There is essentially only one environment in any one process or thread.</li>
<p>LEVEL is incremented by one.
<li>CURSOR Any active select list in CURSOR is passed to the performed program/library and can be consumed by it. Conversely any active select list created by the performed program/library will be returned to the calling program. In other words, both the performing and the performed programs/libraries share a single active select list environment. This is different from execute() where the executed program/library gets its own private active select list, initially inactive.</li>
</p>
</ul>
<p>All other environment variables are shared between the caller and callee. There is essentially only one environment in any one process or thread.
<p>Exodus program/library/functions may also be called directly using conventional function calling syntax. To call an exodus program/library called progname using either the syntax "call progname(args...);" or "var v1 = progname(args...);" you must "#include &lt;progname.h&gt;" after the "programinit()" or "libraryinit()" lines in your program/library. See library.h for more info.</p>
</p>
</td></tr>
<p>Any active select list in CURSOR is passed to the performed program/library and can be consumed by it. Conversely any active select list created by the performed program/library will be returned to the calling program. In other words, both the performing and the performed programs/libraries share a single active select list environment. This is different from execute() which gets its own private active select list, initially inactive.
<tr><td><p><code>var=</code></p></td><td><p><code>execute(command_line)</code></p></td><td><p>Run an exodus program/library.</p>
</p>
<p>Identical to perform() but any currently active select list in the calling program/library is not accessible to the executed program/library and is preserved in the calling [program as is. Any select list created by the executed library is discarded when it terminates.</p>
Exodus program/libraries may also be called directly using conventional function calling syntax. To call an exodus program/library called progname using either the syntax "call progname(args...);" or "var v1 = progname(args...);" you must "#include <progname.h>" after the "programinit()" or "libraryinit()" lines in your program/library.</td></tr>
</td></tr>
<tr><td>var=</td><td>execute(command_line)</td><td><p>Run an exodus program/library's main function.
<tr><td><p><code></code></p></td><td><p><code>chain(command_line)</code></p></td><td><p>Close the current program and perform another one.</p>
</p>
<p>Similar to perform() except that the current program closes first and all environment variables carry forward unchanged.</p>
Identical to perform() but any currently active select list in the calling program/library is not accessible to the executed program/library and is preserved in the calling [program as is. Any select list created by the executed library is discarded when it terminates.</td></tr>
</td></tr>
<tr><td></td><td>chain(command_line)</td><td><p>Close the current program and perform another one.
<tr><td><p><code>var=</code></p></td><td><p><code>libinfo(libname)</code></p></td><td><p>Check if a lib exists.</p>
</p>
<p>Can be checked before perform/execute to avoid errors.</p>
Identical to perform() except that the current program closes first.</td></tr>
<p>Currently it does not check if the library is actually loadable.</p>
<tr><td>var=</td><td>libinfo(libname)</td><td>Check if a lib exists to be performed/executed or called. Currently it does not check if it is actually loadable.</td></tr>
<p><em>return:</em> osfile info.</p>
</td></tr>
</table>
</table>
<h5 id=Program_Termination_>Program Termination </h5>
<h5 id=Program_Termination_>Program Termination </h5>
Line 4,377: Line 4,557:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td></td><td>stop(message = "")</td><td><p>Stop the current exodus program/library normally.
<tr><td><p><code></code></p></td><td><p><code>stop(result = "")</code></p></td><td><p>Stop the current exodus program/library normally.</p>
</p>
<p>Either return to the performing or executing parent exodus program/library, or exit to the OS if none.</p>
<p>Either return to the performing or executing parent exodus program/library, or exit to the OS if none.
<p><em>result:</em> Optional. It will be used as the return value of a parent program's perform() or execute() function, or if none, and therefore returning to the OS, it will be output to stdout if non-numeric or, if numeric, used as the exit status.</p>
</p>
</td></tr>
<em>message:</em> Optional. If exiting to the OS then it will be output to stdout or, if numeric, used as the exit status.</td></tr>
<tr><td><p><code></code></p></td><td><p><code>abort(message = "")</code></p></td><td><p>Abort the current exodus program/library.</p>
<tr><td></td><td>abort(message = "")</td><td><p>Abort the current exodus program/library.
<p>Similar to stop but if exiting to the OS then the default exit status is 1.</p>
</p>
<p><em>message:</em> Optional. If exiting to the OS then it will be output to stderr or, if numeric, used as the exit status.</p>
<p>Similar to stop but if exiting to the OS then the default exit status is 1.
</td></tr>
</p>
<tr><td><p><code></code></p></td><td><p><code>abortall(message = "")</code></p></td><td><p>Abort the current exodus program/library.</p>
<em>message:</em> Optional. If exiting to the OS then it will be output to stderr or, if numeric, used as the exit status.</td></tr>
<p>Similar to abort but if exiting to the OS then the default exit status is 2.</p>
<tr><td></td><td>abortall(message = "")</td><td><p>Abort the current exodus program/library.
</td></tr>
</p>
Similar to abort but if exiting to the OS then the default exit status is 2.</td></tr>
</table>
</table>
<h5 id=DB_File_Dictionaries>DB File Dictionaries</h5>
<h5 id=DB_File_Dictionaries>DB File Dictionaries</h5>
Line 4,395: Line 4,573:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>var=</td><td>calculate(dictid)</td><td>Given a dictid reads a dictrec from the current DICT file (using readc()) and then either extracts a specific field number from the current RECORD/ID/MV environment variables or calls a dict function library to calculate the result.</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>calculate(dictid)</code></p></td><td><p>Get DB record field values given field name only.</p>
<tr><td>var=</td><td>calculate(dictid, dictfile, id, record, mv = 0)</td><td>Given dictid, dictfile, record, id and mv, reads a dictrec from dictfile (using readc()) and then either extracts a specific field number from the given record/id/mv or calls a dict function library to calculate the result.</td></tr>
<p>Use a dictionary file that contains info sufficient to either extract or calculate the required value.</p>
<tr><td>var=</td><td>xlate(filename, key, fieldno_or_name, mode)</td><td><p>Reads a record from the specified file and key (using readc()) and then either extracts a specific field number or calls calculate(dictid...) to obtain the result.
<ol>
</p>
<li>Read fieldinfo from the current DICT file using readc() for caching.</li>
<p><em>filename:</em> Which file to read.
<li>Use the fieldinfo to:<ul>
</p>
  <li>Either extract a specific field number from the current RECORD/ID/MV environment variables.</li>
<p><em>key:</em> The key of the record to read.
  <li>Or call a dictionary function library to calculate the result.</li>
</p>
</ul>
<p><em>fieldno_or_name:</em>
</li>
</p>
</ol>
<p>* If numeric then a specific field number will be extracted.
</td></tr>
</p>
<tr><td><p><code>var=</code></p></td><td><p><code>calculate(dictid, dictfile, id, record, mv = 0)</code></p></td><td><p>Get DB record field values given name and data.</p>
<p>* If "0" then the key will be returned.
<p>Same as the one argument version of calculate() but RECORD/ID/MV are provided as arguments instead of being hard coded.</p>
</p>
</td></tr>
<p>* If "" then the whole record will be returned.
<tr><td><p><code>var=</code></p></td><td><p><code>xlate(filename, key, fieldno_or_name, mode)</code></p></td><td><p>Read DB field using field number or name.</p>
</p>
<ol>
<p>* dictid: calculate(dictid) will be called.
<li>Read a record from a given file and key using readc() for caching.</li>
</p>
<li>Extracts the given field number or calls calculate(dictid...) if non-numeric.</li>
<p><em>mode:</em> Determines what to do if the record does not exist.
</ol>
</p>
<p><em>filename:</em> The file to read.</p>
<p>* "X" Return ""
<p><em>key:</em> The key of the record to read.</p>
</p>
<p></p>
<p>* "C" Return the key.
<p><em>fieldno_or_name:</em> The field  to return.</p>
</p>
<dl>
<em>MV:</em> Environment variable. Will be used to select a particular value or all if zero.</td></tr>
<dt>nn</dt><dd>Field number nn.</dd>
<dt>0</dt><dd>The record key (ID).</dd>
<dt>""</dt><dd>The whole record (RECORD)</dd>
<dt>dictid</dt><dd>The function calculate(dictid) will be called.</dd>
</dl>
<p></p>
<p><em>mode:</em> If the record does not exist.</p>
<dl>
<dt>"X"</dt><dd>Return ""</dd>
<dt>"C"</dt><dd>Return the key.</dd>
</dl>
<p></p>
<p><em>MV:</em> Environment variable. Will be used to select a particular value if not zero, or all values if zero.</p>
</td></tr>
</table>
</table>
<h5 id=I/O_Conversion>I/O Conversion</h5>
<h5 id=I/O_Conversion>I/O Conversion</h5>
Line 4,425: Line 4,616:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>var=</td><td>oconv(input, conversion)</td><td><p>iconv/oconv with access to exoprogram's environment variables.
<tr><td><p><code>var=</code></p></td><td><p><code>oconv(input, conversion)</code></p></td><td><p>iconv/oconv "[...]"</p>
</p>
<p>ExoProgram's iconv/oconv functions have access to ExoProgram's environment variables like BASEFMT, DATEFMT and TZ and have the ability to call custom functions like "[funname,args...]"</p>
<p>exoprog's iconv/oconv have the ability to call custom functions like "[funname,args...]"
<p></p>
</p>
<p>[NUMBER]  // built-in. See doc below.</p>
 
<p>[DATE]    // built-in. See doc below.</p>
<p>[NUMBER]  // built-in. See doc below.
<p>[DATEPERIOD]  e.g. [DATEPERIOD,1] [DATEPERIOD,1,12]</p>
</p>
<p>[DATETIME]    e.g. [DATETIME,4*,DOS] [DATETIME,4*,MTS] [DATETIME,4*]</p>
<p>[DATE]    // built-in. See doc below.
<p>[TIME2]      e.g. [TIME2,MT] [TIME2,MTS] [TIME2,MTS48]</p>
</p>
</td></tr>
<p>[DATEPERIOD]  e.g. [DATEPERIOD,1] [DATEPERIOD,1,12]
<tr><td><p><code>var=</code></p></td><td><p><code>iconv(input, conversion)</code></p></td><td>
</p>
<p>[DATETIME]    e.g. [DATETIME,4*,DOS] [DATETIME,4*,MTS] [DATETIME,4*]
</p>
<p>[TIME2]      e.g. [TIME2,MT] [TIME2,MTS] [TIME2,MTS48]
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>iconv(input, conversion)</td><td><p>iconv/oconv with access to exoprogram's environment variables.
</p>
<p>exoprog's iconv/oconv have the ability to call custom functions like "[funname,args...]"
</p>
<p>[NUMBER]  // built-in. See doc below.
</p>
<p>[DATE]    // built-in. See doc below.
</p>
<p>[DATEPERIOD]  e.g. [DATEPERIOD,1] [DATEPERIOD,1,12]
</p>
<p>[DATETIME]    e.g. [DATETIME,4*,DOS] [DATETIME,4*,MTS] [DATETIME,4*]
</p>
<p>[TIME2]      e.g. [TIME2,MT] [TIME2,MTS] [TIME2,MTS48]
</p></td></tr>
</table>
</table>
<h5 id=Ioconv_Date/Time_>Ioconv Date/Time </h5>
<h5 id=Ioconv_Date/Time_>Ioconv Date/Time </h5>
Line 4,461: Line 4,632:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>var=</td><td>iconv|oconv(var, "[DATE]")</td><td><p>Use iconv/oconv code "[DATE,args]" when you want date conversion to depend on the environment variable DATEFMT, particularly its American/International setting. Otherwise use ordinary "D" conversion codes directly for slightly greater performance.
<tr><td><p><code>var=</code></p></td><td><p><code>iconv|oconv(var, "[DATE]")</code></p></td><td><p>iconv/oconv "[DATE]"</p>
</p>
<p>Use iconv/oconv code "[DATE,args]" when you want date conversion to depend on the environment variable DATEFMT, particularly its American/International setting. Otherwise use ordinary "D" conversion codes directly for slightly greater performance.</p>
 
<p></p>
<p><em>var:</em> [oconv] An internal date (a number).
<p><em>var:</em> [oconv] An internal date (a number).</p>
</p>
<p><em>return:</em> [oconv] A readable date in text format depending on "[DATE,args]" e.g. "31 DEC 2020" "31/12/2020" "12/31/2020"</p>
<p><em>Returns:</em> [oconv] A readable date in text format depending on "[DATE,args]" e.g. "31 DEC 2020" "31/12/2020" "12/31/2020"
<p><em>var:</em> [iconv] A date in text format as above.</p>
</p>
<p><em>return:</em> [iconv] An internal date (a number) or "" if the input could not be understood as a valid date.</p>
<p><em>var:</em> [iconv] A date in text format as above.
<p><em>args:</em> If args is empty then DATEFMT is used as the conversion code. If args starts with "D" then args is used as the conversion codes but any E option in DATEFMT is appended. If args does not start with "D" then args are appended to DATEFMT, a "Z" option is appended, and the result used as the conversion code. A "*" option is equivalent to a second "Z" option.</p>
</p>
<p>If you are calling iconv/oconv in code and DATEFMT is adequate for your needs then pass it directly as a function argument e.g. 'var v1 = iconv|oconv(v2, DATEFORMAT);' instead of indirectly like 'var v1 = iconv|oconv(v2, "[DATE]");'.</p>
<p><em>Returns:</em> [iconv] An internal date (a number) or "" if the input could not be understood as a valid date.
<p>
</p>
<div class="highlight light"><pre><span class="kc">DATEFMT</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;D/E&quot;</span><span class="p">;</span>
<p><em>args:</em> If args is empty then DATEFMT is used as the conversion code. If args starts with "D" then args is used as the conversion codes but any E option in DATEFMT is appended. If args does not start with "D" then args are appended to DATEFMT, a "Z" option is appended, and the result used as the conversion code. A "*" option is equivalent to a second "Z" option.
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">iconv</span><span class="p">(</span><span class="s">&quot;JAN 9 2025&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;D&quot;</span><span class="p">);</span>
</p>
If you are calling iconv/oconv in code and DATEFMT is adequate for your needs then pass it directly as a function argument e.g. 'var v1 = iconv|oconv(v2, DATEFORMAT);' instead of indirectly like 'var v1 = iconv|oconv(v2, "[DATE]");'.
<div class="highlight light"><pre><span class="n">DATEFMT</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;D/E&quot;</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">iconv</span><span class="p">(</span><span class="s">&quot;JAN 9 2025&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;D&quot;</span><span class="p">);</span>
<span class="n">assert</span><span class="p">(</span><span class="nf">oconv</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;[DATE]&quot;</span><span class="w">  </span><span class="p">)</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="s">&quot; 9/ 1/2025&quot;</span><span class="p">);</span><span class="w">  </span><span class="c1">// &quot;D/EZ&quot; or &quot;[DATE,D]&quot; equivalent assuming D/E in DATEFMT (replace leading zeros with spaces)</span>
<span class="n">assert</span><span class="p">(</span><span class="nf">oconv</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;[DATE]&quot;</span><span class="w">  </span><span class="p">)</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="s">&quot; 9/ 1/2025&quot;</span><span class="p">);</span><span class="w">  </span><span class="c1">// &quot;D/EZ&quot; or &quot;[DATE,D]&quot; equivalent assuming D/E in DATEFMT (replace leading zeros with spaces)</span>
<span class="n">assert</span><span class="p">(</span><span class="nf">oconv</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;[DATE,4]&quot;</span><span class="w"> </span><span class="p">)</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="s">&quot; 9/ 1/2025&quot;</span><span class="p">);</span><span class="w">  </span><span class="c1">// &quot;D4Z&quot;  equivalent assuming D/E in DATEFMT (replace leading zeros with spaces)</span>
<span class="n">assert</span><span class="p">(</span><span class="nf">oconv</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;[DATE,4]&quot;</span><span class="w"> </span><span class="p">)</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="s">&quot; 9/ 1/2025&quot;</span><span class="p">);</span><span class="w">  </span><span class="c1">// &quot;D4Z&quot;  equivalent assuming D/E in DATEFMT (replace leading zeros with spaces)</span>
Line 4,482: Line 4,649:
<span class="n">assert</span><span class="p">(</span><span class="nf">oconv</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;[DATE,*]&quot;</span><span class="w"> </span><span class="p">)</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="s">&quot;9/1/2025&quot;</span><span class="p">);</span><span class="w">    </span><span class="c1">// &quot;DZZ&quot;  equivalent assuming D/E in DATEFMT (trim leading zeros and spaces)</span>
<span class="n">assert</span><span class="p">(</span><span class="nf">oconv</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;[DATE,*]&quot;</span><span class="w"> </span><span class="p">)</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="s">&quot;9/1/2025&quot;</span><span class="p">);</span><span class="w">    </span><span class="c1">// &quot;DZZ&quot;  equivalent assuming D/E in DATEFMT (trim leading zeros and spaces)</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td>var=</td><td>iconv|oconv(var, "[NUMBER]")</td><td><p>Use iconv/oconv "[NUMBER,args]" either when your numbers have currency or unit code suffixes or when you want number conversion to depend on the environment variable BASEFMT to determine thousands separator and decimal point. Otherwise use ordinary "MD" conversion codes directly for slightly greater performance.
<tr><td><p><code>var=</code></p></td><td><p><code>iconv|oconv(var, "[NUMBER]")</code></p></td><td><p>iconv/oconv "[NUMBER]"</p>
<p>Use iconv/oconv "[NUMBER,args]" either when your numbers have currency or unit code suffixes or when you want number conversion to depend on the environment variable BASEFMT to determine thousands separator and decimal point. Otherwise use ordinary "MD" conversion codes directly for slightly greater performance.</p>
<p>Formatting for numbers with optional currency code/unit suffix and is sensitive to the International or European setting in BASEFMT regarding use of commas or dots for thousands separators and decimal points.</p>
<p>Primarily used for oconv() but can be used in reverse for iconv.</p>
<p><em>var:</em> A number with an optional currency code or unit suffix. e.g. "12345.67USD"</p>
<p><em>return:</em> A formatted number with thousands separated conventionally e.g. "12.345.67USD".</p>
<p>iconv/oconv("[NUMBER]")      oconv leaves ndecimals untouched as in the input. iconv see below.</p>
<p>iconv/oconv("[NUMBER,2]")    Specified number of decimal places</p>
<p>iconv/oconv("[NUMBER,BASE]") Decimal places as per BASEFMT</p>
<p>iconv/oconv("[NUMBER,*]")    Leave decimal places untouched as in the input</p>
<p>iconv/oconv("[NUMBER,X]")    Leave decimal places untouched as in the input</p>
<p>iconv/oconv("[NUMBER,2Z]")  Z (suppress zero) combined with any other code for oconv results in empty output "" instead of "0.00" in case of zero input.</p>
<p></p>
<p>Empty input "" gives empty output "".</p>
<p></p>
<p>All leading, trailing and internal spaces are removed from the input.</p>
<p></p>
<p>A trailing currency or unit code is ignored and returned on output.</p>
<p></p>
<p>An exodus number is an optional leading + or - followed by one or more decimal digits 0-9 with a single optional decimal point placed anywhere.</p>
<p></p>
<p>If the input is non-numeric then "" is returned and STATUS set to 2. In the case of oconv with multiple fields or values each field or value is processed separately but STATUS is set to 2 if any are non-numeric.</p>
<p></p>
<p>iconv removes and oconv adds thousand separator chars. The thousands separator is  "," if BASEFMT starts with "MD" or "." if it starts with "MC".</p>
<p></p>
<p><em>oconv:</em> </p>
<p></p>
<p>Add thousands separator chars and optionally standardise the number of decimal places.</p>
<p></p>
<p>Multiple numbers in fields, values, subvalues etc. can be processed in one string.</p>
<p></p>
<p>Any leading + character is preserved on output.</p>
<p></p>
<p>Z suppresses zeros and returns empty string "" instead.</p>
<p></p>
<p>Special format "[NUMBER,ndecs,move_ndecs]": move_ndecs causes decimal point to be shifted left if positive or right if negative.</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;1234.5USD&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;[NUMBER,2]&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;1,234.50USD&quot; // Comma added and decimal places corrected.</span>
</pre></div>
iconv:
Remove all thousands separator chars and optionally standardise the number of decimal places.
If ndecs is not specified in the "[NUMBER]" pattern then ndecs is taken from the current RECORD using dictionary code NDECS if DICT is available otherwise it uses ndecs from BASEFMT.
iconv only handles a single field/value.
Optional prefix of "1/" or "/" causes the reciprocal of the number to be used. e.g. "1/100" or "/100" -> "0.01".
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">iconv</span><span class="p">(</span><span class="s">&quot;1,234.5678USD&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;[NUMBER]&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;1234.57USD&quot; // Comma removed</span>
</pre></div>
</p>
</p>
<p>Formatting for numbers with optional currency code/unit suffix and is sensitive to the International or European setting in BASEFMT regarding use of commas or dots for thousands separators and decimal points.
</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>amountunit(input0, out unitx)</code></p></td><td><p>Parse amount+currency code string.</p>
<p>Split amount+currency code/unit string into number and currency code/unit.</p>
<p><em>var:</em> "123.45USD"</p>
<p><em>return:</em> e.g. "123.45"</p>
<p><em>unitx[out]:</em> e.g. "USD"</p>
</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>amountunit(input0)</code></p></td><td>
</td></tr>
</table>
<h5 id=Time/Date_Utilities>Time/Date Utilities</h5>
 
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td><p><code>var=</code></p></td><td><p><code>timedate2()</code></p></td><td><p>Get text of date and time.</p>
<p>In users time zone</p>
<p>e.g. "2MAR2025 11:52AM"</p>
<p>Offset from UTC by TZ seconds.</p>
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>getdatetime(out user_date, out user_time, out system_date, out system_time, out UTC_date, out UTC_time)</code></p></td><td><p>Get current user, server and UTC dates and times.</p>
<p>User date and time is determined by adding the environment variable TZ.f(1)'s TZ offset (in seconds) to UTC date/time obtained from the operating system.</p>
<p>"system" date and time is normally the same as UTC date/time and is determined by adding the environment variable TZ.f(2)'s TZ offset (in seconds) to UTC date/time obtained from the operating system.</p>
</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>elapsedtimetext()</code></p></td><td><p>Get text of elapsed time.</p>
<p>Since environment variable TIMESTAMP.</p>
<p>TIMESTAMP is initialised with ostimestamp() at program/thread startup.</p>
<p>TIMESTAMP can be updated using ostimestamp() as and when desired.</p>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">elapsedtimetext</span><span class="p">();</span><span class="w"> </span><span class="c1">// e.g. &quot;&lt; 1ms&quot;</span>
</pre></div>
</p>
</p>
<p>Primarily used for oconv() but can be used in reverse for iconv.
</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>elapsedtimetext(timestamp1, timestamp2)</code></p></td><td><p>Get text of elapsed time.</p>
<p>Between two given timestamps</p>
<p><em>Warning:</em> Use ostimestamp() not ostime(). The first is in days and the second is in seconds.</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">elapsedtimetext</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="mf">0.55</span><span class="p">);</span><span class="w">  </span><span class="c1">// &quot;13 hours, 12 mins&quot;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">elapsedtimetext</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="mf">0.001</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;1 min, 26 secs&quot;</span>
</pre></div>
</p>
</p>
<p><em>var:</em> A number with an optional currency code or unit suffix. e.g. "12345.67USD"
</td></tr>
</p>
</table>
<p><em>Returns:</em> A formatted number with thousands separated conventionally e.g. "12.345.67USD".
<h5 id=Terminal_I/O_Utilities>Terminal I/O Utilities</h5>
</p>
 
<p>iconv/oconv("[NUMBER]")      oconv leaves ndecimals untouched as in the input. iconv see below.
<table class=wikitable>
</p>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<p>iconv/oconv("[NUMBER,2]")    Specified number of decimal places
<tr><td><p><code></code></p></td><td><p><code>note(msg, options, io response)</code></p></td><td><p>Output a message to stdout and optionally request input.</p>
</p>
<p>If input is requested but stdin is not a terminal then set the response to "" and continue.</p>
<p>iconv/oconv("[NUMBER,BASE]") Decimal places as per BASEFMT
<p><em>options:</em> R = Response requested. C upper case response.</p>
</p>
<p>
<p>iconv/oconv("[NUMBER,*]")    Leave decimal places untouched as in the input
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">response</span><span class="p">;</span>
<span class="c1">// call note(&quot;Enter something&quot;, &quot;RC&quot;, response);</span>
</pre></div>
</p>
</p>
<p>iconv/oconv("[NUMBER,X]")   Leave decimal places untouched as in the input
</td></tr>
<tr><td><p><code></code></p></td><td><p><code>note(msg)</code></p></td><td><p>Output a message to stdout.</p>
<p>
<div class="highlight light"><pre><span class="k">call</span><span class="w"> </span><span class="nf">note</span><span class="p">(</span><span class="s">&quot;Hello world.&quot;</span><span class="p">);</span>
</pre></div>
</p>
</p>
<p>iconv/oconv("[NUMBER,2Z]")   Z (suppress zero) combined with any other code for oconv results in empty output "" instead of "0.00" in case of zero input.
</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>decide(question, options = "")</code></p></td><td><p>Input user selection from a list of options.</p>
<p>If stdin is not a terminal, set the response to "" and continue.</p>
<p><em>return:</em> The chosen option (value not number) or "" if the user cancelled.</p>
</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>decide(question, options, out reply, defaultreply = 1)</code></p></td><td><p>Input user selection from a list of options.</p>
<p>If stdin is not a terminal set the response to the default value, or "" if none, and continue.</p>
<p><em>defaultreply:</em> A default option if the user presses Enter.</p>
<p><em>reply[out]:</em> The option number that the user chose or "" if they cancelled.</p>
<p><em>return:</em> The chosen option (value not number) or "" if the user cancelled.</p>
</td></tr>
<tr><td><p><code>if</code></p></td><td><p><code>esctoexit()</code></p></td><td><p>Check for user pause or cancel.</p>
<p>If stdin is a terminal, check if a key has been pressed and, if so, pause execution and ask the user to confirm if they want to escape/cancel or resume processing.</p>
<p><em>return:</em> </p>
<dl>
<dt>True</dt><dd>A key has been pressed and the user chose not to resume.</dd>
<dt>False</dt><dd>stdif is not a terminal, no key has been pressed, or the user chose to resume.</dd>
</dl>
</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>AT(code)</code></p></td><td><p>Get a string to control terminal operation.</p>
<p><em>return:</em> A string to be output to the terminal in order to accomplish the desired operation.</p>
<p>The terminal protocol is xterminal.</p>
<p><em>code:</em> </p>
<dl>
<dt>  n</dt><dd>Position the cursor at column number n (1 based).</dd>
<dt>  0</dt><dd>Position the cursor at the first column (1).</dd>
<dt> -1</dt><dd>Clear the screen and home the cursor.</dd>
<dt> -2</dt><dd>Position the cursor at the top left home (x, y = 1, 1).</dd>
<dt> -3</dt><dd>Clear from the cursor at the end of screen.</dd>
<dt> -4</dt><dd>Clear from cursor to end of line.</dd>
<dt>-40</dt><dd>Position the cursor at columnno 0 and clear to end of line.</dd>
</dl>
</td></tr>
<tr><td><p><code>var=</code></p></td><td><p><code>AT(x, y)</code></p></td><td><p>Get a terminal cursor positioning string.</p>
<p><em>return:</em> A string to be output to the terminal to position the cursor at the desired screen x and y position.</p>
<p>The terminal protocol is xterminal.</p>
</td></tr>
<tr><td><p><code>if</code></p></td><td><p><code>getcursor(out cursor, delayms = 3000, max_errors = 0)</code></p></td><td><p>Get the position of the terminal cursor.</p>
<p><em>cursor[out]:</em> If stdin is a terminal, an FM delimited string containing the x and y coordinates of the current terminal cursor.</p>
<p>x and y are 1 based, not 0 based.</p>
<p>If stdin is not a terminatl then an empty string "" is returned.</p>
<p>The cursor additionally contains a third field which contains the delay in ms from the terminal.</p>
<p>The FM delimited string returned can be later passed to setcursor() to reposition the cursor back to its original position or it can be parsed and used accordingly.</p>
<p><em>delayms:</em> Default 3000ms. The maximum time to wait for terminal response.</p>
<p><em>max_errors:</em> Default is 0. If not zero, reset the number of times to error before automatically disabling getcursor(). max_errors is initialised to 3. If negative then max_errors has the the effect of disabling all future calls to getcursor().</p>
<p>In case the terminal fails to respond correctly within the required timeout, or is currently disabled due to too many failures, or has been specifically disabled then the returned "cursor" var contains a 4th field:</p>
<dl>
<dt>TIMEOUT</dt><dd>The terminal failed to respond within the timeout.</dd>
<dt>READ_ERROR</dt><dd>Failed to read terminal response.</dd>
<dt>INVALID_RESPONSE</dt><dd>Terminal response invalid.</dd>
<dt>SETUP_ERROR</dt><dd>Terminal setup failed.</dd>
<dt>DISABLED</dt><dd>Terminal is disabled due to more errors than the maximum currently set.</dd>
</dl>
<p>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">cursor</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">isterminal</span><span class="p">()</span><span class="w"> </span><span class="ow">and</span><span class="w"> </span><span class="ow">not</span><span class="w"> </span><span class="nf">getcursor</span><span class="p">(</span><span class="n">cursor</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="c1">// cursor becomes something like &quot;1^20^0.012345&quot;_var</span>
</pre></div>
</p>
</p>
 
</td></tr>
<p>Empty input "" gives empty output "".
<tr><td><p><code>var=</code></p></td><td><p><code>getcursor()</code></p></td><td><p>Get the position of the terminal cursor.</p>
<p>For more info see the main getcursor() function above.</p>
<p>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">cursor</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">getcursor</span><span class="p">();</span><span class="w"> </span><span class="c1">// If isterminal() then cursor becomes something like &quot;0^20^0.012345&quot;_var</span>
</pre></div>
</p>
</p>
 
</td></tr>
<p>All leading, trailing and internal spaces are removed from the input.
<tr><td><p><code></code></p></td><td><p><code>setcursor(cursor_coordinates)</code></p></td><td><p>If stdin is a terminal, position the cursor at x and y as per the given coordinates.</p>
</p>
<p><em>cursor_coordinates:</em> An FM delimited string containing the x and y coordinates of the terminal cursor as can be obtained by getcursor().
 
<div class="highlight light"><pre><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">isterminal</span><span class="p">())</span><span class="w"> </span><span class="p">{</span>
<p>A trailing currency or unit code is ignored and returned on output.
<span class="w">    </span><span class="nf">let</span><span class="w"> </span><span class="n">cursor</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">getcursor</span><span class="p">();</span><span class="w"> </span><span class="c1">// Save the current cursor position.</span>
<span class="w">    </span><span class="n">TRACE</span><span class="p">(</span><span class="n">cursor</span><span class="p">)</span><span class="w">            </span><span class="c1">// Show the saved cursor position.</span>
<span class="w">    </span><span class="nf">print</span><span class="p">(</span><span class="nf">AT</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">));</span><span class="w">          </span><span class="c1">// Position the cursor at 0,0.</span>
<span class="w">    </span><span class="nf">setcursor</span><span class="p">(</span><span class="n">cursor</span><span class="p">);</span><span class="w">        </span><span class="c1">// Restore its position</span>
<span class="p">}</span>
</pre></div>
</p>
</p>
 
</td></tr>
<p>An exodus number is an optional leading + or - followed by one or more decimal digits 0-9 with a single optional decimal point placed anywhere.
</table>
</p>
<h5 id=Array_Utilities>Array Utilities</h5>
 
<p>If the input is non-numeric then "" is returned and STATUS set to 2. In the case of oconv with multiple fields or values each field or value is processed separately but STATUS is set to 2 if any are non-numeric.
</p>
 
<p>iconv removes and oconv adds thousand separator chars. The thousands separator is  "," if BASEFMT starts with "MD" or "." if it starts with "MC".
</p>
 
<p><em>oconv:</em>
</p>
 
<p>Add thousands separator chars and optionally standardise the number of decimal places.
</p>
 
<p>Multiple numbers in fields, values, subvalues etc. can be processed in one string.
</p>
 
<p>Any leading + character is preserved on output.
</p>
 
<p>Z suppresses zeros and returns empty string "" instead.
</p>
 
<p>Special format "[NUMBER,ndecs,move_ndecs]": move_ndecs causes decimal point to be shifted left if positive or right if negative.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">oconv</span><span class="p">(</span><span class="s">&quot;1234.5USD&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;[NUMBER,2]&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;1,234.50USD&quot; // Comma added and decimal places corrected.</span>
</pre></div>
 
</p>
<p><em>iconv:</em>
</p>
 
<p>Remove all thousands separator chars and optionally standardise the number of decimal places.
</p>
 
<p>If ndecs is not specified in the "[NUMBER]" pattern then ndecs is taken from the current RECORD using dictionary code NDECS if DICT is available otherwise it uses ndecs from BASEFMT.
</p>
 
<p>iconv only handles a single field/value.
</p>
 
Optional prefix of "1/" or "/" causes the reciprocal of the number to be used. e.g. "1/100" or "/100" -> "0.01".
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">iconv</span><span class="p">(</span><span class="s">&quot;1,234.5678USD&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;[NUMBER]&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;1234.57USD&quot; // Comma removed</span>
</pre></div>
</td></tr>
<tr><td>var=</td><td>amountunit(input0, out unitx)</td><td><p>Split amount+currency code/unit string into number and currency code/unit.
</p>
<p><em>var:</em> "123.45USD"
</p>
<p><em>Returns:</em> e.g. "123.45"
</p>
<em>unitx:</em> [out] e.g. "USD"</td></tr>
<tr><td>var=</td><td>amountunit(input0)</td><td><p>Split amount+currency code/unit string into number and currency code/unit.
</p>
<p><em>var:</em> "123.45USD"
</p>
<p><em>Returns:</em> e.g. "123.45"
</p>
<em>unitx:</em> [out] e.g. "USD</td></tr>
</table>
<h5 id=Time/Date_Utilities>Time/Date Utilities</h5>
 
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>var=</td><td>timedate2()</td><td>
<p><em>Returns:</em> Text of date and time in users time zone
</p>
<p>e.g. "2MAR2025 11:52AM"
</p>
Offset from UTC by TZ seconds.</td></tr>
<tr><td></td><td>getdatetime(out user_date, out user_time, out system_date, out system_time, out UTC_date, out UTC_time)</td><td>
<p><em>Returns:</em> User, server and UTC date and time
</p>
<p>User date and time is determined by adding the environment variable TZ.f(1)'s TZ offset (in seconds) to UTC date/time obtained from the operating system.
</p>
<p>"system" date and time is normally the same as UTC date/time and is determined by adding the environment variable TZ.f(2)'s TZ offset (in seconds) to UTC date/time obtained from the operating system.
</p>
</td></tr>
<tr><td>var=</td><td>elapsedtimetext()</td><td><p>Get text of elapsed time since environment variable TIMESTAMP was initialised with ostimestamp() at program/thread startup.
</p>
TIMESTAMP can be updated using ostimestamp() as and when desired.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">elapsedtimetext</span><span class="p">();</span><span class="w"> </span><span class="c1">// e.g. &quot;&lt; 1ms&quot;</span>
</pre></div>
</td></tr>
<tr><td>var=</td><td>elapsedtimetext(timestamp1, timestamp2)</td><td><p>Get text of elapsed time between two timestamps
</p>
Caution. Use ostimestamps not ostimes. One is in days and the other is in seconds.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">elapsedtimetext</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="mf">0.55</span><span class="p">);</span><span class="w">  </span><span class="c1">// &quot;13 hours, 12 mins&quot;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">elapsedtimetext</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="mf">0.001</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;1 min, 26 secs&quot;</span>
</pre></div>
</td></tr>
</table>
<h5 id=Terminal_I/O_Utilities>Terminal I/O Utilities</h5>
 
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td></td><td>note(msg, options, io response)</td><td><p>If stdin is a terminal, output a message to stdout and optionally pause processing and request a response from the user, otherwise set the response to "" and continue.
</p>
<em>options:</em> R = Response requested. C upper case response.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">response</span><span class="p">;</span>
<span class="c1">// call note(&quot;Enter something&quot;, &quot;RC&quot;, response);</span>
</pre></div>
</td></tr>
<tr><td></td><td>note(msg)</td><td>Output a message to stdin and continue.
<div class="highlight light"><pre><span class="k">call</span><span class="w"> </span><span class="nf">note</span><span class="p">(</span><span class="s">&quot;Hello world.&quot;</span><span class="p">);</span>
</pre></div>
</td></tr>
<tr><td>var=</td><td>decide(question, options = "")</td><td><p>If stdin is a terminal, pause processing, list some given options to stdout and request the user to make a choice, otherwise set the response to "" and continue.
</p>
<em>Returns:</em> The chosen option (value not number) or "" if the user cancelled.</td></tr>
<tr><td>var=</td><td>decide(question, options, out reply, defaultreply = 1)</td><td><p>Same as decide() above but extended.
</p>
<p><em>defaultreply:</em> A default option if the user presses Enter.
</p>
<em>reply:</em> [out] The option number that the user chose or "" if they cancelled.</td></tr>
<tr><td>if</td><td>esctoexit()</td><td><p>If stdin is a terminal, check if a key has been pressed and, if so, pause execution and ask the user to confirm if they want to escape/cancel or resume processing.
</p>
<em>Returns:</em> True if a key has been pressed and the user confirms to escape/cancel. False if no key has been pressed or the user chooses to resume and not escape/cancel.</td></tr>
<tr><td>var=</td><td>AT(code)</td><td><p>Get a string to control terminal operation.
</p>
<p><em>Returns:</em> A string to be output to the terminal in order to accomplish the desired operation.
</p>
<p>The terminal protocol is xterminal.
</p>
<p><em>code:</em>
</p>
<p>n  Position the cursor at column number n
</p>
<p>0  Position the cursor at column number 0
</p>
<p>-1  Clear the screen and home the cursor
</p>
<p>-2  Position the cursor at the top left home (x,y = 0,0)
</p>
<p>-3  Clear from the cursor at the end of screen
</p>
<p>-4  Clear from cursor to end of line
</p>
-40 Position the cursor at columnno 0 and clear to end of line</td></tr>
<tr><td>var=</td><td>AT(x, y)</td><td><p>Get a terminal cursor positioning string.
</p>
<p><em>Returns:</em> A string to be output to the terminal to position the cursor at the desired screen x and y position.
</p>
The terminal protocol is xterminal.</td></tr>
<tr><td>if</td><td>getcursor(out cursor, delayms = 3000, max_errors = 0)</td><td><p>Get the position of the terminal cursor.
</p>
<p><em>cursor:</em> [out] If stdin is a terminal, an FM delimited string containing the x and y coordinates of the current terminal cursor.
</p>
<p>If stdin is not a terminatl then an empty string "" is returned.
</p>
<p>The cursor additionally contains a third field which contains the delay in ms from the terminal.
</p>
<p>The FM delimited string returned can be later passed to setcursor() to reposition the cursor back to its original position or it can be parsed and used accordingly.
</p>
<p><em>delayms:</em> Default 3000ms. The maximum time to wait for terminal response.
</p>
<p><em>max_errors:</em> Default is 0. If not zero, reset the number of times to error before automatically disabling getcursor(). max_errors is initialised to 3. If negative then max_errors has the the effect of disabling all future calls to getcursor().
</p>
<p>In case the terminal fails to respond correctly within the required timeout, or is currently disabled due to too many failures, or has been specifically disabled then the returned "cursor" var contains a 4th field:
</p>
<p>TIMEOUT - The terminal failed to respond within the timeout.
</p>
<p>READ_ERROR - Failed to read terminal response.
</p>
<p>INVALID_RESPONSE - Terminal response invalid.
</p>
<p>SETUP_ERROR - Terminal setup failed.
</p>
DISABLED - Terminal is disabled due to more errors than the maximum currently set.
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">cursor</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">isterminal</span><span class="p">()</span><span class="w"> </span><span class="ow">and</span><span class="w"> </span><span class="ow">not</span><span class="w"> </span><span class="nf">getcursor</span><span class="p">(</span><span class="n">cursor</span><span class="p">))</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="c1">// cursor becomes something like &quot;0^20^0.012345&quot;_var</span>
</pre></div>
</td></tr>
<tr><td>var=</td><td>getcursor()</td><td><p>Get the position of the terminal cursor.
</p>
For more info see the main getcursor() function above.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">cursor</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">getcursor</span><span class="p">();</span><span class="w"> </span><span class="c1">// If isterminal() then cursor becomes something like &quot;0^20^0.012345&quot;_var</span>
</pre></div>
</td></tr>
<tr><td></td><td>setcursor(cursor_coordinates)</td><td><p>If stdin is a terminal, position the cursor at x and y as per the given coordinates.
</p>
<em>cursor_coordinates:</em> An FM delimited string containing the x and y coordinates of the terminal cursor as can be obtained by getcursor().
<div class="highlight light"><pre><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nf">isterminal</span><span class="p">())</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="nf">let</span><span class="w"> </span><span class="n">cursor</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">getcursor</span><span class="p">();</span><span class="w"> </span><span class="c1">// Save the current cursor position.</span>
<span class="w">    </span><span class="n">TRACE</span><span class="p">(</span><span class="n">cursor</span><span class="p">)</span><span class="w">            </span><span class="c1">// Show the saved cursor position.</span>
<span class="w">    </span><span class="nf">print</span><span class="p">(</span><span class="nf">AT</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">));</span><span class="w">          </span><span class="c1">// Position the cursor at 0,0.</span>
<span class="w">    </span><span class="nf">setcursor</span><span class="p">(</span><span class="n">cursor</span><span class="p">);</span><span class="w">        </span><span class="c1">// Restore its position</span>
<span class="p">}</span>
</pre></div></td></tr>
</table>
<h5 id=Array_Utilities>Array Utilities</h5>


<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>var=</td><td>invertarray(input, pad = false)</td><td><p>Dynamic array fields become values and vice versa
<tr><td><p><code>var=</code></p></td><td><p><code>invertarray(input, pad = false)</code></p></td><td><p>Dynamic array fields become values and vice versa</p>
</p>
<p><em>return:</em> The inverted dynamic array.</p>
<p><em>Returns:</em> The inverted dynamic array.
<p><em>pad:</em> If true then on return, all fields will have the same number of values with superfluous trailing VMs where necessary.</p>
</p>
<p>
<em>pad:</em> If true then on return, all fields will have the same number of values with superfluous trailing VMs where necessary.
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;a]b]c^1]2]3&quot;</span><span class="kt">_var</span><span class="p">;</span>
<div class="highlight light"><pre><span class="nf">let</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;a]b]c^1]2]3&quot;</span><span class="kt">_var</span><span class="p">;</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">invertarray</span><span class="p">(</span><span class="n">v1</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;a]1^b]2^c]3&quot;_var</span>
<span class="nf">let</span><span class="w"> </span><span class="n">v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">invertarray</span><span class="p">(</span><span class="n">v1</span><span class="p">);</span><span class="w"> </span><span class="c1">// &quot;a]1^b]2^c]3&quot;_var</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
<tr><td></td><td>sortarray(io array, fns = "", order = "")</td><td><p>Sorts fields of multivalues of dynamic arrays in parallel
<tr><td><p><code></code></p></td><td><p><code>sortarray(io array, fns = "", order = "")</code></p></td><td><p>Sort parallel fields of multivalues of dynamic arrays</p>
</p>
<p><em>fns:</em> VM separated list of field numbers to sort in parallel based on the first field number</p>
<p><em>fns:</em> VM separated list of field numbers to sort in parallel based on the first field number
<p><em>order:</em> </p>
</p>
<dl>
<p><em>order:</em>
<dt>AL</dt><dd>Ascending  - Left Justified (Alphabetic)</dd>
</p>
<dt>DL</dt><dd>Descending - Left Justified (Alphabetic)</dd>
<p>AL Ascending  - Left Justified - Alphabetic
<dt>AR</dt><dd>Ascending  - Right Justified (Numeric/Natural)</dd>
</p>
<dt>DR</dt><dd>Descending - Right Justified (Numeric/Natural)</dd>
<p>DL Descending - Left Justfiied  - Alphabetic
</dl>
</p>
<p>
<p>AR Ascending  - Right Justified - Numeric
</p>
DR Descending - Right Justified - Numeric
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;f1^10]20]2]1^ww]xx]yy]zz^f3^f4&quot;</span><span class="kt">_var</span><span class="p">;</span><span class="w">  </span><span class="c1">// fields 2 and 3 are parallel multivalues and currently unordered.</span>
<div class="highlight light"><pre><span class="kt">var</span><span class="w"> </span><span class="n">v1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;f1^10]20]2]1^ww]xx]yy]zz^f3^f4&quot;</span><span class="kt">_var</span><span class="p">;</span><span class="w">  </span><span class="c1">// fields 2 and 3 are parallel multivalues and currently unordered.</span>
<span class="nf">sortarray</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;2]3&quot;</span><span class="kt">_var</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;AR&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// v1 -&gt; &quot;f1^1]2]10]20^zz]yy]ww]xx^f3^f4&quot;_var</span>
<span class="nf">sortarray</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;2]3&quot;</span><span class="kt">_var</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;AR&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// v1 -&gt; &quot;f1^1]2]10]20^zz]yy]ww]xx^f3^f4&quot;_var</span>
</pre></div>
</pre></div>
</p>
</td></tr>
</td></tr>
</table>
</table>
Line 4,740: Line 4,869:
<table class=wikitable>
<table class=wikitable>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr> <th>Use</th> <th>Function</th> <th>Description</th> </tr>
<tr><td>if</td><td>lockrecord(filename, io file, keyx, recordx, waitsecs = 0, allowduplicate = false)</td><td>Does not actually return record</td></tr>
<tr><td><p><code>if</code></p></td><td><p><code>lockrecord(filename, io file, keyx, unused, waitsecs = 0, allowduplicate = false)</code></p></td><td>
<tr><td>if</td><td>lockrecord(filename, io file, keyx)</td><td>Does not actually return recor</td></tr>
</td></tr>
<tr><td>if</td><td>unlockrecord(filename, io file, key)</td><td>Does not actually return reco</td></tr>
<tr><td><p><code>if</code></p></td><td><p><code>lockrecord(filename, io file, keyx)</code></p></td><td>
<tr><td>if</td><td>unlockrecord()</td><td>Does not actually return rec</td></tr>
</td></tr>
<tr><td><p><code>if</code></p></td><td><p><code>unlockrecord(filename, io file, key)</code></p></td><td>
</td></tr>
<tr><td><p><code>if</code></p></td><td><p><code>unlockrecord()</code></p></td><td>
</td></tr>
</table>
</table>



Latest revision as of 16:48, 20 April 2025

Sections:

  1. var
  2. dim
  3. exoprog
Var Creation
Use Function Description

var v1;

Create an unassigned var.

Unassigned variables can be assigned conditionally in if/else statements or used as outbound arguments of function calls.

A runtime error is thrown if a var is used before being assigned so silent "use before assign" bugs cannot occur.

var client; // Unassigned var
if (not read(client from "xo_clients", "SB001")) ...

//             Exodus keywords:     C++ declarations:
//             Non-Const   Const    Non-Const   Const
//             -----------------    ----------------------
// Variable:   var         let      var         const var
// Reference:  out         in       var&        const var&

var v1 = expression;

Assign a var using a literal or an expression.

Use "let" instead of "var" wherever possible as a shorthand way of writing "const var".

var v1 = 42;                 // Integer
var v2 = 42.3;               // Double
var v3 = "abc";              // String
var v4 = 'x';                // char
var v5 = true;               // bool

var v6 = v1 + 100;           // Arithmetic
var v7 = v3 ^ "xyz";         // Concatenation
var v8 = oslist(".").sort(); // Built in functions

let v9 = 12345;              // A const var

var v10 = 12'345_var;        // A literal var integer
var v11 = 123.45_var;        // A literal var double
var v12 = "f1^v1]v2^f3"_var; // A literal var string

var x = 0.1, y = "0.2", z = x + y; // z -> 0.3

if

v1.assigned()

Check if a var has been assigned a value.

return: True if the var is assigned, otherwise false

if

v1.unassigned()

Check if a var has not been assigned a value;

return: True if the var is unassigned, otherwise false

var=

v2.or_default(defaultvalue)

Copy a var or, if it is unassigned, copy a default value.

return: A copy of the var if it is assigned or the default value if it is not.

Can be used to handle optional arguments in functions.

defaultvalue: Cannot be unassigned.

var v1; // Unassigned
var v2 = v1.or_default("abc"); // v2 -> "abc"
// or
var v3 = or_default(v1, "abc");

Mutator: defaulter()

v1.defaulter(defaultvalue)

If a var is unassigned, assign a default value.

If the var is unassigned then assign the default value to it, otherwise do nothing.

defaultvalue: Cannot be unassigned.

var v1; // Unassigned
v1.defaulter("abc"); // v1 -> "abc"
// or
defaulter(v1, "abc");

v1.swap(io v2)

Swap the contents of one var with another.

Useful for stashing large strings quickly. They are moved using pointers without making copies or allocating memory.

Eiher or both variables may be unassigned.

var v1 = space(65'536);
var v2 = "";
v1.swap(v2); // v1 -> "" // v2.len() -> 65'536
// or
swap(v1, v2);

var=

v2.move()

Move a var into another.

Shallow copy of var data and take ownership of the moved var's string if any. The moved var becomes an empty string.

This allows large strings to be handled efficiently. They are moved using pointers without making copies or allocating memory.

The moved var must be assigned otherwise a VarUnassigned error is thrown.

var v1 = space(65'536);
var v2 = v1.move(); // v2.len() -> 65'536 // v1 -> ""
// or
var v3 = move(v2);

var=

v2.clone()

Return a copy of the var.

The cloned var may be unassigned, in which case the copy will be unassigned too.

var v1 = "abc";
var v2 = v1.clone(); // "abc"
// or
var v3 = clone(v2);

var=

v1.dump()

Return a string describing internal data of a var.

If the str is located on the heap then its address is given.

typ:

0x01
str is available.
0x02
int is available.
0x04
dbl is available.
0x08
nan: str is not a number.
0x16
osfile (nan is true, str, int and dbl have special meaning).

var v1 = str("x", 32);
v1.dump().outputl(); /// e.g. var:0x7ffea7462cd0 typ:1 str:0x584d9e9f6e70 "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
// or
outputl(dump(v1));

Arithmetical Operators
Use Function Description

if

v1.isnum()

Check if a var is numeric.

return: True if a var holds a double, an integer, or a string that is defined as numeric.

A string is defined as numeric only if it consists of one or more digits 0-9, with an optional decimal point "." placed anywhere, with an optional + or - sign prefix, or it is the empty string "", which is defined to be zero.

if ("+123.45"_var.isnum()) ... ok
if (       ""_var.isnum()) ... ok
if (not   "."_var.isnum()) ... ok
// or
if (isnum("123.")) ... ok

var=

v1.num()

Return a copy of the var if it is numeric or 0 otherwise.

Allow working numerically with data that may be non-numeric.

return: A guaranteed numeric var

var v1 = "123.45"_var.num();    // 123.45
var v2 = "abc"_var.num() + 100; // 100

var=

v2 + v3

Addition

Any attempt to perform numeric operations on non-numeric strings will throw a runtime error VarNonNumeric.

Floating point numbers are implicitly converted to strings with no more than 12 significant digits of precision. This practically eliminates all floatng point rounding errors.

Internally, 0.1 + 0.2 looks like this using doubles.

0.10000000000000003 + 0.20000000000000004 -> 0.30000000000000004

var v1 = 0.1;
var v2 = v1 + 0.2; // 0.3

var=

v2 - v3

Subtraction

var=

v2 * v3

Multiplication

var=

v2 / v3

Division

var=

v2 % v3

Modulus

v1 += v2

Self addition

var v1 = 0.1;
v1 += 0.2; // 0.3

v1 -= v2

Self subtraction

v1 *= v2

Self multiplication

v1 /= v2

Self division

v1 %= v2

Self modulus

v1 ++

Post increment

var v1 = 3;
var v2 = v1 ++; // v2 -> 3 // v1 -> 4

v1 --

Post decrement

var v1 = 3;
var v2 = v1 --; // v2 -> 3 // v1 -> 2

++ v1

Pre increment

var v1 = 3;
var v2 = ++ v1; // v2 -> 4 // v1 -> 4

-- v1

Pre decrement

var v1 = 3;
var v2 = -- v1; // v2 -> 2 // v1 -> 2

Dynamic Array Creation, Access And Update
Use Function Description

var=

""_var

Literal suffix "_var".

Allow dynamic arrays to be seamlessly embedded in code using a predefined set of visible equivalents of unprintable field mark characters as follows:

Visible equivalents:

`
RM Record mark
^
FM Field mark
]
VM Value mark
}
SM Subvalue mark
|
TM Text mark
~
ST Subtext mark

var v1 = "f1^f2^v1]v2^f4"_var; // "f1" _FM "f2" _FM "v1" _VM "v2" _FM "f4"

var v1 = {"a", "b", "c" ...}; // Initializer list

Code a dynamic array var as as list.

C++ constrains list elements to be all the same type: var, string, double, int, etc. but they all end up as fields of a dynamic array string.

var v1 = {11, 22, 33}; // "11^22^33"_var

var=

v2(fieldno); v1(fieldno) = v2

Dynamic array field extraction, update and append:

See also inserter() and remover().

var v1 = "aa^bb"_var;
v1(4) = 44; // v1 -> "aa^bb^^44"_var
// Field number -1 causes appending a field when updating.
v1(-1) = "55"; // v1 -> "aa^bb^^44^55"_var

Field access:

It is recommended to use "v1.f(fieldno)" syntax using a ".f(" prefix to access fields in expressions instead of plain "v1(fieldno)". The former syntax (using .f()) will always compile whereas the latter does not compile in all contexts. It will compile only if being called on a constant var or in a location which requires a var. This is due to C++ not making a clear distinction between usage on the left and right side of assignment operator =.

Furthermore using plain round brackets without the leading .f can be confused with function call syntax.

var v1 = "aa^bb^cc"_var;
var v2 = v1.f(2); // "bb" /// .f() style access. Recommended.
var v3 =   v1(2); // "bb" ///   () style access. Not recommended.

var=

v2(fieldno, valueno); v1(fieldno, valueno) = v2

Dynamic array value update and append

See also inserter() and remover().

var v1 = "aa^b1]b2^cc"_var;
v1(2, 4) = "44"; // v1 -> "aa^b1]b2]]44^cc"_var
// value number -1 causes appending a value when updating.
v1(2, -1) = 55; // v1 -> "aa^b1]b2]]44]55^cc"_var

Value access:

var v1 = "aa^b1]b2^cc"_var;
var v2 = v1.f(2,2); // "b2" /// .f() style access. Recommended.
var v3 =   v1(2,2); // "b2" ///   () style access. Not recommended.

String Creation
Use Function Description

var=

v2 ^ v3

String concatention operator ^

At least one side must be a var.

"aa" ^ "22" will not compile but "aa" "22" will.

Floating point numbers are implicitly converted to strings with no more than 12 significant digits of precision. This practically eliminates all floatng point rounding errors.

var v2 = "aa";
var v1 = v2 ^ 22; // "aa22"

v1 ^= v2

String self concatention ^= (append)

var v1 = "aa";
v1 ^= 22; // v1 -> "aa22"

var=

varnum.round(ndecimals = 0)

Round a number.

Convert a number into a string after rounding it to a given number of decimal places.

Trailing zeros are not omitted. A leading "0." is shown where appropriate.

0.5 always rounds away from zero. i.e. 1.5 -> 2 and -2.5 -> -3

var: The number to be converted.

ndecimals: Determines how many decimal places are shown to the right of the decimal point or, if ndecimals is negative, how many 0's to the left of it.

return: A var containing an ASCII string of digits with a leading "-" if negative, and a decimal point "." if ndecimals is > 0.

let v1 = var(0.295).round(2);  //  "0.30"
// or
let v2 = round(1.295, 2);      //  "1.30"

var v3 = var(-0.295).round(2); // "-0.30"
// or
var v4 = round(-1.295, 2);     // "-1.30"

var v5 = round(0, 1);           // "0.0"
var v6 = round(0, 0);           // "0"
var v7 = round(0, -1);          // "0"

Negative number of decimals rounds to the left of the decimal point

let v1 = round(123456.789,  0); // "123457"
let v2 = round(123456.789, -1); // "123460"
let v3 = round(123456.789, -2); // "123500"

var=

var::chr(num)

Get a char.

num: An integer 0-255.

return: A string containing a single char

0-127 -> ASCII, 128-255 -> invalid UTF-8 which cannot be written to the database or used in many exodus string operations

let v1 = var::chr(0x61); // "a"
// or
let v2 = chr(0x61);

var=

var::textchr(num)

Get a Unicode character.

num: A Unicode Code Point (Number)

return: A single Unicode character in UTF8 encoding.

let v1 = var::textchr(171416); // "𩶘" // or "\xF0A9B698"
// or
let v2 = textchr(171416);

var=

var::textchrname(unicode_code_point)

Get a Unicode character name

unicode_code_point: 0 - 0x10FFFF.

return: Text of the name or "" if not a valid Unicode Code Point

let v1 = var::textchrname(91); // "LEFT SQUARE BRACKET"
// or
let v2 = textchrname(91);

var=

strvar.str(num)

Get a string of repeated substrings.

var: The substring to be repeated

num: How many times to repeat the substring

return: A string

let v1 = "ab"_var.str(3); // "ababab"
// or
let v2 = str("ab", 3);

var=

var::space(nspaces)

Get a string as a given number of spaces.

nspaces: The number of spaces required.

return: A string of space chars.

let v1 = var::space(3); // "␣␣␣"
// or
let v2 = space(3);

var=

varnum.numberinwords(locale = "")

Get a number written out in words insteads of digits.

return: A string.

locale: e.g. en_GB, ar_AE, el_CY, es_US, fr_FR etc or a language name e.g. "french".

let softhyphen = "\xc2\xad";
let v1 = var(123.45).numberinwords("de_DE").replace(softhyphen, " "); // "ein␣hundert␣drei␣und␣zwanzig␣Komma␣vier␣fünf"

String Scanning
Use Function Description

var=

strvar.at(pos1)

Get a single char from a string.

pos1: First char is 1. Last char is -1.

return: A single char if pos1 +/- the length of the string, or "" if greater. Returns the first char if pos1 is 0 or (-pos1) > length.

var v1 = "abc";
var v2 = v1.at(2);  // "b"
var v3 = v1.at(-3); // "a"
var v4 = v1.at(4);  // ""

var=

strvar.ord()

Get the char number of a char.

return: A number between 0 and 255.

If given a string, then only the first char is considered.

Equivalent to ord() in php

let v1 = "abc"_var.ord(); // 0x61 // decimal 97, 'a'
// or
let v2 = ord("abc");

var=

strvar.textord()

Get the Unicode Code Point of a Unicode character.

var: A UTF-8 string. Only the first Unicode character is considered.

return: A number 0 to 0x10FFFF.

Equivalent to ord() in python and ruby, mb_ord() php.

let v1 = "Γ"_var.textord(); // 915 // U+0393: Greek Capital Letter Gamma (Unicode character)
// or
let v2 = textord("Γ");

var=

strvar.len()

Get the length of a source string in number of chars.

return: A number

let v1 = "abc"_var.len(); // 3
// or
let v2 = len("abc");

if

strvar.empty()

Check if the var is an empty string.

return: True if it is empty amd false if not.

This is a shorthand and more expressive way of writing 'if (var == "")' or 'if (var.len() == 0)' or 'if (not var.len())'

Note that 'if (var.empty())' is not exactly the same as 'if (not var)' because 'if (var("0.0")' is also defined as false. If a string can be converted to 0 then it is considered to be false. Contrast this with common scripting languages where 'if (var("0"))' is defined to be true.

let v1 = "0";
if (not v1.empty()) ... ok // true
// or
if (not empty(v1)) ... ok // true

var=

strvar.textwidth()

Count the number of output columns required for a given source string.

return: A number

Allow wide multi-column Unicode characters that occupy more than one space in a text file or terminal screen.

Reduce combining characters to a single column. e.g. "e" followed by grave accent is multiple bytes but only occupies one output column.

Does not properly calculate all possible combining sequences of graphemes e.g. face followed by colour

let v1 = "🤡x🤡"_var.textwidth(); // 5
// or
let v2 = textwidth("🤡x🤡");

var=

strvar.textlen()

Count the number of Unicode code points in a source string.

return: A number.

let v1 = "Γιάννης"_var.textlen(); // 7
// or
let v2 = textlen("Γιάννης");

var=

strvar.fcount(sepstr)

Count the number of fields in a source string.

sepstr: The separator character or substr that delimits individual fields.

return: The count of the number of fields

This is similar to "var.count(sepstr) + 1" but it returns 0 for an empty source string.

let v1 = "aa**cc"_var.fcount("*"); // 3
// or
let v2 = fcount("aa**cc", "*");

var=

strvar.count(sepstr)

Count the number of occurrences of a given substr in a source string.

substr: The substr to count.

return: The count of the number of sepstr found.

Overlapping substrings are not counted.

let v1 = "aa**cc"_var.count("*"); // 2
// or
let v2 = count("aa**cc", "*");

if

strvar.starts(prefix)

Check if a source string starts with a given prefix (substr).

prefix: The substr to check for.

return: True if the source string starts with the given prefix.

Always returns false if suffix is "". DIFFERS from c++, javascript, python3. See contains() for more info.

if ("abc"_var.starts("ab")) ... true
// or
if (starts("abc", "ab")) ... true

if

strvar.ends(suffix)

Check if a source string ends with a given suffix (substr).

suffix: The substr to check for.

return: True if the source string ends with given suffix.

Always returns false if suffix is "". DIFFERS from c++, javascript, python3. See contains() for more info.

if ("abc"_var.ends("bc")) ... true
// or
if (ends("abc", "bc")) ... true

if

strvar.contains(substr)

Check if a given substr exists in a source string.

substr: The substr to check for.

return: True if the source string starts with, ends with or contains the given substr.

Always returns false if substr is "". DIFFERS from c++, javascript, python3. See contains() for more info.

Human logic: "" is not equal to "x" therefore x does not contain "".

Human logic: Check each item (character) in the list for equality with what I am looking for and return success if any are equal.

Programmer logic: Compare as many characters as are in the search string for presence in the list of characters and return success if there are no failures.

if ("abcd"_var.contains("bc")) ... true
// or
if (contains("abcd", "bc")) ... true

var=

strvar.index(substr, startchar1 = 1)

Find a substr in a source string.

substr: The substr to search for.

startchar1: The char position (1 based) to start the search at. The default is 1, the first char.

return: The char position (1 based) that the substr is found at or 0 if not present.

let v1 = "abcd"_var.index("bc"); // 2
// or
let v2 = index("abcd", "bc");

var=

strvar.indexn(substr, occurrence)

Find the nth occurrence of a substr in a source string.

substr: The string to search for.

return: char position (1 based) or 0 if not present.

let v1 = "abcabc"_var.indexn("bc", 2); // 5
// or
let v2 = indexn("abcabc", "bc", 2);

var=

strvar.indexr(substr, startchar1 = -1)

Find the position of substr working backwards

Start at the end and work backwards.

substr: The string to search for.

return: The char position of the substr if found, or 0 if not.

startchar1: Defaults to -1 meaning start searching from the last char. Positive start1char1 counts from the beginning of the source string and negative startchar1 counts backwards from the last char.

let v1 = "abcabc"_var.indexr("bc"); // 5
// or
let v2 = indexr("abcabc", "bc");

var=

strvar.match(regex_str, regex_options = "")

Find all matches of a given regular expression.

return: Zero or more matching substrings separated by FMs. Any groups are in VMs.

let v1 = "abc1abc2"_var.match("BC(\\d)", "i"); // "bc1]1^bc2]2"_var
// or
let v2 = match("abc1abc2", "BC(\\d)", "i");

regex_options:

l
Literal (any regex chars are treated as normal chars)
i
Case insensitive
p
ECMAScript/Perl (the default)
b
Basic POSIX (same as sed)
e
Extended POSIX
a
awk
g
grep
eg
egrep or grep -E

char ranges like a-z are locale sensitive if ECMAScript

regex_options:

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 the first match of a regular expression.

startchar1: [in] char position to start the search from

startchar1[out]: char position to start the next search from or 0 if no more matches.

return: The 1st match like match()

regex_options as for match()

var startchar1 = 1;
let v1 = "abc1abc2"_var.search("BC(\\d)", startchar1, "i"); // "bc1]1"_var // startchar1 -> 5 /// Ready for the next search
// or
startchar1 = 1;
let v2 = search("abc1abc2", "BC(\\d)", startchar1, "i");

var=

strvar.search(regex_str)

Ditto starting from first char

var=

strvar.search(regex, io startchar1)

Ditto given a rex

var=

strvar.search(regex)

Ditto starting from first char.

var=

strvar.hash(std::uint64_t modulus = 0)

Get a hash of a source string.

modulus: The result is limited to [0, modulus)

return: A 64 bit signed integer.

MurmurHash3 is used.

let v1 = "abc"_var.hash(); assert(v1 == var(6'715'211'243'465'481'821));
// or
let v2 = hash("abc");

String Conversion - Non-Mutating - Chainable
Use Function Description

var=

strvar.ucase()

Convert to upper case

let v1 = "Γιάννης"_var.ucase(); // "ΓΙΆΝΝΗΣ"
// or
let v2 = ucase("Γιάννης");

var=

strvar.lcase()

Convert to lower case

let v1 = "ΓΙΆΝΝΗΣ"_var.lcase(); // "γιάννης"
// or
let v2 = lcase("ΓΙΆΝΝΗΣ");

var=

strvar.tcase()

Convert to title case.

return: Original source string with the first letter of each word is capitalised.

let v1 = "γιάννης παππάς"_var.tcase(); // "Γιάννης Παππάς"
// or
let v2 = tcase("γιάννης παππάς");

var=

strvar.fcase()

Convert to folded case.

Case folding is the process of converting text to a case independent representation.

return: The source string standardised in a way to enable consistent indexing and searching,

https: //www.w3.org/International/wiki/Case_folding

Accents can be significant. As in French cote, coté, côte and côté.

Case folding is not locale-dependent.

let v1 = "Grüßen"_var.fcase(); // "grüssen"
// or
let v2 = tcase("Grüßen");

var=

strvar.normalize()

Replace Unicode character sequences with their standardised NFC form.

Unicode normalization is the process of converting Unicode strings to a standard form, making them binary comparable and suitable for text processing and comparison. It is an important part of Unicode text processing.

For example, Unicode character "é" can be represented by either a single Unicode character, which is Unicode Code Point (\u00E9" - Latin Small Letter E with Acute), or a combination of two Unicode code points i.e. the ASCII letter "e" and a combining acute accent (Unicode Code Point "\u0301"). Unicode NFC definition converts the pair of code points to the single code point.

Normalization is not locale-dependent.

let v1 = "cafe\u0301"_var.normalize(); // "caf\u00E9" // "café"
// or
let v2 = normalize("cafe\u0301");

var=

strvar.invert()

Simple reversible disguising of string text.

It works by treating the string as UTF8 encoded Unicode code points and inverting the first 8 bits of their Unicode Code Points.

return: A string.

invert(invert()) returns to the original text.

ASCII bytes become multibyte UTF-8 so string sizes increase.

Inverted characters remain on their original Unicode Code Page but are jumbled up.

Non-existant Unicode Code Points may be created but UTF8 encoding remains valid.

let v1 = "abc"_var.invert(); // "\xC2" "\x9E" "\xC2" "\x9D" "\xC2" "\x9C"
// or
let v2 = invert("abc");

var=

strvar.lower()

Reduce all types of field mark chars by one level.

Convert all FM to VM, VM to SM etc.

return: The converted string.

Note that subtext ST chars are not converted because they are already the lowest level.

String size remains identical.

let v1 = "a1^b2^c3"_var.lower(); // "a1]b2]c3"_var
// or
let v2 = lower("a1^b2^c3"_var);

var=

strvar.raise()

Increase all types of field mark chars by one level.

Convert all VM to FM, SM to VM etc.

return: The converted string.

The record mark char RM is not converted because it is already the highest level.

String size remains identical.

let v1 = "a1]b2]c3"_var.raise(); // "a1^b2^c3"_var
// or
let v2 = "a1]b2]c3"_var;

var=

strvar.crop()

Remove any redundant FM, VM etc. chars (Trailing FM; VM before FM etc.)

let v1 = "a1^b2]]^c3^^"_var.crop(); // "a1^b2^c3"_var
// or
let v2 = crop("a1^b2]]^c3^^"_var);

var=

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 surrounding double or single quotes.

let v1 = "'abc'"_var.unquote(); // "abc"
// or
let v2 = unquote("'abc'");

var=

strvar.trim(trimchars = " ")

Remove all leading, trailing and excessive inner bytes.

trimchars: The chars (bytes) to remove. The default is space.

let v1 = "␣␣a1␣␣b2␣c3␣␣"_var.trim(); // "a1␣b2␣c3"
// or
let v2 = trim("␣␣a1␣␣b2␣c3␣␣");

var=

strvar.trimfirst(trimchars = " ")

Ditto but only leading.

let v1 = "␣␣a1␣␣b2␣c3␣␣"_var.trimfirst(); // "a1␣␣b2␣c3␣␣"
// or
let v2 = trimfirst("␣␣a1␣␣b2␣c3␣␣");

var=

strvar.trimlast(trimchars = " ")

Ditto but only trailing.

let v1 = "␣␣a1␣␣b2␣c3␣␣"_var.trimlast(); // "␣␣a1␣␣b2␣c3"
// or
let v2 = trimlast("␣␣a1␣␣b2␣c3␣␣");

var=

strvar.trimboth(trimchars = " ")

Ditto but only leading and trailing, not inner.

let v1 = "␣␣a1␣␣b2␣c3␣␣"_var.trimboth(); // "a1␣␣b2␣c3"
// or
let v2 = trimboth("␣␣a1␣␣b2␣c3␣␣");

var=

strvar.first()

Get the first char of a string.

return: A char, or "" if empty.

Equivalent to var.substr(1,length) or var[1, length] in Pick OS

let v1 = "abc"_var.first(); // "a"
// or
let v2 = first("abc");

var=

strvar.last()

Get the last char of a string.

return: A char, or "" if empty.

Equivalent to var.substr(-1, 1) or var[-1, 1] in Pick OS

let v1 = "abc"_var.last(); // "c"
// or
let v2 = last("abc");

var=

strvar.first(length)

Get the first n chars of a source string.

length: The number of chars (bytes) to get.

return: A string of up to n chars.

Equivalent to var.substr(1, length) or var[1, length] in Pick OS

let v1 = "abc"_var.first(2); // "ab"
// or
let v2 = first("abc", 2);

var=

strvar.last(length)

Extract up to length trailing chars

Equivalent to var.substr(-length, length) or var[-length, length] in Pick OS

let v1 = "abc"_var.last(2); // "bc"
// or
let v2 = last("abc", 2);

var=

strvar.cut(length)

Remove n chars (bytes) from the source string.

length: Positive to remove first n chars or negative to remove the last n chars.

If the absolute value of length is >= the number of chars in the source string then all chars will be removed.

Equivalent to var.substr(length) or var[1, length] = "" in Pick OS

let v1 = "abcd"_var.cut(2); // "cd"
// or
let v2 = cut("abcd", 2);

var=

strvar.paste(pos1, length, replacestr)

Insert a substr at an given position after removing a given number of chars.

pos1:

0 or 1
Remove length chars from the beginning and insert at the beginning.
-1
Insert on or before the last char after removing up to length chars starting with the last char.
-2
Ditto on or before the penultimate char.
> strlen
If pos1 > length of the source string, insert after the last char.

Equivalent to var[pos1, length] = substr in Pick OS

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 chars

Equivalent to var[pos1, 0] = substr in Pick OS

let v1 = "abcd"_var.paste(2, "XYZ"); // "aXYZbcd"
// or
let v2 = paste("abcd", 2, "XYZ");

var=

strvar.prefix(insertstr)

Insert text at the beginning

Equivalent to var[0, 0] = substr in Pick OS

let v1 = "abc"_var.prefix("XYZ"); // "XYZabc"
// or
let v2 = prefix("abc", "XYZ");

var=

strvar.append(appendable, ...)

Append anything at the end of a string.

let v1 = "abc"_var.append(" is ", 10, " ok", '.'); // "abc is 10 ok."
// or
let v2 = append("abc", " is ", 10, " ok", '.');

var=

strvar.pop()

Remove one trailing char.

Equivalent to var[-1, 1] = "" in Pick OS

let v1 = "abc"_var.pop(); // "ab"
// or
let v2 = pop("abc");

var=

strvar.field(delimiter, fieldnx = 1, nfieldsx = 1)

Copy one or more consecutive fields from a string.

delimiter: A Unicode character.

fieldno: The first field is 1, the last field is -1.

return: A substring

let v1 = "aa*bb*cc"_var.field("*", 2); // "bb"
// or
let v2 = field("aa*bb*cc", "*", 2);

let v1 = "aa*bb*cc"_var.field("*", -1); // "cc"
// or
let v2 = field("aa*bb*cc", "*", -1);

var=

strvar.field2(separator, fieldno, nfields = 1)

var=

strvar.fieldstore(separator, fieldno, nfields, replacement)

fieldstore() replaces, inserts or deletes subfields in a string.

fieldno: The field number to replace or, if not 1, the field number to start at. Negative fieldno counts backwards from the last field.

nfields: The number of fields to replace or, if negative, the number of fields to delete first. Can be 0 to cause simple insertion of fields.

replacement: A string that is the replacement field or fields.

return: A modified copy of the original string.

There is no way to simply delete n fields because the replacement argument cannot be omitted, however one can achieve the same result by replacing n+1 fields with the n+1th field.

The replacement can contain multiple fields itself. If replacing n fields and the replacement contains < n fields then the remaining fields become "". Conversely, if the replacement contains more fields than are required, they are discarded.

let v1 = "aa,bb,cc,dd,ee"_var.fieldstore(",", 2, 3, "11,22"); // "aa,11,22,,ee"
// or
let v2 = fieldstore("aa,bb,cc,dd,ee", ",", 2, 3, "11,22");

If nfields is 0 then insert the replacement field(s) before fieldno

let v1 = "aa,bb,cc,dd,ee"_var.fieldstore(",", 2, 0, "11,22"); // "aa,11,22,bb,cc,dd,ee"
If nfields is negative then delete abs(n) fields before inserting whatever fields the replacement has.
let v1 = "aa,bb,cc,dd,ee"_var.fieldstore(",", 2, -2, "11"); // "aa,11,dd,ee"

If nfields exceeds the number of fields in the input then additional empty fields are added.

let v1 = "aa,bb,cc"_var.fieldstore(",", 6, 2, "11"); // "aa,bb,cc,,,11,"

var=

strvar.substr(pos1, length)

substr version 1.

Copy a substr of length chars from a given a starting char position.

return: A substr or "".

pos1: The char position to start at. If negative then start from a position counting backwards from the last char

length: The number of chars to copy. If negative then copy backwards. This reverses the order of the chars in the returned substr.

Equivalent to var[start, length] in Pick OS

Not Unicode friendly.

let v1 = "abcd"_var.substr(2, 2); // "bc"
// or
let v2 = substr("abcd", 2, 2);

If pos1 is negative then start counting backwards from the last char

let v1 = "abcd"_var.substr(-3, 2); // "bc"
// or
let v2 = substr("abcd", -3, 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); // "cb"

var=

strvar.b(pos1, length)

Abbreviated alias of substr version 1.

var=

strvar.substr(pos1)

substr version 2.

Copy a substr from a given char position up to the end of the source string

return: A substr or "".

pos1: The char position to start at. If negative then start from a position counting backwards from the last char

Equivalent to var[pos1, 9999999] in Pick OS

Partially Unicode friendly but pos1 is in chars.

let v1 = "abcd"_var.substr(2); // "bcd"
// or
let v2 = substr("abcd", 2);

var=

strvar.b(pos1)

Shorthand alias of substr version 2.

var=

strvar.substr(pos1, delimiterchars, out pos2)

substr version 3.

Copy a substr from a given char position up to (but excluding) any one of some given delimiter chars

return: A substr or "".

pos1: [in] The position of the first char to copy. Negative positions count backwards from the last char of the string.

pos2[out]: The position of the next delimiter char, or one char position after the end of the source string if no subsequent delimiter chars are found.

COL2: Is a predefined variable that can be used for pos2 instead of declaring a variable.

An empty string may be returned if pos1 [in] points to one of the delimiter chars or points beyond the end of the source string.

Equivalent to var[pos1, ",."] in Pick OS (non-numeric length).

Works with any encoding including UTF8 for the source string but the delimiter chars are bytes.

Add 1 to pos2 to skip over the next delimiter char to copy the next substr

Works with any encoding including UTF8 for the source string but the delimiter chars are bytes.

This function is similar to std::string::find_first_of but that function only returns pos2.

var pos1 = 4;
let v1 = "12,45 78"_var.substr(pos1, ", ", COL2);  // v1 -> "45" // COL2 -> 6 // 6 is the position of the next delimiter char found.
// or
let v2 = substr("12,45 78", COL2 + 1, ", ", COL2); // v2 -> "78" // COL2 -> 9 // 9 is one after the end of the string meaning that none of the delimiter chars were found.

var=

strvar.b(pos1, delimiterchars, out pos2)

Shorthand alias of substr version 3.

var=

strvar.substr2(io pos1, out delimiterno)

substr version 4.

Copy a substr from a given char position up to (but excluding) the next field mark char (RM, FM, VM, SM, TM, ST).

return: A substr or "".

pos1: [in] The position of the first char to copy. Negative positions count backwards from the last char of the string.

pos1[out]: The position of the first char of the next substr after whatever field mark char is found, or one char position after the end of the source string if no subsequent field mark char is found.

field_mark_no[out]: A number (1-6) indicating which of the standard field mark chars was found, or 0 if not.

An empty string may be returned if the pos1 [in] points to one of the field marks or beyond the end of the source string.

pos1 [out] is correctly positioned to copy the next substr.

Works with any encoding including UTF8. Was called "remove" in Pick OS.

The equivalent in Pick OS was the statement "Remove variable From string At column Setting flag"

This function is valuable for high performance processing of dynamic arrays.

It is notably used in "list" to print parallel columns of mixed combinations of multivalues/subvalues and text marks correctly lined up mv to mv, sv to sv, tm to tm even when particular values, subvalues and text fragments are missing from particular columns.

It is similar to version 3 of substr - substr(pos1, delimiterchars, pos2) except that in this version the delimiter chars are hard coded as the standard field mark chars (RM, FM, VM, SM, TM, ST) and it returns the first char position of the next substr, not the char position of the next field mark char.

var pos1 = 4, field_mark_no;
let v1 = "12^45^78"_var.substr2(pos1, field_mark_no);  // "45" // pos1 -> 7 // field_mark_no -> 2 // field_mark_no 2 means that a FM was found.
// or
let v2 = substr2("12^45^78"_var, pos1, field_mark_no); // "78" // pos1 -> 9 // field_mark_no -> 0 // field_mark_no 0 means that none of the standard field marks were found.

var=

strvar.b2(io pos1, out field_mark_no)

Shorthand alias of substr version 4.

var=

strvar.convert(fromchars, tochars)

Convert or delete chars one for one to other chars

from_chars: chars to convert. If longer than to_chars then delete those characters instead of converting them.

to_chars: chars to convert to

Not UTF8 compatible.

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 one 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, replacement_str)

Replace substrings using a regular expression.

regex: A regular expression created by rex() or _rex.

replacement_str: A literal to replace all matched substrings.

The replacement string can include the following special replacement patterns:

Pattern

$$
Inserts a "$".
$&
Inserts the matched substring. Equivalent to $0.
$`
Inserts the portion of the string that precedes the matched substring.
$'
Inserts the portion of the string that follows the matched substring.
$n
Inserts the nth (1-indexed) capturing group where n is a positive integer less than 100.

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.replace(regex, ReplacementFunction auto repl_func)

Replace substrings using a regular expression and a custom function.

Allow complex string conversions.

repl_func: A function with arguments (in match_str) that returns a var to replace match_str. May be an inline anonymous lambda function (capturing or non-capturing).

e.g. [](auto match_str) {return match_str;} // Does nothing.

match_str: Text of a single match. If regex groups are used, match_str.f(1, 1) is the whole match, match_str.f(1, 2) is the first group, etc.

// Decode hex escape codes.
let v1 = R"(--\0x3B--\0x2F--)";                                 // Hex escape codes.
let v2 = v1.replace(
    R"(\\0x[0-9a-fA-F]{2,2})"_rex,                              // Find \0xFF.
    [](auto match_str) {return match_str.cut(3).iconv("HEX");}  // Decode to a char.
);
assert(v2 == "--;--/--");

// Reformat dates using groups.
let v3 = "Date: 03-15-2025";
let v4 = v3.replace(
    R"((\d{2})-(\d{2})-(\d{4}))"_rex,
    [](auto match_str) {return match_str.f(1, 4) ^ "-" ^ match_str.f(1, 2) ^ "-" ^ match_str.f(1, 3);}
);
assert(v4 == "Date: 2025-03-15");

var=

strvar.unique()

Remove duplicate fields, values or subvalues.

From a dynamic array.

let v1 = "a1^b2^a1^c2"_var.unique(); // "a1^b2^c2"_var
// or
let v2 = unique("a1^b2^a1^c2"_var);

var=

strvar.sort(delimiter = FM)

Reorder fields, values or subvalues.

In a dynamic array.

Numeric data:

let v1 = "20^10^2^1^1.1"_var.sort(); // "1^1.1^2^10^20"_var
// or
let v2 = sort("20^10^2^1^1.1"_var);

Alphabetic data:

let v1 = "b1^a1^c20^c10^c2^c1^b2"_var.sort(); // "a1^b1^b2^c1^c10^c2^c20"_var
// or
let v2 = sort("b1^a1^c20^c10^c2^c1^b2"_var);

var=

strvar.reverse(delimiter = FM)

Reorder fields in an FM or VM etc. separated list in descending order

let v1 = "20^10^2^1^1.1"_var.reverse(); // "1.1^1^2^10^20"_var
// or
let v2 = reverse("20^10^2^1^1.1"_var);

var=

strvar.randomize(delimiter = FM)

Randomise the order of fields in an FM, VM separated list

let v1 = "20^10^2^1^1.1"_var.randomize(); /// e.g. "2^1^20^1.1^10" (random order depending on initrand())
// or
let v2 = randomize("20^10^2^1^1.1"_var);

var=

strvar.parse(char sepchar = ' ')

Split a delimited string into a dynamic array.

Replace separator chars with FM chars except inside double or single quotes and ignoring escaped quotes \" \'

return: A dynamic array

Can be used to process CSV data.

let v1 = "abc,\"def,\"123\" fgh\",12.34"_var.parse(','); // "abc^\"def,\"123\" fgh\"^12.34"_var
// or
let v2 = parse("abc,\"def,\"123\" fgh\",12.34", ',');

dim=

strvar.split(delimiter = FM)

Split a delimited string into a dim array.

Delimiter: Can be multibyte Unicode.

return: A dim array.

dim d1 = "a^b^c"_var.split(); // A dimensioned array with three elements (vars)
// or
dim d2 = split("a^b^c"_var);

var=

strvar.paste(pos1, length, replacestr)

var=

strvar.fieldstore(delimiter, fieldno, nfields, replacement)

String Mutation - Standalone Commands
Use Function Description

strvar.ucaser()

To upper case

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

var v1 = "abc";
v1.ucaser(); // "ABC"
// or
ucaser(v1);

strvar.lcaser()

strvar.tcaser()

strvar.fcaser()

strvar.normalizer()

strvar.inverter()

strvar.quoter()

strvar.squoter()

strvar.unquoter()

strvar.lowerer()

strvar.raiser()

strvar.cropper()

strvar.trimmer(trimchars = " ")

strvar.trimmerfirst(trimchars = " ")

strvar.trimmerlast(trimchars = " ")

strvar.trimmerboth(trimchars = " ")

strvar.firster()

strvar.laster()

strvar.firster(length)

strvar.laster(length)

strvar.cutter(length)

strvar.paster(pos1, length, insertstr)

strvar.paster(pos1, insertstr)

strvar.prefixer(insertstr)

strvar.appender(appendable, ...)

strvar.popper()

strvar.fieldstorer(delimiter, fieldno, nfields, replacement)

strvar.substrer(pos1, length)

strvar.substrer(pos1)

strvar.converter(from_chars, to_chars)

strvar.textconverter(from_characters, to_characters)

strvar.replacer(regex, tostr)

strvar.replacer(regex, ReplacementFunction auto repl_func)

strvar.replacer(fromstr, tostr)

strvar.uniquer()

strvar.sorter(delimiter = FM)

strvar.reverser(delimiter = FM)

strvar.randomizer(delimiter = FM)

strvar.parser(char sepchar = ' ')

I/O Conversion
Use Function Description

var=

var.oconv(convstr)

Convert internal data to output external display format.

convstr: A conversion code or pattern. See ICONV/OCONV PATTERNS

return: The data in external display format or, if the data is invalid and cannot converted, most conversions return the original data UNCONVERTED.

throw: VarNotImplemented if convstr is invalid

let v1 = var(30123).oconv("D/E"); // "21/06/2050"
// or
let v2 = oconv(30123, "D/E");

var=

var.iconv(convstr)

Convert external data to internal format.

convstr: A conversion code or pattern. See ICONV/OCONV PATTERNS

return: The data in internal format or, if the data is invalid and cannot be converted, most conversions return the EMPTY STRING ""

throw: VarNotImplemented if convstr is invalid

let v1 = "21 JUN 2050"_var.iconv("D/E"); // 30123
// or
let v2 = iconv("21 JUN 2050", "D/E");

var=

var.format(fmt_str, args, ...)

Classic format function in printf style

vars can be formatted either with C++ format codes e.g. {:_>8.2f}

or with exodus oconv codes e.g. {::MD20P|R(_)#8} as in the below example.

let v1 = var(12.345).format("'{:_>8.2f}'"); // "'___12.35'"
let v2 = var(12.345).format("'{::MD20P|R(_)#8}'");
// or
var v3 = format("'{:_>8.2f}'", var(12.345)); // "'___12.35'"
var v4 = format("'{::MD20P|R(_)#8}'", var(12.345));

var=

strvar.from_codepage(codepage)

Convert from codepage encoded text to UTF-8 encoded exodus text

codepage: e.g. Codepage "CP1124" (Ukrainian).

Use Linux command "iconv -l" for a 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)

Convert to codepage encoded text from exodus UTF-8 encoded text

let v1 = "Є"_var.to_codepage("CP1124").oconv("HEX"); // "A4"
// or
let v2 = to_codepage("Є", "CP1124").oconv("HEX");

Dynamic Array Functions
Use 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"
//
// For brevity the function alias "f()" (standing for "field") is normally used instead of "extract()" as follows:
var v3 = v1.f(2, 2);

var=

strvar.update(fieldno, valueno, subvalueno, replacement)

Update (replace or insert) a specific subvalue in a dynamic array.

Same as var.updater() function but returns a new string instead of updating a variable in place. Rarely used.

"update()" was called "replace()" in Pick OS/Basic.

var=

strvar.update(fieldno, valueno, replacement)

Update (replace or insert) a specific value in a dynamic array.

var=

strvar.update(fieldno, replacement)

Update (replace or insert) a specific field a dynamic array.

var=

strvar.insert(fieldno, valueno, subvalueno, insertion)

Insert a subvalue in a dynamic array.

Same as var.inserter() function but returns a new string instead of updating a variable in place.

var=

strvar.insert(fieldno, valueno, insertion)

Insert a value in a dynamic array.

var=

strvar.insert(fieldno, insertion)

Insert a field in a dynamic array.

var=

strvar.remove(fieldno, valueno = 0, subvalueno = 0)

Remove a field, value or subvalue from a dynamic array.

Same as var.remover() function but returns a new string instead of updating a variable in place.

"remove()" was called "delete()" in Pick OS/Basic.

Dynamic Array Filters
Use Function Description

var=

strvar.sum()

Sum up multiple values in a dynamic array.

Whatever is the lowest level is summed up into a higher level.

let v1 = "1]2]3^4]5]6"_var.sum(); // "6^15"_var
// or
let v2 = sum("1]2]3^4]5]6"_var);

var=

strvar.sumall()

Sum up everything in a dynamic array.

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(delimiter)

Sum all fields using a given delimiter.

let v1 = "10,20,30"_var.sum(","); // 60
// or
let v2 = sum("10,20,30", ",");

var=

strvar.stddev()

Calculate basic statistics include stddev.

return: An FM delimited string containing n, tot, min, max, tot, mean and stddev

strvar: A dynamic array containing numbers using any field, value or subvalue mark delimiters.

let v1 = "-11.2^0^11.5^12^13.9^14"_var.stddev(); // "6^40.2^-11.2^14^6.7^9.32344714506"_var
// or
let v2 = stddev("-11.2^0^11.5^12^13.9^14"_var);

var=

strvar.mv(opcode, var2)

Binary ops on parallel multivalues

opcode:

+
Addition
-
Subtraction
Multiplication
/
Division

let v1 = "10]20]30"_var.mv("+","2]3]4"_var); // "12]23]34"_var

Dynamic Array Mutators Standalone Commands
Use Function Description

strvar.updater(fieldno, replacement)

Replace a specific field in a dynamic array

var v1 = "f1^v1]v2}s2}s3^f3"_var;
v1.updater(2, "X"); // "f1^X^f3"_var
// or
v1(2) = "X"; /// Easiest.
// or
updater(v1, 2, "X");

strvar.updater(fieldno, valueno, replacement)

Replace a specific value in a dynamic array.

var v1 = "f1^v1]v2}s2}s3^f3"_var;
v1.updater(2, 2, "X"); // "f1^v1]X^f3"_var
// or
v1(2, 2) = "X"; /// Easiest.
// or
updater(v1, 2, 2, "X");

strvar.updater(fieldno, valueno, subvalueno, replacement)

Replace a specific subvalue in a dynamic array.

var v1 = "f1^v1]v2}s2}s3^f3"_var;
v1.updater(2, 2, 2, "X"); // "f1^v1]v2}X}s3^f3"_var
// or
v1(2, 2, 2) = "X"; /// Easiest.
// or
updater(v1, 2, 2, 2, "X");

strvar.inserter(fieldno, insertion)

Insert a specific field in a dynamic array

All other fields are moved up.

var v1 = "f1^v1]v2}s2}s3^f3"_var;
v1.inserter(2, "X"); // "f1^X^v1]v2}s2}s3^f3"_var
// or
inserter(v1, 2, "X");

strvar.inserter(fieldno, valueno, insertion)

Insert a specific value in a dynamic array.

All other values are moved up.

var v1 = "f1^v1]v2}s2}s3^f3"_var;
v1.inserter(2, 2, "X"); // "f1^v1]X]v2}s2}s3^f3"_var
// or
inserter(v1, 2, 2, "X");

strvar.inserter(fieldno, valueno, subvalueno, insertion)

Insert a specific subvalue in a dynamic array.

All other subvalues are moved up.

var v1 = "f1^v1]v2}s2}s3^f3"_var;
v1.inserter(2, 2, 2, "X"); // "f1^v1]v2}X}s2}s3^f3"_var
// or
v1.inserter(2, 2, 2, "X");

strvar.remover(fieldno, valueno = 0, subvalueno = 0)

Remove a specific field, value, or subvalue from a dynamic array.

All other fields, values, or subvalues are moved down.

var v1 = "f1^v1]v2}s2}s3^f3"_var;
v1.remover(2, 2); // "f1^v1^f3"_var
// or
remover(v1, 2, 2);

Use Function Description

var=

strvar.locate(substr)

locate substr in dynamic array

Search unordered fields, values and/or subvalues.

With only the substr argument provided, locate searches regardless of the field mark delimiters present.

return: The field, value or subvalue number if found or 0 if not. Fields are counted regardless of delimiter.

Searching for empty fields, values etc. (i.e. "") will work. Locating "" in "]yy" will return 1, in "xx]]zz" 2, and in "xx]yy]" 3, however, locating "" in "xx" will return 0 because there is conceptually no empty value in "xx". Locate "" in "" will return 1.

if ("UK^US^UA"_var.locate("US")) ... ok // 2
// or
if (locate("US", "UK^US^UA"_var)) ... ok

if

strvar.locate(substr, out valueno)

locate substr in values.

Search unordered VM delimited string.

valueno[out]: Value number if found or the max value number + 1 if not. If not found then valueno [out] is suitable for creating a new value.

return: True if found or False if not.

var valueno;
if ("UK]US]UA"_var.locate("US", valueno)) ... ok // valueno -> 2
// or
if (locate("US", "UK]US]UA"_var,valueno)) ... ok

if

strvar.locate(substr, out num, fieldno, valueno = 0)

locate substr in dynamic array.

Search in an unordered dynamic array.

fieldno: If fieldno is non-zero then search the specified field number otherwise, if fieldno is 0, search using FM as delimiter.

valueno: If provided, search the specified value number for a subvalue.

num[out]: If found, the field, value or subvalue number where it was found. If not found, the max field, value or subvalue number + 1. If not found then num [out] is suitable for creating a new field, value or subvalue.

return: True if found or False if not.

var num;
if ("f1^f2v1]f2v2]s1}s2}s3}s4^f3^f4"_var.locate("s4", num, 2, 3)) ... ok // num -> 4 // Return true

if

strvar.locateby(ordercode, substr, out valueno)

locate substr in ordered dynamic array

locateby() without fieldno or valueno arguments, searches ordered values separated by VM chars.

Data must already be in the correct order for searching to work properly.

ordercode:

AL
Ascending - Left Justified (Alphabetic)
DL
Descending - Left Justified (Alphabetic)
AR
Ascending - Right Justified (Numeric/Natural)
DR
Descending - Right Justified (Numeric/Natural)

return: True if found, otherwise false.

valueno[out]: Either the value no found or the correct value no for inserting the substr

var valueno; if ("aaa]bbb]ccc"_var.locateby("AL", "bb", valueno)) ... // valueno -> 2 // Return false and valueno = where it could be correctly inserted.

if

strvar.locateby(ordercode, substr, out num, fieldno, valueno = 0)

locate substr in ordered dynamic array

locateby() with fieldno and/or valueno arguments, searches fields if fieldno is 0, or values in a specific fieldno, or subvalues in a specific valueno.

For more info, see locateby() without fieldno or valueno arguments.

var num;
if ("f1^f2^aaa]bbb]ccc^f4"_var.locateby("AL", "bb", num, 3)) ... // num -> 2 // return false and where it could be correctly inserted.

if

strvar.locateusing(usingchar, substr)

locate substr using any delimiter.

if ("AB,EF,CD"_var.locateusing(",", "EF")) ... ok

if

strvar.locateusing(usingchar, substr, out num, fieldno = 0, valueno = 0, subvalueno = 0)

locate substr in dynamic array using any delimiter

Search in a specific field, value or subvalue.

num[out]: If found, the number where found, otherwise the maximum number of delimited fields + 1.

return: True if found and False if not.

This is similar to the main locate command but the delimiter char can be specified e.g. a comma or TM etc.

var num;
if ("f1^f2^f3c1,f3c2,f3c3^f4"_var.locateusing(",", "f3c2", num, 3)) ... ok // num -> 2 // Return true

if

strvar.locatebyusing(ordercode, usingchar, substr, out num, fieldno = 0, valueno = 0, subvalueno = 0)

locatebyusing() supports all the locate features in a single function.

Database Access
Use Function Description

if

dbconn.connect(conninfo = "")

Establish a connection to a database.

conninfo: The DB connection string parameters are merged from the following places in descending priority.

  1. Provided in connect()'s conninfo argument. See the last option. 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.

dbconn[out]: Becomes a reference or handle for future functions that require a connection argument.

For all the various DB function calls, the dbconn or operative var can be either:

  • A DB connection created with dbconnect().
  • A file var created with open().
  • Any var. A default connection will be established on the fly.

var dbconn = "exodus";
if (not dbconn.connect("dbname=exodus user=exodus password=somesillysecret")) ...;
// or
if (not connect()) ...
// or
if (not connect("exodus")) ...

if

dbconn.attach(filenames)

Attach filename(s) to a specific DB connection.

Any following use of the given filename(s) without specifying a connection will be directed to the specified connection until process termination.

It is not necessary to attach files before opening them but the act of opening them also attaches them.

The files must exist in the specified connection.

Attachments can changed by calling attach() or open() on a different connection or they can be removed by calling detach().

dbconn: The connection to which the filename(s) should be attached. Defaults to the default connection.

filenames: FM separated list.

return: False if any filename does not exist and cannot be opened on the given connection. All filenames that can be opened on the connection are attached even if some cannot.

Internally, attach merely opens each filename on the given connection causing them to be added to an internal cache.

var dbconn = "exodus";
let filenames = "xo_clients^dict.xo_clients"_var;
if (dbconn.attach(filenames)) ... ok
// or
if (attach(filenames)) ... ok

dbconn.detach(filenames)

Remove files from the internal cache created by previous open() and attach() calls.

filenames: FM separated list.

if

dbconn.begintrans()

Begin a DB transaction.

return:

True
Successfully begun.
False
DB refused. See lasterror() for info.

var dbconn = "exodus";
if (not dbconn.begintrans()) ...
// or
if (not begintrans()) ...

if

dbconn.statustrans()

Check if a DB transaction is in progress.

return: True or False.

var dbconn = "exodus";
if (dbconn.statustrans()) ... ok
// or
if (statustrans()) ... ok

if

dbconn.rollbacktrans()

Rollback a DB transaction.

return:

True
Successfully rolled back or there was no transaction in progress.
False
DB refused. See lasterror() for info.

var dbconn = "exodus";
if (dbconn.rollbacktrans()) ... ok
// or
if (rollbacktrans()) ... ok

if

dbconn.committrans()

Commit a DB transaction.

return:

True
Successfully committed or there was no transaction in progress.
False
DB refused. See lasterror() for info.

var dbconn = "exodus";
if (dbconn.committrans()) ... ok
// or
if (committrans()) ... ok

if

dbconn.sqlexec(sqlcmd)

Execute an sql command.

return:

True
Successfully executed.
False
DB refused. See lasterror() for info.

var dbconn = "exodus";
if (dbconn.sqlexec("select 1")) ... ok
// or
if (sqlexec("select 1")) ... ok

if

dbconn.sqlexec(sqlcmd, io response)

Execute an SQL command and capture the response.

return:

True
Successfully executed.
False
DB refused. See lasterror() for info.

response: Any rows and columns returned are separated by RM and FM respectively. The first row is the column names.

It is *ecommended* that you do not use sql directly unless you must, perhaps to manage or configure a database.

var dbconn = "exodus";
let sqlcmd = "select 'xxx' as col1, 'yyy' as col2";
var response;
if (dbconn.sqlexec(sqlcmd, response)) ... ok // response -> "col1^col2\x1fxxx^yyy"_var /// \x1f is the Record Mark (RM) char. The backtick char is used here by gendoc to deliminate source code.
// or
if (sqlexec(sqlcmd, response)) ... ok

dbconn.disconnect()

Close a DB connection

Free process resources both locally and in the database server.

var dbconn = "exodus";
dbconn.disconnect();
// or
disconnect();

dbconn.disconnectall()

Close all DB connections

Free process resources both locally and in the database server(s).

All connections are closed automatically when a process terminates.

var dbconn = "exodus";
dbconn.disconnectall();
// or
disconnectall();

var=

var::lasterror()

return: The last OS or DB error message.

var v1 = var::lasterror();
// or
var v2 = lasterror();

dbconn.setlasterror(msg)

Set the lasterror() message.

var::loglasterror(source = "")

Log the last OS or DB error message.

Output: To stdlog

Prefix the output with source if provided.

var::loglasterror("main:");
// or
loglasterror("main:");

Database Management
Use Function Description

if

dbconn.dbcreate(new_dbname, old_dbname = "")

Create a named database on a particular connection.

Optionally copies an existing database from the same connection

return: True or False. See lasterror() for errors.

  • Target database must not already exist.
  • Source database must exist on the same connection.
  • Source database cannot have any current connections.

var dbconn = "exodus";
if (not dbdelete("xo_gendoc_testdb")) {}; // Cleanup first
if (dbconn.dbcreate("xo_gendoc_testdb")) ... ok
// or
if (dbcreate("xo_gendoc_testdb")) ...

if

dbconn.dbcopy(from_dbname, to_dbname)

Create a named database as a copy of an existing database.

return: True or False. See lasterror() for errors.

  • Target database must not already exist.
  • Source database must exist on the same connection.
  • Source database cannot have any current connections.

var dbconn = "exodus";
if (not dbdelete("xo_gendoc_testdb2")) {}; // Cleanup first
if (dbconn.dbcopy("xo_gendoc_testdb", "xo_gendoc_testdb2")) ... ok
// or
if (dbcopy("xo_gendoc_testdb", "xo_gendoc_testdb2")) ...

var=

dbconn.dblist()

Get a list of available databases.

A list for a given connection or the default connection.

return: An FM delimited list.

var dbconn = "exodus";
let v1 = dbconn.dblist();
// or
let v2 = dblist();

if

dbconn.dbdelete(dbname)

Delete (drop) a named database.

return: True or False. See lasterror() for errors.

  • Database does not exist
  • Database has active connections.

var dbconn = "exodus";
if (dbconn.dbdelete("xo_gendoc_testdb2")) ... ok
// or
if (dbdelete("xo_gendoc_testdb2")) ...

if

dbconn.createfile(filename)

Create a named DB file.

filenames ending with "_temp" only last until the connection is closed.

return: True or False. See lasterror() for errors.

  • Filename is invalid.
  • Filename already exists.

let filename = "xo_gendoc_temp", dbconn = "exodus";
if (dbconn.createfile(filename)) ... ok
// or
if (createfile(filename)) ...

if

dbconn.renamefile(filename, newfilename)

Rename a DB file.

return: True or False. See lasterror() for errors.

  • source filename does not exist.
  • newfilename is invalid.
  • newfilename already exists.

let dbconn = "exodus", filename = "xo_gendoc_temp", new_filename = "xo_gendoc_temp2";
if (dbconn.renamefile(filename, new_filename)) ... ok
// or
if (renamefile(filename, new_filename)) ...

var=

dbconn.listfiles()

Get a list of all files in a database.

return: An FM separated list.

var dbconn = "exodus";
if (not dbconn.listfiles()) ...
// or
if (not listfiles()) ...

if

dbconn.clearfile(filename)

Delete all records in a DB file.

return: True or False. See lasterror() for errors.

  • filename does not exist.

let dbconn = "exodus", filename = "xo_gendoc_temp2";
if (not dbconn.clearfile(filename)) ...
// or
if (not clearfile(filename)) ...

if

dbconn.deletefile(filename)

Delete a DB file.

return: True or False. See lasterror() for errors.

  • filename does not exist.

let dbconn = "exodus", filename = "xo_gendoc_temp2";
if (dbconn.deletefile(filename)) ... ok
// or
if (deletefile(filename)) ...

var=

conn_or_file.reccount(filename = "")

Get the approx number of records in a DB file.

Might return -1 if not known.

Not very accurate inside transactions.

return: An approximate number.

let dbconn = "exodus", filename = "xo_clients";
var nrecs1 = dbconn.reccount(filename);
// or
var nrecs2 = reccount(filename);

if

conn_or_file.flushindex(filename = "")

Call the DB maintenance function.

For one file or all files.

Ensure that reccount() function is reasonably accurate.

Despite the name, this doesnt flush any index.

return: True or False. See lasterror() for errors.

  • Cannot perform maintenance while a transaction is active.
Database File I/O
Use Function Description

if

file.open(dbfilename, dbconn = "")

Open a DB file.

To a var which can be used in subsequent DB function calls to access a specific file using a specific connection.

dbconn: If dbconn is *not* specified, and the filename is present in an internal cache of filenames and connections created by previous calls to open() or attach() then open() returns true. If it is not present in the cache then the default connection will be checked.

return: See lasterror().

True
The filename was present in the cache OR the DB connection reports that the file is present.
False
The DB connection reports that the file does not exist.

var file, filename = "xo_clients";
if (not file.open(filename)) ...
// or
if (not open(filename to file)) ...

file.close()

Close a DB file.

Does nothing currently since database file vars consume no resources

var file = "xo_clients";
file.close();
// or
close(file);

if

file.createindex(fieldname, dictfile = "")

Create a secondary index.

For a given DB file and field name.

The fieldname must exist in a dictionary file. The default dictionary is "dict." ^ filename.

return: False if the index cannot be created for any reason. See lasterror().

  • 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 = "xo_clients", fieldname = "DATE_CREATED";
if (not deleteindex("xo_clients", "DATE_CREATED")) {}; // Cleanup first
if (filename.createindex(fieldname)) ... ok
// or
if (createindex(filename, fieldname)) ...

var=

file|dbconn.listindex(file_or_filename = "", fieldname = "")

List secondary indexes.

In a database or for a DB file.

return: An FM separated list.

  • DB file or fieldname does not exist.

var dbconn = "exodus";
if (dbconn.listindex()) ... ok // include "xo_clients__date_created"
// or
if (listindex()) ... ok

if

file.deleteindex(fieldname)

Delete a secondary index.

For a DB file and field name.

return: False if the index cannot be deleted for any reason. See lasterror().

  • File does not exist
  • Index does not already exists

var file = "xo_clients", fieldname = "DATE_CREATED";
if (file.deleteindex(fieldname)) ... ok
// or
if (deleteindex(file, fieldname)) ...

var=

file.lock(key)

Place a metaphorical DB lock.

On a particular record given a DB file and key.

This is a advisory lock, not a physical lock, since it makes no restriction on the access or modification of data by other connections.

Neither the DB file nor the record key need to actually exist since a lock is just a hash of the DB file name and key combined.

If another connection attempts to place an identical lock on the same database it will be denied.

Locks can be removed by unlock() or unlockall() or will be automatically removed at the end of a transaction or when the connection is closed.

If the same process attempts to place an identical lock more than once it may be denied (if not in a transaction) or succeed but be ignored (if in a transaction).

Locks can be used to avoid processing a transaction simultaneously with another connection only to have one of them fail due to mutually updating the same records.

Returns:

0
Failure: Another connection has already placed the same lock.
""
Failure: The lock has already been placed.
1
Success: A new lock has been placed.
2
Success: The lock has already been placed and the connection is in a transaction.

var file = "xo_clients", key = "1000";
if (file.lock(key)) ... ok
// or
if (lock(file, key)) ...

if

file.unlock(key)

Remove a DB lock.

A lock placed by the lock function.

return: True or False. See lasterror().

  • Lock cannot be removed while in a transaction.
  • Lock is not present in the connection.

var file = "xo_clients", key = "1000";
if (file.unlock(key)) ... ok
// or
if (unlock(file, key)) ...

if

file.unlockall()

Remove all DB locks.

All locks placed by the lock function in the specified connection.

return: True or False. See lasterror().

  • Locks cannot be removed while in a transaction.

var dbconn = "exodus";
if (not dbconn.unlockall()) ...
// or
if (not unlockall(dbconn)) ...

record.write(file, key)

Write a record into a DB file.

Given a unique primary key, either inserts a new record or updates an existing record.

return: Nothing since writes always succeed.

throw: VarDBException if the file does not exist.

Any memory cached record is deleted.

let record = "Client GD^G^20855^30000^1001.00^20855.76539"_var;
let file = "xo_clients", key = "GD001";
//if (not "xo_clients"_var.deleterecord("GD001")) {}; // Cleanup first
record.write(file, key);
// or
write(record on file, key);

if

record.read(file, key)

Read a record from a DB file.

Given a unique primary key.

file: A DB filename or a var opened to a DB file.

key: The key of the record to be read.

return: False if the key doesnt exist

var: Contains the record if it exists or is unassigned if not.

A special case of the key being "%RECORDS%" results in a fictitious "record" being returned as an FM separated list of all the keys in the DB file up to a maximum size of 4Mib, sorted in natural order.

var record;
let file = "xo_clients", key = "GD001";
if (not record.read(file, key)) ... // record -> "Client GD^G^20855^30000^1001.00^20855.76539"_var
// or
if (not read(record from file, key)) ...

if

file.deleterecord(key)

Delete a record from a DB file.

Given a unique primary key.

return: True or False.

  • Key doesnt exist.

Any memory cached record is deleted.

deleterecord(in file), a one argument free function, is available that deletes multiple records using the currently active select list.

let file = "xo_clients", key = "GD001";
if (file.deleterecord(key)) ... ok
// or
//if (deleterecord(file, key)) ...

if

record.insertrecord(file, key)

Insert a new record in a DB file.

Given a unique primary key.

return: True or False.

  • Key already exists

Any memory cached record is deleted.

let record = "Client GD^G^20855^30000^1001.00^20855.76539"_var;
let file = "xo_clients", key = "GD001";
if (record.insertrecord(file, key)) ... ok
// or
if (insertrecord(record on file, key)) ...

if

record.updaterecord(file, key)

Update an existing record in a DB file.

Given a unique primary key.

return: True or False.

  • Key does not exists

Any memory cached record is deleted.

let record = "Client GD^G^20855^30000^1001.00^20855.76539"_var;
let file = "xo_clients", key = "GD001";
if (not record.updaterecord(file, key)) ...
// or
if (not updaterecord(record on file, key)) ...

if

record.updatekey(key, newkey)

Update the key of an existing record in a DB file.

Given two unique primary keys.

return: True or False.

  • Key does not exists
  • New key already exists.

Any memory cached records of either key are deleted.

let file = "xo_clients", key = "GD001", newkey = "GD002";
if (not file.updatekey(key, newkey)) ...
// or
if (not updatekey(file, newkey, key)) ... // Reverse the above change.

if

strvar.readf(file, key, fieldno)

Read a field from a DB file record.

Same as read() but only returns a specific field number from the record.

fieldno: The field number to return from the DB record.

return: A string var.

var field, file = "xo_clients", key = "GD001", fieldno = 2;
if (not field.readf(file, key, fieldno)) ... // field -> "G"
// or
if (not readf(field from file, key, fieldno)) ...

strvar.writef(file, key, fieldno)

Write a field to a DB file record.

Same as write() but only writes to a specific field number in the record.

var field = "f3", file = "xo_clients", key = "1000", fieldno = 3;
field.writef(file, key, fieldno);
// or
writef(field on file, key, fieldno);

record.writec(file, key)

Write a record and key into a memory cached "DB file".

The actual database file is NOT updated.

writec() either updates an existing cache record if the key already exists or otherwise inserts a new record into the cache.

It always succeeds so no result code is returned.

Neither the DB file nor the record key need to actually exist in the actual DB.

let record = "Client XD^X^20855^30000^1001.00^20855.76539"_var;
let file = "xo_clients", key = "XD001";
record.writec(file, key);
// or
writec(record on file, key);

if

record.readc(file, key)

Read a DB record first looking in a memory cached "DB file".

Same as "read() but first reads from a memory cache held per connection.

  1. Tries to read from a memory cache. Returns true if successful.

2a. Tries to read from the actual DB file and returns false if unsuccessful.

2b. Writes the record and key to the memory cache and returns true.

Cached DB file data lives in exodus process memory and is lost when the process terminates or clearcache() is called.

var record;
let file = "xo_clients", key = "XD001";
if (record.readc(file, key)) ... ok
// or
if (readc(record from file, key)) ... ok

// Verify not in actual database file by using read() not readc()
if (read(record from file, key)) abort("Error: " ^ key ^ " should not be in the actual database file"); // error

if

dbfile.deletec(key)

Delete a record from a memory cached "DB file".

The actual database file is NOT updated.

return: False if the key doesnt exist

var file = "xo_clients", key = "XD001";
if (file.deletec(key)) ... ok
// or
if (deletec(file, key)) ...

dbconn.clearcache()

Clear the "DB file" memory cache.

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

let dbconn = "exodus";
dbconn.clearcache();
// or
clearcache(dbconn);

var=

strvar.xlate(filename, fieldno, mode)

Read a field given filename, key and field number or name.

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 named columns, functions and multivalued data.

strvar: The primary key to lookup a field in a given file and field no or field name.

filename: The DB file in which to look up data.

If var key is multivalued then a multivalued field is returned.

fieldno: Which field of the record to return.

nn
Field number nn
0
The key.
""
The whole record.

mode: If the record does not exist.

"X"
Returns ""
"C"
Returns the key unconverted.

let key = "SB001";
let client_name = key.xlate("xo_clients", 1, "X"); // "Client AAA"
// or
let name_and_type = xlate("xo_clients", key, "NAME_AND_TYPE", "X"); // "Client AAA (A)"

Database Sort/Select
Use Function Description

if

dbfile.select(sort_select_command = "")

Create an active select list of DB keys.

The select(command) function searches and orders database records for subsequent processing given an English language-like command.

The primary job of a database, beyond mere storage and retrieval of information, is to allow rapid searching and ordering of information on demand.

In Exodus, searching and ordering of information is known as "sort/select" and is performed by the select() function.

Executing the select() function creates an "active select list" which can then be consumed by the readnext() function.

dbfile: A opened database file or file name, or an open connection or an empty var for default connections. Subsequent readnext calls must use the same.

sort_select_command: A natural language command using dictionary field names. The command can be blank if a dbfile or filename is given in dbfile or just a file name and all keys will be selected in undefined order.

Example: "select xo_clients with type 'B' and with balance ge 100 by type by name"

Option: "(R)" appended to the sort_select_command acquires the database records as well.

return: True if any records are selected or false if none.

throw: VarDBException in case of any syntax error in the command.

Active select lists created using var.select()'s member function syntax cannot be consumed by the free function form of readnext() and vice versa.

var clients = "xo_clients";
if (clients.select("with type 'B' and with balance ge 100 by type by name"))
    while (clients.readnext(ID))
        println("Client code is {}", ID);
// or
if (select("xo_clients with type 'B' and with balance ge 100 by type by name"))
    while (readnext(ID))
        println("Client code is {}", ID);

if

dbfile.selectkeys(keys)

Create an active select list from a string of DB keys.

Similar to select() but creates the list directly from a var.

keys: An FM separated list of keys or key^VM^valueno pairs.

return: True if any keys are provided or false if not.

var dbfile = "";
let keys = "A01^B02^C03"_var;
if (dbfile.selectkeys(keys)) ... ok
assert(dbfile.readnext(ID) and ID == "A01");
// or
if (selectkeys(keys)) ... ok
assert(readnext(ID) and ID == "A01");

if

dbfile.hasnext()

Check if a select list is active.

dbfile: A file or connection var used in a prior select, selectkeys or getlist function call.

return: True if a select list is active and false if not.

If it returns true then a call to readnext() will return a database record key, otherwise not.

var clients = "xo_clients", key;
if (clients.select()) {
    assert(clients.hasnext());
}
// or
if (select("xo_clients")) {
    assert(hasnext());
}

if

dbfile.readnext(out key)

Acquire and consume one key from an active select list.

Each call to readnext consumes one key from the list.

Once all the keys in an active select list have been consumed by calls to readnext, the list becomes inactive.

See select() for example code.

dbfile: A file or connection var used in a prior select, selectkeys or getlist function call.

key[out]: Returns the first (next) key present in an active select list or "" if no select list is active.

return: True if a list was active and a key was acquired, false if not.

if

dbfile.readnext(out key, out valueno)

Acquire and consume one key and valueno pair from an active select list.

Similar to readnext(key) but multivalued.

If the active list was ordered by multivalued database fields then pairs of key and multivalue number will be available to the readnext function.

if

dbfile.readnext(out record, out key, out valueno)

Similar to readnext(key, valueno) but acquire the database record as well.

record[out]: Returns the next database record from the select list assuming that the select list was created with the (R) option otherwise "" if not.

key[out]: Returns the next database record key in the select list.

valueno[out]: The multivalue number if the select list was ordered on multivalued database record fields or 1 if not.

return: True if a list was active and a key was acquired, false if not.

var clients = "xo_clients";
if (clients.select("with type 'B' and with balance ge 100 by type by name (R)"))
    while (clients.readnext(RECORD, ID, MV))
        println("Code is {}, Name is {}", ID, RECORD.f(1));
// or
DICT = "dict.xo_clients";
if (select("xo_clients with type 'B' and with balance ge 100 by type by name (R)"))
    while (readnext(RECORD, ID, MV))
        println("Code is {}, Name is {}", calculate("CODE"), calculate("NAME"));

dbfile.clearselect()

Deactivate an active select list.

dbfile: A file or connection var used in a prior select, selectkeys or getlist function call.

return: Nothing

Has no effect if no select list is active for dbfile.

var clients = "xo_clients";
clients.clearselect();
if (not clients.hasnext()) ... ok
// or
clearselect();
if (not hasnext()) ... ok

if

dbfile.savelist(listname)

Save an active select list for later retrieval.

dbfile: A file or connection var used in a prior select, selectkeys or getlist function call.

listname: A suitable name that will be required for later retrieval.

return: True if saved successfully or false if there was no active list to be saved.

Any existing list with the same name will be overwritten.

Only the remaining unconsumed part of the active select list is saved.

Saved lists are stand-alone and are not tied to specific database files although they usually hold keys related to specific files.

Saved lists can be created from one file and used to access another.

savelist() merely writes an FM separated string of keys as a record in the "lists" database file using the list name as the key of the record.

If a saved list is very long, additional blocks of keys for the same list may be stored with keys like listname*2, listname*3 etc.

Select lists saved in the lists database file may be created, deleted and listed like database records in any other database file.

var clients = "xo_clients";
if (clients.select("with type 'B' by name")) {
}
// or
if (select("xo_clients with type 'B' by name")) {
    if (savelist("mylist")) ... ok
}

if

dbfile.getlist(listname)

Retrieve and reactivate a saved select list.

dbfile: A file or connection var to be used by subsequent readnext function calls.

listname: The name of an existing list in the "lists" database file, either created by savelist or manually.

return: True if the list was successfully retrieved and activated, or false if the list name doesnt exist.

Any currently active select list is replaced.

Retrieving a list does not delete it and a list can be retrieved more than once until specifically deleted.

var file = "";
if (file.getlist("mylist")) {
    while (file.readnext(ID))
        println("Key is {}", ID);
}
// or
if (getlist("mylist")) {
    while (readnext(ID))
        println("Key is {}", ID);
}

if

dbfile.deletelist(listname)

Delete a saved select list.

dbfile: A file or connection to the desired database.

listname: The name of an existing list in the "lists" database file.

return: True if successful or false if the list name doesnt exist.

var dbconn = "";
if (dbconn.deletelist("mylist")) ... ok
// or
if (deletelist("mylist")) ...

OS Time/Date
Use Function Description

var=

var::date()

Get the current date in internal format.

Internal format is the number of whole days since pick epoch 1967-12-31 00:00:00 UTC. Dates prior to that are numbered negatively.

return: A number. e.g. 20821 represents 2025-01-01 00:00:00 UTC for 24 hours.

let today1 = var::date();
// or
let today2 = date();

var=

var::time()

Get the current time in internal format.

Internal time is the number of whole seconds since the last midnight 00:00:00 (UTC).

return: A number in the range 0 - 86399 since there are 24*60*60 seconds in a day. e.g. 43200 if time is 12:00:00

let now1 = var::time();
// or
let now2 = time();

var=

var::ostime()

Get the current time in high resolution internal format.

High resolution internal time is the number of fractional seconds since the last midnight 00:00:00 (UTC).

return: A floating point with approx. nanosecond resolution depending on hardware.

e.g. 23343.704387955 approx. 06:29:03 UTC

let now1 = var::ostime();
// or
let now2 = ostime();

var=

var::ostimestamp()

Get the current timestamp in internal format.

Internal timestamp is the number of fractional days since pick epoch 1967-12-31 00:00:00 UTC. Negative for dates before.

return: A floating point with approx. nanosecond resolution depending on hardware.

e.g. Was 20821.99998842593 around 2025-01-01 23:59:59 UTC

let now1 = var::ostimestamp();
// or
let now2 = ostimestamp();

var=

vardate.ostimestamp(ostime)

Get the timestamp for a given date and time

vardate: Internal date from date(), iconv("D") etc.

ostime: Internal time from time(), ostime(), iconv("MT") etc.

let idate = iconv("2025-01-01", "D"), itime = iconv("23:59:59", "MT");
let ts1 = idate.ostimestamp(itime); // 20821.99998842593
// or
let ts2 = ostimestamp(idate, itime);

var::ossleep(milliseconds)

Sleep/pause/wait

milliseconds: How to long to sleep.

Release the processor if not needed for a period of time or a delay is required.

var::ossleep(100); // sleep for 100ms
// or
ossleep(100);

var=

file_dir_list.oswait(milliseconds)

Sleep/pause/wait up for a file system event

file_dir_list: An FM delimited list of OS files and/or dirs to monitor.

milliseconds: How long to wait. Any terminal input (e.g. a key press) will also terminate the wait.

return: An FM array of event information is returned. See below.

Multiple events may be captured and are returned in multivalues.

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

Returned dynamic array fields:

  1. Event type codes
  2. dirpaths
  3. filenames
  4. d=dir, f=file

Possible event type codes:

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
Use Function Description

if

osfilevar.osopen(osfilename, utf8 = true)

Open an OS file handle.

Allow random read and write operations.

Open for writing if possible, otherwise read-only.

osfilevar[out]: Handle for subsequent osbread() and osbwrite() calls.

osfilename: Path and name of an existing OS file.

utf8: True (default) removes partial UTF-8 sequences from osbread() ends; false returns raw data.

return: True if opened successfully, false if file doesn’t exist or isn’t accessible.

let osfilename = ostempdir() ^ "xo_gendoc_test.conf";
if (oswrite("" on osfilename)) ... ok /// Create an empty OS file
var ostempfile;
if (ostempfile.osopen(osfilename)) ... ok
// or
if (osopen(osfilename to ostempfile)) ... ok

if

strvar.osbwrite(osfilevar, io offset)

Random write data to an OS file.

At a specified position.

strvar: Data to write.

osfilevar: Handle from osopen() or a path/filename; creates file if offset is 0 and it’s new, fails if offset isn’t 0.

offset: [in/out] Start position (0-based); updated to end of written data; -1 appends.

return: True if write succeeds, false if file isn’t accessible, updateable, or creatable.

let osfilename = ostempdir() ^ "xo_gendoc_test.conf";
let text = "aaa=123\nbbb=456\n";
var offset = -1; /// -1 means append.
if (text.osbwrite(osfilename, offset)) ... ok // offset -> 16
// or
if (not osbwrite(text on osfilename, offset)) ...

if

strvar.osbread(osfilevar, io offset, length)

Random read data from an OS file

From a specified position.

strvar[out]: Data read.

osfilevar: Handle from osopen() or a path/filename.

offset: [in/out] Start position (0-based); updated to end of read data.

length: Chars to read; with utf8=true (default), may return less to ensure complete UTF-8 code points.

return: True if read succeeds, false if file doesn’t exist or isn’t accessible or offset >= file size.

let osfilename = ostempdir() ^ "xo_gendoc_test.conf";
var text, offset = 0;
if (text.osbread(osfilename, offset, 8)) ... ok // text -> "aaa=123\n" // offset -> 8
// or
if (osbread(text from osfilename, offset, 8)) ... ok // text -> "bbb=456\n" // offset -> 16

osfile << anything << std::endl;

Use convenient << syntax to output anything to an osfile.

osfile: An OS path and filename or an osfilevar opened by osopen(). The file will be appended, or created if it does not already exist. osfile can be "stdout" or "stderr" to simulate cout/cerr/clog.

let txtfile = "t_temp.txt";
if (not osremove(txtfile)) {} // Remove any existing file.
txtfile << txtfile << " " << 123.456789 << " " << 123 << std::endl;
let v1 = osread(txtfile);   // "t_temp.txt 123.457 123\n"

All standard c++ io manipulators may be used e.g. std::setw, setfill etc.

let vout = "t_std_iomanip_overview.txt";
if (not osremove(vout)) {}
using namespace std;

vout << boolalpha    << true          << "\ttrue"    << endl;
vout << noboolalpha  << true          << "\t1"       << endl;

vout << showpoint    << 42.0          << "\t42.0000" << endl;
vout << noshowpoint  << 42.0          << "\t42"      << endl;

vout << showpos      << 42            << "\t+42"     << endl;
vout << noshowpos    << 42            << "\t42"      << endl;

vout << skipws       << " " << 42     << "\t 42"     << endl;
vout << noskipws     << " " << 42     << "\t 42"     << endl;

vout << unitbuf      << "a"           << "\ta"       << endl;
vout << nounitbuf    << "b"           << "\tb"       << endl;

vout << setw(6)      << 42            << "\t    42"  << endl;

vout << left         << setw(6) << 42 << "\t42    "  << endl;
vout << right        << setw(6) << 42 << "\t    42"  << endl;
vout << internal     << setw(6) << 42 << "\t    42"  << endl;
vout << setfill('*') << setw(6) << 42 << "\t****42"  << endl;

vout << showbase     << hex << 255    << "\t0xff"    << endl;
vout << noshowbase   << 255           << "\tff"      << endl;

vout << uppercase    << 255           << "\tFF"      << endl;
vout << nouppercase  << 255           << "\tff"      << endl;

vout << oct          << 255           << "\t377"     << endl;
vout << hex          << 255           << "\tff"      << endl;
vout << dec          << 255           << "\t255"     << endl;

vout << fixed        << 42.1          << "\t42.100000"            << endl;
vout << scientific   << 42.1          << "\t4.210000e+01"         << endl;
vout << hexfloat     << 42.1          << "\t0x1.50ccccccccccdp+5" << endl;
vout << defaultfloat << 42.1          << "\t42.1"                 << endl;

vout << std::setprecision(3)      << 42.1567  << "\t42.2"  << endl;
vout << resetiosflags(ios::fixed) << 42.1567  << "\t42.2"  << endl;
vout << setiosflags(ios::showpos) << 42       << "\t+42"   << endl;

// Verify actual v. expected.
var act_v_exp = osread(vout);
act_v_exp.converter("\n\t", FM ^ VM); /// Text to dynamic array
act_v_exp = invertarray(act_v_exp);   /// Columns <-> Rows
assert(act_v_exp.f(1) eq act_v_exp.f(2));

var().osclose()

Close an osfilevar.

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

var osfilevar; if (osfilevar.osopen(ostempfile())) ... ok
osfilevar.osclose();
// or
osclose(osfilevar);

if

strvar.oswrite(osfilename, codepage = "")

Create a complete OS file from a var.

strvar: The text or data to be used to create the file.

osfilename: Absolute or relative path and filename to be written. Any existing OS file is removed first.

codepage: If specified then output is converted from UTF-8 to that codepage before being written. Otherwise no conversion is done.

return: True if successful or false if not possible for any reason. e.g. Path is not writeable, permissions etc

let text = &qquot;aaa = 123\nbbb = 456";
let osfilename = ostempdir() ^ "xo_gendoc_test.conf";
if (text.oswrite(osfilename)) ... ok
// or
if (oswrite(text on osfilename)) ... ok

if

strvar.osread(osfilename, codepage = "")

Read a complete OS file into a var.

osfilename: Absolute or relative path and filename to be read.

codepage: If specified then input is converted from that codepage to UTF-8 after being read. Otherwise no conversion is done.

strvar[out]: Is currently set to "" in case of any failure but this is may be changed in a future release to either force var to be unassigned or to leave it untouched. To guarantee future behaviour either add a line 'xxxx.defaulter("")' or set var manually in case osread() returns false. Or use the one argument free function version of osread() which always returns "" in case of failure to read.

return: True if successful or false if not possible for any reason. e.g. File doesnt exist, insufficient permissions etc.

var text;
let osfilename = ostempdir() ^ "xo_gendoc_test.conf";
if (text.osread(osfilename)) ... ok // text -> "aaa = 123\nbbb = 456"
// or
if (osread(text from osfilename)) ... ok
let text2 = osread(osfilename);

if

osfile_or_dirname.osrename(new_dirpath_or_filepath)

Rename an OS file or dir.

In the OS file system.

The source and target must exist in the same storage device.

osfile_or_dirname: Absolute or relative path and file or dir name to be renamed.

new_dirpath_or_filepath: Will not overwrite an existing OS file or dir.

return: True if successful or false if not possible for any reason. e.g. Target already exists, path is not writeable, permissions etc.

Uses std::filesystem::rename internally.

let from_osfilename = ostempdir() ^ "xo_gendoc_test.conf";
let to_osfilename = from_osfilename ^ ".bak";
if (not osremove(ostempdir() ^ "xo_gendoc_test.conf.bak")) {}; // Cleanup first

if (from_osfilename.osrename(to_osfilename)) ... ok
// or
if (osrename(from_osfilename, to_osfilename)) ...

if

osfile_or_dirname.osmove(to_osfilename)

"Move" an OS file or dir.

Within the OS file system.

Attempt osrename first, then oscopy plus osremove original.

osfile_or_dirname: Absolute or relative path and file or dir name to be moved.

to_osfilename: Will not overwrite an existing OS file or dir.

return: 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, storage space etc.

let from_osfilename = ostempdir() ^ "xo_gendoc_test.conf.bak";
let to_osfilename = from_osfilename.cut(-4);

if (not osremove(ostempdir() ^ "xo_gendoc_test.conf")) {}; // Cleanup first
if (from_osfilename.osmove(to_osfilename)) ... ok
// or
if (osmove(from_osfilename, to_osfilename)) ...

if

osfile_or_dirname.oscopy(to_osfilename)

Copy an OS file or directory.

Including subdirs.

osfile_or_dirname: Absolute or relative path and file or dir name to be copied.

to_osfilename: Will overwrite an existing OS file or merge into an existing dir.

return: True if successful or false if not possible for any reason. e.g. Source doesnt exist or cannot be accessed, target is not writeable, permissions, storage space, etc.

Uses std::filesystem::copy internally with recursive and overwrite options

let from_osfilename = ostempdir() ^ "xo_gendoc_test.conf";
let to_osfilename = from_osfilename ^ ".bak";

if (from_osfilename.oscopy(to_osfilename)) ... ok;
// or
if (oscopy(from_osfilename, to_osfilename)) ... ok

if

osfilename.osremove()

Remove/delete an OS file.

From the OS file system.

Will not remove directories. Use osrmdir() to remove directories

osfilename: Absolute or relative path and file name to be removed.

return: True if successful or false if not possible for any reason. e.g. Target doesnt exist, path is not writeable, permissions etc.

If osfilename is an osfilevar then it is automatically closed.

let osfilename = ostempdir() ^ "xo_gendoc_test.conf";
if (osfilename.osremove()) ... ok
// or
if (osremove(osfilename)) ...

OS Directories
Use Function Description

var=

dirpath.oslist(globpattern = "", mode = 0)

Get a list of OS files and/or dirs.

dirpath: Absolute or relative dir path.

globpattern: e.g. *.conf to be appended to the dirpath or a complete path plus glob pattern e.g. /etc/ *.conf.

mode:

0
Any regular OS file or dir (Default).
1
Only regular OS files.
2
Only dirs.

return: An FM delimited string containing all matching dir entries given a dir path

var entries1 = "/etc/"_var.oslist("*.cfg"); /// e.g. "adduser.conf^ca-certificates.con^... etc."
// or
var entries2 = oslist("/etc/" "*.conf");

var=

dirpath.oslistf(globpattern = "")

Get a list of OS files.

See oslist() for info.

var=

dirpath.oslistd(globpattern = "")

Get a list of OS dirs.

See oslist() for info.

var=

osfile_or_dirpath.osinfo(mode = 0)

Get dir info about an OS file or dir.

return: A short string containing size ^ FM ^ modified_time ^ FM ^ modified_time or "" if not a regular file or dir.

mode: 0: Default. 1: Must be a regular OS file. 2: Must be an OS dir.

See also osfile() and osdir()

var info1 = "/etc/hosts"_var.osinfo(); /// e.g. "221^20597^78309"_var
// or
var info2 = osinfo("/etc/hosts");

var=

osfilename.osfile()

Get dir info of an OS file.

osfilename: Absolute or relative path and file name.

return: A short string containing size ^ FM ^ modified_time ^ FM ^ modified_time or "" if not a regular file.

Alias for osinfo(1)

var fileinfo1 = "/etc/hosts"_var.osfile(); /// e.g. "221^20597^78309"_var
// or
var fileinfo2 = osfile("/etc/hosts");

var=

dirpath.osdir()

Get dir info of an OS dir.

dirpath: Absolute or relative path and dir name.

return: A short string containing FM ^ modified_time ^ FM ^ modified_time or "" if not a dir.

Alias for osinfo(2)

var dirinfo1 = "/etc/"_var.osdir(); /// e.g. "^20848^44464"_var
// or
var dirinfo2 = osfile("/etc/");

if

dirpath.osmkdir()

Create a new OS file system directory.

Parent dirs wil be created if necessary.

dirpath: Absolute or relative path and dir name.

return: True if successful.

let osdirname = "xo_test/aaa";
if (osrmdir("xo_test/aaa")) {}; // Cleanup first
if (osdirname.osmkdir()) ... ok
// or
if (osmkdir(osdirname)) ...

if

var::oscwd(newpath)

Change the current working dir.

newpath: An absolute or relative dir path and name.

return: True if successful or false if not. e.g. Invalid dirpath, insufficient permission etc.

let osdirname = "xo_test/aaa";
if (osdirname.oscwd()) ... ok
// or
if (oscwd(osdirname)) ... ok
if (oscwd("../..")) ... ok /// Change back to avoid errors in following code.

var=

var::oscwd()

Get the current working dir path and name.

return: The current working dir path and name.

e.g. "/root/exodus/cli/src/xo_test/aaa"

var cwd1 = var().oscwd();
// or
var cwd2 = oscwd();

if

dirpath.osrmdir(evenifnotempty = false)

Remove (deletes) an OS dir,

eventifnotempty: If true any subdirs will also be removed/deleted recursively, otherwise the function will fail and return false.

return: Returns true if successful or false if not. e.g dir doesnt exist, insufficient permission, not empty etc.

let osdirname = "xo_test/aaa";
if (osdirname.osrmdir()) ... ok
// or
if (osrmdir(osdirname)) ...

OS Shell/Environment
Use Function Description

if

command.osshell()

Execute a shell command.

command: An executable command to be interpreted by the default OS shell.

return: True if the process terminates with error status 0 and false otherwise.

Append "&>/dev/null" to the command to suppress terminal output.

let cmd = "echo $HOME";
if (cmd.osshell()) ... ok
// or
if (osshell(cmd)) ... ok

if

instr.osshellread(oscmd)

Execute a shell command and capture its stdout.

return: The stout of the shell command.

Append "2>&1" to the command to capture stderr/stdlog output as well.

let cmd = "echo $HOME";
var text;
if (text.osshellread(cmd)) ... ok

// or capturing stdout but ignoring exit status
text = osshellread(cmd);

if

outstr.osshellwrite(oscmd)

Execute a shell command and provide its stdin.

return: True if the process terminates with error status 0 and false otherwise.

Append "&> somefile" to the command to suppress and/or capture output.

let outtext = "abc xyz";
if (outtext.osshellwrite("grep xyz")) ... ok
// or
if (osshellwrite(outtext, "grep xyz")) ... ok

if

dirpath.osprocess(oscmd, stdin_for_process, out stdout_from_process, out stderr_from_process, out exit_status, timeout_secs = 0)

Run an OS program synchronously.

Provide its standard input and capture its output, errors, and exit status.

Shell features (e.g., pipes, redirects) are unsupported but can be invoked via an oscmd like "bash -c 'abc|yy $HOME'".

oscmd: Executable and arguments; must exist in OS PATH.

stdin_for_process: Optional; input data for the program’s standard input.

stdout_from_process[out]: Standard output from the program.

stderr_from_process[out]: Error/log output from the program.

exit_status[out]: Program’s exit status: 0 (normal), -1 (timeout), else (error).

timeout_secs: Optional; max runtime in seconds (default 0 = no timeout).

return: True if program ran and exited with status 0 (success) or false if program failed to start, timed out, or exited with non-zero status.

throw: Pipe creation failed, fork failed, poll failed.

var v_stdout, v_stderr, v_exit_status;
if (var::osprocess("grep xyz", "abc\nxyz 123\ndef", v_stdout, v_stderr, v_exit_status)) ... ok // v_stdout -> "xyz 123" // v_exit_status = 0
// or
if (osprocess("grep xyz", "abc\nxyz 123\ndef", v_stdout, v_stderr, v_exit_status)) ... ok

var=

var::ostempdir()

Get the tmp dir path.

return: A string e.g. "/tmp/"

let v1 = var::ostempdir();
// or
let v2 = ostempdir();

var=

var::ostempfile()

Create a temporary file.

return: The name of new temporary file e.g. "/tmp/~exoEcLj3C"

var temposfilename1 = var::ostempfile();
// or
var temposfilename2 = ostempfile();

if

envvalue.osgetenv(envcode)

Get the value of an environment variable.

envcode: The code of the env variable to get or "" for all.

envvalue[out]: Set to the value of the env variable if set otherwise "". If envcode is "" then envvalue is set to a dynamic array of all environment variables LIKE CODE1=VALUE1^CODE2=VALUE2...

return: True if the envcode is set or false if not.

osgetenv and ossetenv work with a per thread copy of the OS process environment. This avoids multithreading issues but does not change the process environment. Child processes created by var::osshell() will not inherit any env variables set using ossetenv() so the oscommand will need to be prefixed to achieve the desired result.

For the actual system environment, see "man environ". extern char **environ; // environ is a pointer to an array of pointers to char* env pairs like xxx=yyy and the last pointer in the array is nullptr.

var envvalue1;
if (envvalue1.osgetenv("HOME")) ... ok // e.g. "/home/exodus"
// or
let envvalue2 = osgetenv("EXO_ABC"); // "XYZ"

envvalue.ossetenv(envcode)

Set the value of an environment variable.

envcode: The code of the env variable to set.

envvalue: The new value to set the env code to.

let envcode = "EXO_ABC", envvalue = "XYZ";
envvalue.ossetenv(envcode);
// or
ossetenv(envcode, envvalue);

var=

var::ospid()

Get the current OS process id.

return: A number e.g. 663237.

let pid1 = var::ospid(); /// e.g. 663237
// or
let pid2 = ospid();

var=

var::ostid()

Get the current OS thread process id.

return: A number e.g. 663237.

let tid1 = var::ostid(); /// e.g. 663237
// or
let tid2 = ostid();

var=

var::version()

Get the exodus library version info.

return: The git commit details as at the time the library was built.

// e.g.
// Local:  doc 2025-03-19 18:15:31 +0000 219cdad8a
// Remote: doc 2025-03-17 15:03:00 +0000 958f412f0
// https://github.com/exodusdb/exodusdb/commit/219cdad8a
// https://github.com/exodusdb/exodusdb/archive/958f412f0.tar.gz
//
let v1 = var::version();
// or
let v2 = version();

if

strvar.setxlocale(newlocalecode)

Set the current thread's default locale.

strvar: The new locale codepage code.

True if successful

if (var::setxlocale("en_US.utf8")) ... ok
// or
if (setxlocale("en_US.utf8")) ... ok

var=

var.getxlocale()

Get the current thread's default locale.

return: A locale codepage code string.

let v1 = var::getxlocale(); // "en_US.utf8"
// or
let v2 = getxlocale();

Output
Use Function Description

expr

strvar.outputl(prefix = "")

Output to stdout with optional prefix.

Append an NL char.

Is FLUSHED, not buffered.

The raw string bytes are output. No character or byte conversion is performed.

"abc"_var.outputl("xyz = "); /// Sends "xyz = abc\n" to stdout and flushes.
// or
outputl("xyz = ", "abc"); /// Any number of arguments is allowed. All will be output.

expr

strvar.output(prefix = "")

Same as outputl() but doesnt append an NL char and is BUFFERED, not flushed.

expr

strvar.outputt(prefix = "")

Same as outputl() but appends a tab char instead of an NL char and is BUFFERED, not flushed.

expr

strvar.logputl(prefix = "")

Output to stdlog with optional prefix.

Appends an NL char.

Is BUFFERED not flushed.

Any of the six types of field mark chars present are converted to their visible versions,

"abc"_var.logputl("xyz = "); /// Sends "xyz = abc\n" to stdlog buffer and is not flushed.
// or
logputl("xyz = ", "abc");; /// Any number of arguments is allowed. All will be output.

expr

strvar.logput(prefix = "")

Same as logputl() but doesnt append an NL char.

expr

strvar.errputl(prefix = "")

Output to stderr with optional prefix.

Appends an NL char.

Is FLUSHED not buffered.

Any of the six types of field mark chars present are converted to their visible versions,

"abc"_var.errputl("xyz = "); /// Sends "xyz = abc\n" to stderr
// or
errputl("xyz = ", "abc"); /// Any number of arguments is allowed. All will be output.

expr

strvar.errput(prefix = "")

Same as errputl() but doesnt append an NL char and is BUFFERED not flushed.

expr

strvar.put(std::ostream& ostream1)

Output to a given stream.

Is BUFFERED not flushed.

The raw string bytes are output. No character or byte conversion is performed.

var().osflush()

Flush any and all buffered output to stdout and stdlog.

var().osflush();
// or
osflush();

Input
Use Function Description

if

var.input(prompt = "")

Read one line of input from stdin.

return: True if successful or false if EOF or user pressed Esc or Ctrl+X in a terminal.

var[in]: The default value for terminal input and editing. Ignored if not a terminal.

var[out]: Raw bytes up to but excluding the first new line char. In case of EOF or user pressed Esc or Ctrl+X in a terminal it will be changed to "".

Prompt: If provided, it will be displayed on the terminal.

Multibyte/UTF8 friendly.

// var v1 = "defaultvalue";
// if (v1.input("Prompt:")) ... ok
// or
// var v2 = input();

expr

var.keypressed(wait = false)

Return the code of the current terminal key pressed.

wait: Defaults to false. True means wait for a key to be pressed if not already pressed.

return: ASCII or key code defined according to terminal protocol.

return: "" if stdin is not a terminal.

e.g. The PgDn key if pressed might return an escape sequence like "\x1b[6~"

It only takes a few µsecs to return false if no key is pressed.

var v1; v1.keypressed();
// or
var v2 = keypressed();

if

var().isterminal(in_out_err = 1)

Check if is a terminal or a file/pipe.

Can check stdin, stdout, stderr.

in_out_err:

0
stdin
1
stdout (Default)
2
stderr.

return: True if it is a terminal or false if it is a file or pipe.

Note that if the process is at the start or end of a pipeline, then only stdin or stdout will be a terminal.

The type of stdout terminal can be obtained from the TERM environment variable.

var v1 = var().isterminal(); /// 1 or 0
// or
var v2 = isterminal();

if

var().hasinput(milliseconds = 0)

Check if stdin has any bytes available for input.

If no bytes are immediately available, the process sleeps for up to the given number of milliseconds, returning true immediately any bytes become available or false if the period expires without any bytes becoming available.

return: True if any bytes are available otherwise false.

It only takes a few µsecs to return false if no bytes are available and no wait time has been requested.

if

var().eof()

True if stdin is at end of file

if

var().echo(on_off = true)

Set terminal echo on or off.

"On" causes all stdin data to be reflected to stdout if stdin is a terminal.

Turning terminal echo off can be used to prevent display of confidential information.

return: True if successful.

var().breakon()

Install various interrupt handlers.

Automatically called in program/thread initialisation by exodus_main.

SIGINT
Ctrl+C -> "Interrupted. (C)ontinue (Q)uit (B)acktrace (D)ebug (A)bort ?"
SIGHUP
Sets a variable "RELOAD_req" which may be handled or ignored by the program.
SIGTERM
Sets a variable "TERMINATE_req" which may be handled or ignored by the program.

var().breakoff()

Disable keyboard interrupt.

Ctrl+C becomes inactive in terminal.

Math/Boolean
Use Function Description

var=

varnum.abs()

Absolute value.

let v1 = -12.34;
let v2 = v1.abs(); // 12.34
// or
let v3 = abs(v1);

var=

varnum.pwr(exponent)

Power.

let v1 = var(2).pwr(8); // 256
// or
let v2 = pwr(2, 8);

varnum.initrnd()

Initialise the seed for rnd().

Allow the stream of pseudo random numbers generated by rnd() to be reproduced.

Seeded from std::chrono::high_resolution_clock::now() if the argument is 0;

var(123).initrnd(); /// Set seed to 123
// or
initrnd(123);

var=

varnum.rnd()

Pseudo random number generator.

return: A pseudo random integer between 0 and the provided maximum minus 1.

Uses std::mt19937 and std::uniform_int_distribution<int>

let v1 = var(100).rnd(); /// Random 0 to 99
// or
let v2 = rnd(100);

var=

varnum.exp()

Power of e.

let v1 = var(1).exp(); // 2.718281828459045
// or
let v2 = exp(1);

var=

varnum.sqrt()

Square root.

let v1 = var(100).sqrt(); // 10
// or
let v2 = sqrt(100);

var=

varnum.sin()

Sine of degrees.

let v1 = var(30).sin(); // 0.5
// or
let v2 = sin(30);

var=

varnum.cos()

Cosine of degrees.

let v1 = var(60).cos(); // 0.5
// or
let v2 = cos(60);

var=

varnum.tan()

Tangent of degrees.

let v1 = var(45).tan(); // 1
// or
let v2 = tan(45);

var=

varnum.atan()

Arctangent of degrees.

let v1 = var(1).atan(); // 45
// or
let v2 = atan(1);

var=

varnum.loge()

Natural logarithm.

return: Floating point var (double)

let v1 = var(2.718281828459045).loge(); // 1
// or
let v2 = loge(2.718281828459045);

var=

varnum.integer()

Truncate decimals.

Convert decimal to nearest integer towards zero.

Remove decimal fraction.

return: An integer var

let v1 = var(2.9).integer(); // 2
// or
let v2 = integer(2.9);

var v3 = var(-2.9).integer(); // -2
// or
var v4 = integer(-2.9);

var=

varnum.floor()

Floor decimals.

Convert decimal to nearest integer towards negative infinity.

return: An integer var

let v1 = var(2.9).floor(); // 2
// or
let v2 = floor(2.9);

var v3 = var(-2.9).floor(); // -3
// or
var v4 = floor(-2.9);

var=

varnum.mod(modulus)

Modulus function.

Identical to C++ % operator only for positive numbers and modulus

Negative denominators are considered as periodic with positive numbers

Result is between [0, modulus) if modulus is positive

Result is between (modulus, 0] if modulus is negative (symmetric)

throw: VarDivideByZero if modulus is zero.

Floating point works.

let v1 = var(11).mod(5); // 1
// or
let v2 = mod(11, 5); // 1
let v3 = mod(-11, 5); // 4
let v4 = mod(11, -5); // -4
let v5 = mod(-11, -5); // -1

int=

var::setprecision(newprecision)

Set floating point precision.

This is the number of post-decimal point digits to consider for floating point comparison and implicit conversion to strings.

The default precision is 4 which is 0.0001.

NUMBERS AND DIFFERENCES SMALLER THAN 0.0001 ARE TREATED AS ZERO UNLESS PRECISION IS INCREASED.

With the default precision, Exodus handles, without assistance, conversion to and from strings for positive and negative numbers between 0.0001 and 999'999'999'999.9999 (12 digits).

newprecision: New precision between -307 and 308 inclusive.

return: The new precision if successful or the old precision if not.

Not required if using common numbers or using the explicit rounding and formatting functions to convert numbers to strings.

Increasing the precision allows comparing and outputting smaller numbers but creates errors handling large numbers.

Setting precision inside a perform, execute or dictionary function lasts until termination of the function.

See cli/demo_precision for more info.

assert(0.000001_var == 0); /// NOTE WELL: Default precision 4.
let new_precision1 = var::setprecision(6); // 6 // Increase the precision.
// or
let new_precision2 = setprecision(6);
assert(0.000001_var != 0); /// NOTE: Precision 6.

int=

var::getprecision()

Get current floating point precision.

return: The current precision setting.

See setprecision() for more info.

let curr_precision1 = var::getprecision();
// or
let curr_precision2 = getprecision();

I/O Conversion Codes

Use Function Description

var=

vardate.oconv("D")

oconv "D" Convert internal date to external format.

Date output: Convert internal date format to human readable date or calendar info in text format.

return: Human readable date or calendar info, or the original value unconverted if non-numeric.

flags: See examples below.

Any Dynamic array structure is preserved.

let v1 = 19002;
var v2;
v2 =  v1.oconv( "D"   ) ; //  "09 JAN 2020"   // Default

v2 =  v1.oconv( "D/"  ) ; //  "01/09/2020"    // mm/dd/yyyy - American numeric
v2 =  v1.oconv( "D-"  ) ; //  "01-09-2020"    // mm-dd-yyyy - American numeric

v2 =  v1.oconv( "D/E" ) ; //  "09/01/2020"    // dd/mm/yyyy - International numeric
v2 =  v1.oconv( "D-E" ) ; //  "09-01-2020"    // dd-mm-yyyy - International numeric

v2 =  v1.oconv( "D2"  ) ; //  "09 JAN 20"     // 2 digit year
v2 =  v1.oconv( "D0"  ) ; //  "09 JAN"        // No year

v2 =  v1.oconv( "DS"  ) ; //  "2020 JAN 09"   // yyyy mmm dd - ISO year first, alpha month
v2 =  v1.oconv( "DS-" ) ; //  "2020-01-09"    // yyyy-mm-dd  - ISO year first, numeric month

v2 =  v1.oconv( "DZ"  ) ; //  " 9 JAN 2020"   // Leading 0 become spaces
v2 =  v1.oconv( "DZZ" ) ; //  "9 JAN 2020"    // Leading 0 are suppressed
v2 =  v1.oconv( "D!"  ) ; //  "09JAN2020"     // No separators
v2 =  v1.oconv( "DS-!") ; //  "20200109"      // yyyymmdd packed

v2 =  v1.oconv( "DM"  ) ; //  "1"             // Month number
v2 =  v1.oconv( "DMA" ) ; //  "JANUARY"       // Month name
v2 =  v1.oconv( "DY"  ) ; //  "2020"          // Year number
v2 =  v1.oconv( "DY2" ) ; //  "20"            // Year 2 digits
v2 =  v1.oconv( "DD"  ) ; //  "9"             // Day number in month (1-31)
v2 =  v1.oconv( "DW"  ) ; //  "4"             // Weekday number (1-7)
v2 =  v1.oconv( "DWA" ) ; //  "THURSDAY"      // Weekday name
v2 =  v1.oconv( "DQ"  ) ; //  "1"             // Quarter number
v2 =  v1.oconv( "DJ"  ) ; //  "9"             // Day number in year
v2 =  v1.oconv( "DL"  ) ; //  "31"            // Last day number of month (28-31)

// Dynamic array
let v3 = "12345^12346]12347"_var;
v2 = v3.oconv("D") ; //  "18 OCT 2001^19 OCT 2001]20 OCT 2001"_var

// or
v2 =  oconv(v3, "D"   ) ;

var=

strvar.iconv("D")

iconv "D" Convert external date format to internal.

Date input: Convert human readable date to internal date format.

return: Internal date or "" if the input is an invalid date.

Internal date format is whole days since 1967-12-31 00:00:00 which is day 0.

Any Dynamic array structure is preserved.

// International order "DE"
var v2;
v2 =             oconv(19005, "DE") ; //  "12 JAN 2020"
v2 =    "12/1/2020"_var.iconv("DE") ; //  19005
v2 =    "12 1 2020"_var.iconv("DE") ; //  19005
v2 =    "12-1-2020"_var.iconv("DE") ; //  19005
v2 =  "12 JAN 2020"_var.iconv("DE") ; //  19005
v2 =  "jan 12 2020"_var.iconv("DE") ; //  19005

// American order "D"
v2 =             oconv(19329, "D") ; //  "01 DEC 2020"
v2 =    "12/1/2020"_var.iconv("D") ; //  19329
v2 =   "DEC 1 2020"_var.iconv("D") ; //  19329
v2 =   "1 dec 2020"_var.iconv("D") ; //  19329

// Reverse order
v2 =   "2020/12/1"_var.iconv("DE") ; //  19329
v2 =    "2020-12-1"_var.iconv("D") ; //  19329
v2 =   "2020 1 dec"_var.iconv("D") ; //  19329

//Invalid date
v2 =    "2/29/2021"_var.iconv("D") ; //  ""
v2 =   "29/2/2021"_var.iconv("DE") ; //  ""

// or
v2 = iconv("12/1/2020"_var, "DE") ; //  19005

var=

vartime.oconv("MT")

oconv "MT" Convert internal time to external format.

Time output: Convert internal time format to human readable time e.g. "10:30:59".

return: Human readable time or the original value unconverted if non-numeric.

Conversion code (e.g. "MTHS") is "MT" ^ flags ...

flags:

H
Show AM/PM otherwise 24 hour clock is used.
S
Output seconds
2
Ignored (used in iconv)
:
Any other flag is used as the separator char instead of ":"

Any Dynamic array structure is preserved.

let v1  = 62000;
var v2;
v2 = v1.oconv("MT"  ); // "17:13"      // Default
v2 = v1.oconv("MTH" ); // "05:13PM"    // 'H' flag for AM/PM
v2 = v1.oconv("MTS" ); // "17:13:20"   // 'S' flag for seconds
v2 = v1.oconv("MTHS"); // "05:13:20PM" // Both flags

let v3  = 0;
v2 = v3.oconv("MT"  ); // "00:00"
v2 = v3.oconv("MTH" ); // "12:00AM"
v2 = v3.oconv("MTS" ); // "00:00:00"
v2 = v3.oconv("MTHS"); // "12:00:00AM"

// Dynamic array
let v4  = "61980^62040]62100"_var;
v2 = v4.oconv("MT");    // "17:13^17:14]17:15"_var

// or
v2 = oconv(v1, "MT");    // "17:13"

var=

strvar.iconv("MT")

iconv "MT" Convert external time format to internal.

Time input: Convert human readable time (e.g. "10:30:59") to internal time format.

return: Internal time or "" if the input is an invalid time.

Internal time format is whole seconds since midnight.

Accepts: Two or three groups of digits surrounded and separated by any non-digits char(s).

Any Dynamic array structure is preserved.

var v2;
v2 =       "17:13"_var.iconv( "MT" ) ; //  61980
v2 =     "05:13PM"_var.iconv( "MT" ) ; //  61980
v2 =    "17:13:20"_var.iconv( "MT" ) ; //  62000
v2 =  "05:13:20PM"_var.iconv( "MT" ) ; //  62000

v2 =       "00:00"_var.iconv( "MT" ) ; //  0
v2 =     "12:00AM"_var.iconv( "MT" ) ; //  0     // Midnight
v2 =     "12:00PM"_var.iconv( "MT" ) ; //  43200 // Noon
v2 =    "00:00:00"_var.iconv( "MT" ) ; //  0
v2 =  "12:00:00AM"_var.iconv( "MT" ) ; //  0

// Dynamic array
v2 = "17:13^05:13PM]17:13:20"_var.iconv("MT") ; //  "61980^61980]62000"_var

// or
v2 = iconv("17:13", "MT") ; //  61980

var=

varnum.oconv("MD")

oconv "MD" Convert internal numbers to external format.

Number output: Convert internal numbers to external text format after rounding and optional scaling.

return: A string or, if the value is not numeric, then no conversion is performed and the original value is returned.

conversion_code: (e.g. "MD20Z") is "MD" or "MC", 1st digit, 2nd digit, flags ...

"MD"
Outputs like 123.45 (International)
"MC"
Outputs like 123,45 (European)

1st digit * Decimal places to display. Also decimal places to move if 2nd digit not present and no P flag present.

2nd digit * Optional decimal places to move left if P flag not present.

flags:

P
Preserve decimal places. Same as 2nd digit = 0;
Z
Zero flag - return "" if zero.
X
No conversion - return as is.
.
Separate thousands depending on MD or MC.
,
Ditto
-
Suffix negatives with "-" and positives with " " (space).
<
Wrap negatives in "<" and ">" chars.
C
Suffix negatives with "CR" and positives or zero with "DB".
D
Suffix negatives with "DB" and positives or zero with "CR".

Any Dynamic array structure is preserved.

var v1 = -1234.567;
var v2;
v2 =  v1.oconv( "MD20"   ) ; //   "-1234.57"
v2 =  v1.oconv( "MD20,"  ) ; //  "-1,234.57"    // , flag
v2 =  v1.oconv( "MC20,"  ) ; //  "-1.234,57"    // MC code
v2 =  v1.oconv( "MD20,-" ) ; //   "1,234.57-"   // - flag
v2 =  v1.oconv( "MD20,<" ) ; //  "<1,234.57>"   // < flag
v2 =  v1.oconv( "MD20,C" ) ; //   "1,234.57CR"  // C flag
v2 =  v1.oconv( "MD20,D" ) ; //   "1,234.57DB"  // D flag

// Dynamic array
var v3 = "1.1^2.1]2.2"_var;
v2 =  v3.oconv( "MD20"   ) ; //  "1.10^2.10]2.20"_var

// or
v2 =  oconv(v1, "MD20"   ) ; //   "-1234.57"   

var=

var.oconv("LRC")

oconv "L" "R" "C" Justify text and numbers.

Text justification: Left, right and center. Padding and truncating. See Procrustes.

e.g. "L#10", "R#10", "C#10"

Useful when outputting to terminal devices where spaces are used for alignment.

Dynamic array structure is preserved.

ASCII only.

var v2;
v2 =      "abcde"_var.oconv( "L#3" ) ; //  "abc"  // Truncating
v2 =      "abcde"_var.oconv( "R#3" ) ; //  "cde"
v2 =      "abcde"_var.oconv( "C#3" ) ; //  "abc"

v2 =      "ab"_var.oconv( "L#6" ) ; //  "ab␣␣␣␣"  // Padding
v2 =      "ab"_var.oconv( "R#6" ) ; //  "␣␣␣␣ab"
v2 =      "ab"_var.oconv( "C#6" ) ; //  "␣␣ab␣␣"

v2 =       var(42).oconv( "L(0)#5" ) ; //  "42000"  // Padding char (x)
v2 =       var(42).oconv( "R(0)#5" ) ; //  "00042"
v2 =       var(42).oconv( "C(0)#5" ) ; //  "04200"
v2 =       var(42).oconv( "C(0)#5" ) ; //  "04200"

// Dynamic array
v2 =       "f1^v1]v2"_var.oconv("L(_)#5") ; //  "f1___^v1___]v2___"_var

// Fail for non-ASCII (Should be 5)
v2 =      "🐱"_var.oconv("L#5").textwidth() ; //  3

// or
v2 =      oconv("abcd", "L#3" ) ; //  "abc" 

var=

strvar.oconv("T")

oconv "T" Justify and fold text.

e.g. T#20

Useful when outputting to terminal devices where spaces are used for alignment.

Split text into multiple fixed length lines by inserting spaces and TM chars.

ASCII only.

let v1 = "Have a nice day";
let v2 = v1.oconv("T#10") ; //  "Have a␣␣␣␣|nice day␣␣"_var
// or
let v3  = oconv(v1, "T#10") ; //  "Have a␣␣␣␣|nice day␣␣"_var 

expr

varnum.oconv("MR")

oconv "MR" Replace characters.

e.g. MRU

let v1 = "123/abC.";
var v2;
v2 = v1.oconv("MRL") ; //  "123/abc." // lcase
v2 = v1.oconv("MRU") ; //  "123/ABC." // ucase
v2 = v1.oconv("MRT") ; //  "123/Abc." // tcase
v2 = v1.oconv("MRN") ; //  "123"      // Return only digits
v2 = v1.oconv("MRA") ; //  "abC"      // Return only alphabetic
v2 = v1.oconv("MRB") ; //  "123abC"   // Return only alphanumeric
v2 = v1.oconv("MR/N") ; //  "/abC."   // Remove digits
v2 = v1.oconv("MR/A") ; //  "123/."   // Remove alphabetic
v2 = v1.oconv("MR/B") ; //  "/."      // Remove alphanumeric

var=

strvar.oconv("HEX")

oconv "HEX" Convert a string of chars to a string of pairs of hexadecimal digits.

strvar: A string. Numbers will be converted to strings for conversion. 1.2 -> "1.2" -> hex "312E32"

Dynamic array structure is not preserved. Field marks are converted to HEX as for all other bytes.

The size of the output is always precisely double that of the input.

This function is the exact inverse of iconv("HEX").

var v2;
v2 =      "ab01"_var.oconv( "HEX" ) ; //  "61" "62" "30" "31"
v2 =  "\xff\x00"_var.oconv( "HEX" ) ; //  "FF" "00"            // Any bytes are ok.
v2 =         var(10).oconv( "HEX" ) ; //  "31" "30"            // Uses ASCII string equivalent of 10 i.e. "10".
v2 =    "\u0393"_var.oconv( "HEX" ) ; //  "CE" "93"            // Greek capital Gamma in UTF8 bytes.
v2 =      "a^]b"_var.oconv( "HEX" ) ; //  "61" "1E" "1D" "62"  // Field and value marks.
// or
v2 =       oconv("ab01"_var, "HEX") ; //  "61" "62" "30" "31"

var=

strvar.iconv("HEX")

iconv "HEX" Convert a string of pairs of hexadecimal digits to a string of chars.

strvar: Must be a string of only hex digits 0-9, a-f or A-F.

return: A string if all input was hex digits otherwise "".

Dynamic array structure is not preserved. Any field marks prevent conversion.

This function is the exact inverse of oconv("HEX").

After prefixing a "0" to an odd sized input, the size of the output is always precisely half that of the input.

var=

varnum.oconv("MX")

oconv "MX" Convert a number to hexadecimal string.

"MX"
Convert and trim leading zeros e.g. oconv(1025, "MX") -> "401"
"MXn"
Pad with up to n leading zeros but do not truncate. e.g. oconv(1025, "MX8") -> "00000401"
"MXnT"
Pad and truncate to n characters. e.g. oconv(1025, "MX2") -> "01"

"n": Width. 0-9, A-G = 10 - 16.

varnum: A number or dynamic array of numbers. Floating point numbers are rounded to integers before conversion.

return: A string of hexadecimal digits or a dynamic array of the same. Elements that are not numeric are left untouched and unconverted.

Dynamic array structure is preserved.

Negative numbers are treated as unsigned 8 byte integers (uint64).

0 ->
"00"
1 ->
"01"
15 ->
"0F"
-1 ->
"FFFF" "FFFF" "FFFF" "FFFF" (8 x "FF")

This function is a near inverse of iconv("MX").

let v1 = "14.5]QQ]65535"_var.oconv("MX"); // "F]QQ]FFFF"_var
// or
let v2 = oconv("14.5]QQ]65535"_var, "MX");

var=

strvar.iconv("MX")

iconv "MX" Convert a hexadecimal string to number.

strvar: A string or dynamic array of up to 16 hex digits: 0-9, a-f, A-F.

return: An integer or dynamic array of integers. Invalid elements are converted to "".

Dynamic array structure is preserved.

Hex strings are converted to unsigned 8 byte integers (uint64)

Leading zeros are ignored.

"0" ->
0
"00" ->
0
"1" ->
1

Hex "FFFF" "FFFF" "FFFF" "FFFF" (8 x "FF") -> -1.

Hex "7FFF" "FFFF" "FFFF" "FFFF" -> The maximum positive integer: 9223372036854775805.

Hex "8000" "0000" "0000" "0000" -> The maximum negative integer: -9223372036854775808.

This function is the exact inverse of oconv("MX").

let v1 = "F]QQ]FFFF"_var.iconv("MX"); // "15]]65535"_var
// or
let v2 = iconv("F]QQ]FFFF", "MX");

var=

varnum.oconv("MB")

oconv "MB" Convert a number to a binary string of "1"s and "0"s,

varnum: If not numeric then no conversion is performed and the original value is returned.

let v1 = var(255).oconv("MB"); // 1111'1111
// or
let v2 = oconv(255, "MB");

var=

strvar.oconv("TX")

oconv "TX" Convert a dynamic array to text.

Convert dynamic arrays to standard text format.

Useful for using text editors on dynamic arrays.

FMs ->
\n after escaping any embedded NL
VMs ->
literal "\" \n
SMs ->
literal "\\" \n

etc.

// 1. Backslash in text remains backslash
let v1 = var(_BS).oconv("TX");     // _BS

// 2. Literal "\n" -> literal "\\n" (Double escape any escaped NL chars)
let v2 = var(_BS "n").oconv("TX"); // _BS _BS "n"

// 3. \n becomes literal "\n" (Single escape any NL chars)
let v3 = var(_NL).oconv("TX");     // _BS "n"

// 4. FM -> \n
let v4 = "f1^f2"_var.oconv("TX");  // "f1" _NL "f2"

// 5. VM -> "\" \n
let v5 = "v1]v2"_var.oconv("TX");  // "v1" _BS _NL "v2"

// 6. SM -> "\\" \n
let v6 = "s1}s2"_var.oconv("TX");  // "s1" _BS _BS _NL "s2"

// 7. TM -> "\\\" \n
let v7 = "t1|t2"_var.oconv("TX");  // "t1" _BS _BS _BS _NL "t2"

// 8. ST -> "\\\\" \n
let v8 = "st1~st2"_var.oconv("TX"); // "st1" _BS _BS _BS _BS _NL "st2"

var=

strvar.iconv("TX")

iconv "TX" Convert text to a dynamic array.

Convert standard text format to dynamic array.

Reverse of oconv("TX") above.

Dimensioned Array Construction
Use Function Description

dim d1;

Create an undimensioned array of vars.

Pending actual dimensions by redim, read, osread or split.

dim d1;

dim d1(nrows, ncols = 1);

Create a dimensioned array of vars.

Specify a fixed number of columns and rows. All vars are unassigned.

dim d1(10);
dim d2(10, 3);

dim d1 = d2; // Copy

Copy a dimensioned array.

Unassigned elements are copied as is.

dim d1 = {2, 4, 6, 8};
dim d2 = d1;

dim d1 = dim(); // Move

Save a dimensioned array created elsewhere.

Use C++ "move" semantics.

dim d1 = "f1^f2^f3"_var.split();

dim d1 = {"a", "b", "c" ...}; // Initializer list

Create a dimensioned array from a literal list.

All elements must be the same type, var, string, double, int, etc. All end up as vars which are flexible.

dim d1 = {1, 2, 3, 4, 5};
dim d2 = {"A", "B", "C"};

dim d1 = v1;

Initialise all elements of an dimensioned array.

To some single value. e.g. a var, "", 0 etc.

dim d1(10);
d1 = "";

d1.redim(nrows, ncols = 1)

Resize a dimensioned array.

To a different number of rows and columns.

Existing data will be retained. Any additional elements are unassigned.

Resizing rows to 0 clears all data.

Resizing cols to 0 clears all data and changes its status to "undimensioned".

dim d1;
d1.redim(10, 3);

d1.swap(d2)

Swap two arrays.

Either or both may be undimensioned.

dim d1(5);
dim d2(10);
d1.swap(d2);

Array Access
Use Function Description

var v1 = d1[rowno];
d1[rowno] = v1;

[row] Access and update dimensioned array elements.

Two dimensioned arrays can be traversed, columnwise then rowwise, using one dimension array access.

dim d1 = {1, 2, 3, 4, 5};
d1[3] = "X";
let v1 = d1[3]; // "X"

var v1 = d1[rowno, colno];
d1[rowno, colno] = v1;

[row, col] Access and update dimensioned array elements.

dim d1(10, 5);
d1 = "";
d1[3, 4] = "X";
let v1 = d1[3, 4]; // "X"

var=

d1.rows()

Get the number of rows in the dimensioned array

return: A count. Can be zero, indicating an empty or undimensioned array.

dim d1(5,3);
let v1 = d1.rows(); // 5

var=

d1.cols()

Get the number of columns in the dimensioned array

return: A count. 0 if the array is undimensioned.

dim d1(5,3);
let v1 = d1.cols(); // 3

var=

d1.join(delimiter = FM)

Get a delimited string concatenating all elements of a dimensioned array.

Unassigned elements on the end are omitted.

delimiter: Default is FM.

return: A string var.

dim d1 = {"f1", "f2", "f3"};
let v1 = d1.join(); // "f1^f2^f3"_var

Array Mutation
Use Function Description

d1.splitter(str1, delimiter = FM)

Create or update a dimensioned array using a string with delimiters.

If the dim array is undimensioned it will be dimensioned with the number of elements that the string has fields.

If the dim array is dimensioned and has more elements than there are fields in the string, the excess array elements are initialised to "". If the record has more fields than there are elements in the array, the excess fields are all left unsplit in the final element of the array.

Predimensioning arrays allows the efficient reuse of arrays in loops and ensures that all elements are assigned values, useful when reading records from DB files.

Using undimensioned arrays allows the efficient handling of arrays with a very variable number of elements. e.g. OS text files.

dim d1;
d1.splitter("f1^f2^f3"_var); // d1.rows() -> 3  //// Automatically dimensioned.
//
dim d2(10);
d2.splitter("f1^f2^f3"_var); // d2.rows() -> 10 /// Predimensioned. Excess elements become ""

d1.sorter(reverse = false)

Sort a dimensioned array.

The order of the elements is adjusted so that each element is <= the next.

reverse: If true, then the order is reversed. The default is false.

dim d1 = "2,20,10,1"_var.split(",");
d1.sorter();
let v1 = d1.join(","); // "1,2,10,20"_var

d1.reverser()

Reverse a dimensioned array.

The order of the elements is reversed.

dim d1 = "2,20,10,1"_var.split(",");
d1.reverser();
let v1 = d1.join(","); // "1,10,20,2"_var

d1.randomizer()

Randomise a dimensioned array.

The order of the elements is randomised.

dim d1 = "2,20,10,1"_var.split(",");
d1.randomizer();
let v1 = d1.join(","); // random

Array Conversion
Use Function Description

dim=

d1.sort(reverse = false)

Get a sorted copy of a dimensioned array.

dim=

d1.reverse()

Get a reversed copy of a dimensioned array;

dim=

d1.randomize()

Get a randomised copy of a dimensioned array.

Array DB I/O
Use Function Description

d1.write(dbfile, key)

Write a DB file record created from a dimensioned array.

Each element in the array becomes a separate field in the DB record.

Redundant trailing FMs are omitted.

dim d1 = "Client GD^G^20855^30000^1001.00^20855.76539"_var.split();
let file = "xo_clients", key = "GD001";
if (not deleterecord("xo_clients", "GD001")) {}; // Cleanup first
d1.write(file, key);
// or
write(d1 on file, key);

if

d1.read(dbfile, key)

Read a DB file record into a dimensioned array.

Each field in the database record becomes a single element in the array.

return: True if the record exists or false if not,

If the array is predimensioned then any excess array elements are initialised to "" and any excess record fields are left unsplit in the final array element. See dim splitter for more info.

If the array is not predimensioned (rows and cols = 0) then it will be dimensioned to have exactly the same number of rows as there are fields in the record being read.

dim d1(10);
let file = "xo_clients", key = "GD001";
if (not d1.read(file, key)) ... // d1.join() -> "Client GD^G^20855^30000^1001.00^20855.76539^^^^"_var
// or
if (not read(d1 from file, key)) ...

Array OS I/O
Use Function Description

if

d1.oswrite(osfilename, codepage = "")

Create an entire OS text file from a dimensioned array

Each element of the array becomes one line in the OS file delimited by \n

Any existing OS file is overwritten and replaced.

codepage: Optional: Data is converted from UTF8 to the required codepage/encoding before output. If the conversion cannot be performed then return false.

return: True if successful or false if not.

dim d1 = "aaa=1\nbbb=2\nccc=3\n"_var.split("\n");
if (not osremove("xo_conf.txt")) {}; // Cleanup first
let osfilename = "xo_conf.txt";
if (not d1.oswrite(osfilename)) ...
// or
if (not oswrite(d1 on osfilename)) ...

if

d1.osread(osfilename, codepage = "")

Read an entire OS text file into a dimensioned array.

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

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

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

return: True if successful or false if not.

If the first \n in the file is \r\n then the whole file will be split using \r\n as delimiter.

dim d1;
let osfilename = "xo_conf.txt";
if (not d1.osread(osfilename)) ... // d1.join("\n") -> "aaa=1\nbbb=2\nccc=3\n"_var0
// or
if (not osread(d1 from osfilename)) ...

Select Lists
Use Function Description

if

select(sortselectclause_or_filehandle = "")

Create an active select list using a natural language sort/select command.

This and all the following exoprog member functions work on an environment variable CURSOR.

Identical functions are available directly on plain var objects but vars have less functionality regarding dictionaries and environment variables which are built-in to exoprog.

return: True if an active select list was created, false otherwise.

In the following examples, various environment variables like RECORD, ID and MV are used instead of declaring and using named vars. In actual code, either may be freely used.

select("xo_clients by name by type with type 'A' 'B' and with balance between 0 and 2000");
if (readnext(ID)) ... ok

if

selectkeys(keys)

Create an active select list from a dynamic array of keys.

selectkeys("SB001^JB001^JB002"_var);
if (readnext(ID)) ... ok // ID -> "SB001"

if

hasnext()

Check if a select list is active.

if (hasnext()) ... ok

if

readnext(out key)

Get the next key from an active select list.

key[out]: A string. Typically the key of a db file record.

return: True if an active select list was available and the next key in the list was obtained.

selectkeys("SB001^JB001^JB002"_var);
if (readnext(ID)) ... ok // ID -> "SB001"

if

readnext(out key, out valueno)

Get the next key and value number pair from an active select list.

key[out]: A string. Typically the key of a db file record.

valueno[out]: Is only available in select lists that have been created by sort/select commands that refer to multi-valued db dictionary fields where db records have multiple values for a specific field. In this case, a record key will appear multiple times in the select list since each multivalue is exploded for the purpose of sorting and selecting. This can be viewed as a process of "normalising" multivalues so they appear as multiple records instead of being held in a single record.

return: True if an active select list was available and the next key in the list was obtained.

selectkeys("SB001]2^SB001]1^JB001]2"_var);
if (readnext(ID, MV)) ... ok // ID -> "SB001" // MV -> 2

if

readnext(out record, out key, out valueno)

Get the next record, key and value no from an active select list.

record[out]: Is only available in select lists that have been created with the final (R) option. Otherwise the record will be returned as an empty string and must be obtained using a db read() function.

key[out]: A string. Typically the key of a db file record.

valueno[out]: Is only available in select lists that have been created by sort/select commands that refer to multi-valued db dictionary fields where db records have multiple values for a specific field.

return: True if an active select list was available and the next key in the list was obtained.

select("xo_clients by name (R)");
if (readnext(RECORD, ID, MV)) ... ok;
assert(not RECORD.empty());

pushselect(out cursor)

Get a reference to the currently active select list and suspend it.

Allow another select list to be activated and used temporarily before the original select list is reactivated.

Multiple levels of pushselect/popselect can be used.

cursor[out]: A var that can be passed later on to the popselect() function to reactivate the saved list.

select("xo_clients by name");
var saved_xo_clients_cursor;
pushselect(saved_xo_clients_cursor);
//
// ... work with another select list ...
//
popselect(saved_xo_clients_cursor); // Reactivate the original select list.

popselect(cursor)

Re-activate a select list using a reference provided by pushselect().

cursor: A var created by the pushselect() function.

See pushselect() for more info.

clearselect()

Deactivate an active select list.

If no select list is active then nothing is done.

clearselect();

if

deleterecord(filename)

Delete multiple DB records using an active select list.

return: False if any records could not be deleted.

Contrast this function with the two argument "deleterecord(file, key)" function that deletes a single record.

if (select("xo_clients with type 'Q' and with balance between 0 and 100")) {
  if (deleterecord("xo_clients")) ...
}

if

deleterecord(dbfile, key)

Delete a single DB record.

let file = "xo_clients", key = "QQ001";
write("" on file, key);
if (not deleterecord(file, key)) ...
// or
write("" on file, key);
if (not file.deleterecord(key)) ...

if

savelist(listname)

Save the current active select list under a given name.

Select lists are saved in the DB file "lists". They are accessible to any Exodus process and remain until specifically deleted.

After saving, the list is no longer active and hasnext() will return false.

return: True if an active select list was saved, false if there was no active select list.

selectkeys("SB001^SB002"_var);
if (not savelist("my_list")) ...

if

getlist(listname)

Create an active select list using a saved select list of a given name.

A saved list is obtained from the "lists" file and activated. The list remains in the lists file for multiple use.

return: True if an active select list was successfully reactivated, otherwise false.

if (not getlist("my_list")) ...

if

deletelist(listname)

Remove a saved select list by name.

A saved list is deleted from the "lists" file.

if (not deletelist("my_list")) ...

if

formlist(filename_or_command, keys = "", fieldno = 0)

if

makelist(listname, keys)

Perform/Execute
Use Function Description

var=

perform(command_line)

Run an Exodus program/library.

Creates a new instance of an Exodus program library function object and calls its main() function using a command-like syntax, similar to that of running an OS executable program, and passes its arguments through the COMMAND and OPTIONS variables.

A performed program/library's main function should have no arguments otherwise they appear unassigned and a segfault or core dump may occur.

The Exodus program class member variables of a performed or executed program/library are all, as might be expected, initially unassigned unless specifically initialised inline. Note that this is not the same as calling a program library function (using function call syntax and round brackets funcx()), where the program/library/function's member variables are initially unassigned but retain their state between calls.

command_line: Used to initialise the COMMAND, SENTENCE and OPTIONS environment variables of the performed exodus program/library. Analogous to passing function arguments. The first word of command_line is used as the name of the program/library to be loaded and run.

return: Whatever the program returns from main() or passes as an argument to stop(). If the program terminates abnormally then it will return "" and lasterror() will contain some error message. The return value may be ignored so there is no need so wrap perform statements in if clauses to avoid compiler warnings.

throw: All the various runtime errors based on VarError e.g. VarUnassigned.

environment: The following environment variables are initialised on entry to the main function of the program/library and are preserved untouched (actually restored) in the calling program.

  • COMMAND, OPTIONS, SENTENCE.
  • RECUR0, RECUR1, RECUR2, RECUR3, RECUR4 to "".
  • ID, RECORD, MV, DICT initialised to "".
  • LEVEL is incremented by one.
  • All other environment variables are shared between the caller and callee. There is essentially only one environment in any one process or thread.
  • CURSOR Any active select list in CURSOR is passed to the performed program/library and can be consumed by it. Conversely any active select list created by the performed program/library will be returned to the calling program. In other words, both the performing and the performed programs/libraries share a single active select list environment. This is different from execute() where the executed program/library gets its own private active select list, initially inactive.

Exodus program/library/functions may also be called directly using conventional function calling syntax. To call an exodus program/library called progname using either the syntax "call progname(args...);" or "var v1 = progname(args...);" you must "#include <progname.h>" after the "programinit()" or "libraryinit()" lines in your program/library. See library.h for more info.

var=

execute(command_line)

Run an exodus program/library.

Identical to perform() but any currently active select list in the calling program/library is not accessible to the executed program/library and is preserved in the calling [program as is. Any select list created by the executed library is discarded when it terminates.

chain(command_line)

Close the current program and perform another one.

Similar to perform() except that the current program closes first and all environment variables carry forward unchanged.

var=

libinfo(libname)

Check if a lib exists.

Can be checked before perform/execute to avoid errors.

Currently it does not check if the library is actually loadable.

return: osfile info.

Program Termination
Use Function Description

stop(result = "")

Stop the current exodus program/library normally.

Either return to the performing or executing parent exodus program/library, or exit to the OS if none.

result: Optional. It will be used as the return value of a parent program's perform() or execute() function, or if none, and therefore returning to the OS, it will be output to stdout if non-numeric or, if numeric, used as the exit status.

abort(message = "")

Abort the current exodus program/library.

Similar to stop but if exiting to the OS then the default exit status is 1.

message: Optional. If exiting to the OS then it will be output to stderr or, if numeric, used as the exit status.

abortall(message = "")

Abort the current exodus program/library.

Similar to abort but if exiting to the OS then the default exit status is 2.

DB File Dictionaries
Use Function Description

var=

calculate(dictid)

Get DB record field values given field name only.

Use a dictionary file that contains info sufficient to either extract or calculate the required value.

  1. Read fieldinfo from the current DICT file using readc() for caching.
  2. Use the fieldinfo to:
    • Either extract a specific field number from the current RECORD/ID/MV environment variables.
    • Or call a dictionary function library to calculate the result.

var=

calculate(dictid, dictfile, id, record, mv = 0)

Get DB record field values given name and data.

Same as the one argument version of calculate() but RECORD/ID/MV are provided as arguments instead of being hard coded.

var=

xlate(filename, key, fieldno_or_name, mode)

Read DB field using field number or name.

  1. Read a record from a given file and key using readc() for caching.
  2. Extracts the given field number or calls calculate(dictid...) if non-numeric.

filename: The file to read.

key: The key of the record to read.

fieldno_or_name: The field to return.

nn
Field number nn.
0
The record key (ID).
""
The whole record (RECORD)
dictid
The function calculate(dictid) will be called.

mode: If the record does not exist.

"X"
Return ""
"C"
Return the key.

MV: Environment variable. Will be used to select a particular value if not zero, or all values if zero.

I/O Conversion
Use Function Description

var=

oconv(input, conversion)

iconv/oconv "[...]"

ExoProgram's iconv/oconv functions have access to ExoProgram's environment variables like BASEFMT, DATEFMT and TZ and have the ability to call custom functions like "[funname,args...]"

[NUMBER] // built-in. See doc below.

[DATE] // built-in. See doc below.

[DATEPERIOD] e.g. [DATEPERIOD,1] [DATEPERIOD,1,12]

[DATETIME] e.g. [DATETIME,4*,DOS] [DATETIME,4*,MTS] [DATETIME,4*]

[TIME2] e.g. [TIME2,MT] [TIME2,MTS] [TIME2,MTS48]

var=

iconv(input, conversion)

Ioconv Date/Time
Use Function Description

var=

iconv|oconv(var, "[DATE]")

iconv/oconv "[DATE]"

Use iconv/oconv code "[DATE,args]" when you want date conversion to depend on the environment variable DATEFMT, particularly its American/International setting. Otherwise use ordinary "D" conversion codes directly for slightly greater performance.

var: [oconv] An internal date (a number).

return: [oconv] A readable date in text format depending on "[DATE,args]" e.g. "31 DEC 2020" "31/12/2020" "12/31/2020"

var: [iconv] A date in text format as above.

return: [iconv] An internal date (a number) or "" if the input could not be understood as a valid date.

args: If args is empty then DATEFMT is used as the conversion code. If args starts with "D" then args is used as the conversion codes but any E option in DATEFMT is appended. If args does not start with "D" then args are appended to DATEFMT, a "Z" option is appended, and the result used as the conversion code. A "*" option is equivalent to a second "Z" option.

If you are calling iconv/oconv in code and DATEFMT is adequate for your needs then pass it directly as a function argument e.g. 'var v1 = iconv|oconv(v2, DATEFORMAT);' instead of indirectly like 'var v1 = iconv|oconv(v2, "[DATE]");'.

DATEFMT = "D/E";
let v1 = iconv("JAN 9 2025", "D");
assert(oconv(v1, "[DATE]"   ) == " 9/ 1/2025");  // "D/EZ" or "[DATE,D]" equivalent assuming D/E in DATEFMT (replace leading zeros with spaces)
assert(oconv(v1, "[DATE,4]" ) == " 9/ 1/2025");  // "D4Z"  equivalent assuming D/E in DATEFMT (replace leading zeros with spaces)
assert(oconv(v1, "[DATE,*4]") == "9/1/2025");    // "D4ZZ" equivalent assuming D/E in DATEFMT (trim leading zeros and spaces)
assert(oconv(v1, "[DATE,*]" ) == "9/1/2025");    // "DZZ"  equivalent assuming D/E in DATEFMT (trim leading zeros and spaces)

var=

iconv|oconv(var, "[NUMBER]")

iconv/oconv "[NUMBER]"

Use iconv/oconv "[NUMBER,args]" either when your numbers have currency or unit code suffixes or when you want number conversion to depend on the environment variable BASEFMT to determine thousands separator and decimal point. Otherwise use ordinary "MD" conversion codes directly for slightly greater performance.

Formatting for numbers with optional currency code/unit suffix and is sensitive to the International or European setting in BASEFMT regarding use of commas or dots for thousands separators and decimal points.

Primarily used for oconv() but can be used in reverse for iconv.

var: A number with an optional currency code or unit suffix. e.g. "12345.67USD"

return: A formatted number with thousands separated conventionally e.g. "12.345.67USD".

iconv/oconv("[NUMBER]") oconv leaves ndecimals untouched as in the input. iconv see below.

iconv/oconv("[NUMBER,2]") Specified number of decimal places

iconv/oconv("[NUMBER,BASE]") Decimal places as per BASEFMT

iconv/oconv("[NUMBER,*]") Leave decimal places untouched as in the input

iconv/oconv("[NUMBER,X]") Leave decimal places untouched as in the input

iconv/oconv("[NUMBER,2Z]") Z (suppress zero) combined with any other code for oconv results in empty output "" instead of "0.00" in case of zero input.

Empty input "" gives empty output "".

All leading, trailing and internal spaces are removed from the input.

A trailing currency or unit code is ignored and returned on output.

An exodus number is an optional leading + or - followed by one or more decimal digits 0-9 with a single optional decimal point placed anywhere.

If the input is non-numeric then "" is returned and STATUS set to 2. In the case of oconv with multiple fields or values each field or value is processed separately but STATUS is set to 2 if any are non-numeric.

iconv removes and oconv adds thousand separator chars. The thousands separator is "," if BASEFMT starts with "MD" or "." if it starts with "MC".

oconv:

Add thousands separator chars and optionally standardise the number of decimal places.

Multiple numbers in fields, values, subvalues etc. can be processed in one string.

Any leading + character is preserved on output.

Z suppresses zeros and returns empty string "" instead.

Special format "[NUMBER,ndecs,move_ndecs]": move_ndecs causes decimal point to be shifted left if positive or right if negative.

var v1 = oconv("1234.5USD", "[NUMBER,2]"); // "1,234.50USD" // Comma added and decimal places corrected.
iconv: Remove all thousands separator chars and optionally standardise the number of decimal places. If ndecs is not specified in the "[NUMBER]" pattern then ndecs is taken from the current RECORD using dictionary code NDECS if DICT is available otherwise it uses ndecs from BASEFMT. iconv only handles a single field/value. Optional prefix of "1/" or "/" causes the reciprocal of the number to be used. e.g. "1/100" or "/100" -> "0.01".
var v1 = iconv("1,234.5678USD", "[NUMBER]"); // "1234.57USD" // Comma removed

var=

amountunit(input0, out unitx)

Parse amount+currency code string.

Split amount+currency code/unit string into number and currency code/unit.

var: "123.45USD"

return: e.g. "123.45"

unitx[out]: e.g. "USD"

var=

amountunit(input0)

Time/Date Utilities
Use Function Description

var=

timedate2()

Get text of date and time.

In users time zone

e.g. "2MAR2025 11:52AM"

Offset from UTC by TZ seconds.

getdatetime(out user_date, out user_time, out system_date, out system_time, out UTC_date, out UTC_time)

Get current user, server and UTC dates and times.

User date and time is determined by adding the environment variable TZ.f(1)'s TZ offset (in seconds) to UTC date/time obtained from the operating system.

"system" date and time is normally the same as UTC date/time and is determined by adding the environment variable TZ.f(2)'s TZ offset (in seconds) to UTC date/time obtained from the operating system.

var=

elapsedtimetext()

Get text of elapsed time.

Since environment variable TIMESTAMP.

TIMESTAMP is initialised with ostimestamp() at program/thread startup.

TIMESTAMP can be updated using ostimestamp() as and when desired.

var v1 = elapsedtimetext(); // e.g. "< 1ms"

var=

elapsedtimetext(timestamp1, timestamp2)

Get text of elapsed time.

Between two given timestamps

Warning: Use ostimestamp() not ostime(). The first is in days and the second is in seconds.

let v1 = elapsedtimetext(0, 0.55);  // "13 hours, 12 mins"
let v2 = elapsedtimetext(0, 0.001); // "1 min, 26 secs"

Terminal I/O Utilities
Use Function Description

note(msg, options, io response)

Output a message to stdout and optionally request input.

If input is requested but stdin is not a terminal then set the response to "" and continue.

options: R = Response requested. C upper case response.

var response;
// call note("Enter something", "RC", response);

note(msg)

Output a message to stdout.

call note("Hello world.");

var=

decide(question, options = "")

Input user selection from a list of options.

If stdin is not a terminal, set the response to "" and continue.

return: The chosen option (value not number) or "" if the user cancelled.

var=

decide(question, options, out reply, defaultreply = 1)

Input user selection from a list of options.

If stdin is not a terminal set the response to the default value, or "" if none, and continue.

defaultreply: A default option if the user presses Enter.

reply[out]: The option number that the user chose or "" if they cancelled.

return: The chosen option (value not number) or "" if the user cancelled.

if

esctoexit()

Check for user pause or cancel.

If stdin is a terminal, check if a key has been pressed and, if so, pause execution and ask the user to confirm if they want to escape/cancel or resume processing.

return:

True
A key has been pressed and the user chose not to resume.
False
stdif is not a terminal, no key has been pressed, or the user chose to resume.

var=

AT(code)

Get a string to control terminal operation.

return: A string to be output to the terminal in order to accomplish the desired operation.

The terminal protocol is xterminal.

code:

n
Position the cursor at column number n (1 based).
0
Position the cursor at the first column (1).
-1
Clear the screen and home the cursor.
-2
Position the cursor at the top left home (x, y = 1, 1).
-3
Clear from the cursor at the end of screen.
-4
Clear from cursor to end of line.
-40
Position the cursor at columnno 0 and clear to end of line.

var=

AT(x, y)

Get a terminal cursor positioning string.

return: A string to be output to the terminal to position the cursor at the desired screen x and y position.

The terminal protocol is xterminal.

if

getcursor(out cursor, delayms = 3000, max_errors = 0)

Get the position of the terminal cursor.

cursor[out]: If stdin is a terminal, an FM delimited string containing the x and y coordinates of the current terminal cursor.

x and y are 1 based, not 0 based.

If stdin is not a terminatl then an empty string "" is returned.

The cursor additionally contains a third field which contains the delay in ms from the terminal.

The FM delimited string returned can be later passed to setcursor() to reposition the cursor back to its original position or it can be parsed and used accordingly.

delayms: Default 3000ms. The maximum time to wait for terminal response.

max_errors: Default is 0. If not zero, reset the number of times to error before automatically disabling getcursor(). max_errors is initialised to 3. If negative then max_errors has the the effect of disabling all future calls to getcursor().

In case the terminal fails to respond correctly within the required timeout, or is currently disabled due to too many failures, or has been specifically disabled then the returned "cursor" var contains a 4th field:

TIMEOUT
The terminal failed to respond within the timeout.
READ_ERROR
Failed to read terminal response.
INVALID_RESPONSE
Terminal response invalid.
SETUP_ERROR
Terminal setup failed.
DISABLED
Terminal is disabled due to more errors than the maximum currently set.

var cursor;
if (isterminal() and not getcursor(cursor)) ... // cursor becomes something like "1^20^0.012345"_var

var=

getcursor()

Get the position of the terminal cursor.

For more info see the main getcursor() function above.

let cursor = getcursor(); // If isterminal() then cursor becomes something like "0^20^0.012345"_var

setcursor(cursor_coordinates)

If stdin is a terminal, position the cursor at x and y as per the given coordinates.

cursor_coordinates: An FM delimited string containing the x and y coordinates of the terminal cursor as can be obtained by getcursor().

if (isterminal()) {
    let cursor = getcursor(); // Save the current cursor position.
    TRACE(cursor)             // Show the saved cursor position.
    print(AT(0,0));           // Position the cursor at 0,0.
    setcursor(cursor);        // Restore its position
}

Array Utilities
Use Function Description

var=

invertarray(input, pad = false)

Dynamic array fields become values and vice versa

return: The inverted dynamic array.

pad: If true then on return, all fields will have the same number of values with superfluous trailing VMs where necessary.

let v1 = "a]b]c^1]2]3"_var;
let v2 = invertarray(v1); // "a]1^b]2^c]3"_var

sortarray(io array, fns = "", order = "")

Sort parallel fields of multivalues of dynamic arrays

fns: VM separated list of field numbers to sort in parallel based on the first field number

order:

AL
Ascending - Left Justified (Alphabetic)
DL
Descending - Left Justified (Alphabetic)
AR
Ascending - Right Justified (Numeric/Natural)
DR
Descending - Right Justified (Numeric/Natural)

var v1 = "f1^10]20]2]1^ww]xx]yy]zz^f3^f4"_var;  // fields 2 and 3 are parallel multivalues and currently unordered.
sortarray(v1, "2]3"_var, "AR"); // v1 -> "f1^1]2]10]20^zz]yy]ww]xx^f3^f4"_var

Record Locking
Use Function Description

if

lockrecord(filename, io file, keyx, unused, waitsecs = 0, allowduplicate = false)

if

lockrecord(filename, io file, keyx)

if

unlockrecord(filename, io file, key)

if

unlockrecord()