k9Simples.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<!-- April 15, 2023

Copyright (C) 2020 John Estrada -->
<title>Shakti (k9) tutorial</title>

<meta name="description" content="k programming tutorial, Shakti (k9) tutorial">
<meta name="keywords" content="Shakti (k9) tutorial">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="texi2any">
<meta name="viewport" content="width=device-width,initial-scale=1">

<link href="#Top" rel="start" title="Top">
<link href="#Introduction" rel="next" title="Introduction">
<style type="text/css">
<!--
/* spacing */


a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
span:hover a.copiable-anchor {visibility: visible}
ul.no-bullet {list-style: none}
.cartouche{
    border: none;
    background: lightgrey;
}

table, th, td{
  table-layout: auto;
  border-collapse: collapse;
  border: 1px solid blue;
  font-family: monospace; 
}

th, td {
  padding: 5px;     
  font-family: monospace; 
}

tr:nth-child(1) {
/*    background-color:lightsteelblue; // Replace it with your desired color */
}

.menu{
    border: none;
}

table.menu td{ 
    padding: 1px;
    border: none;
    font-family: sansserif;
}

table.menu th{ 
    padding: 1px;
    border: none;
    font-family: sansserif;
}


-->
</style>


</head>

<body lang="en">
<h1 class="settitle" align="center">Shakti (k9) tutorial</h1>


<div class="top" id="Top">
<div class="header">
<p>
Next: <a href="#Introduction" accesskey="n" rel="next">Introduction</a> &nbsp; </p>
</div>
<span id="k9_003a-Manual"></span><h1 class="top">k9: Manual</h1>
<p>This manual is for Shakti (k9) build 2023.03.09.<br>
</p>
<p>The Shakti programming language is the work of Arthur Whitney and the team at Shakti.  The language comes from a lineage of similar languages going back to APL.  It&rsquo;s also known as k9 given the similarities to k, k2, ..., k6, k7 and the fact that Arthur also wrote those.  k9 is still under development so expect a bit of syntax change and likely even more improvements.
</p>
<p>Learning k9 means code like <code>{x@(!#x)+\!#y}</code> is clear and actually prefered to something much longer and verbose.  You&rsquo;ll have to go a bit down the rabbit hole before it starts to come together but once it does you&rsquo;ll probably be happy you gave it a chance and end up learning a few things.  You&rsquo;ll understand how fast k9 can be in processing and analyzing data and how terse code is less likely to contain errors.  Unfortunately you will be less likely to be content using more bloated and slow frameworks.  
</p>
<p>Alas this manual is not as elegant as the k9 language in that the text version of this document is almost as big as the binary of the language.  
</p>
<p>The built-in reference screen (<code>\</code>) containing all the k9 commands.
</p>
<p><tt>select&nbsp;<a href="#count">count</a>&nbsp;<a href="#first">first</a>&nbsp;last&nbsp;min&nbsp;max&nbsp;sum&nbsp;avg&nbsp;var&nbsp;dev&nbsp;..&nbsp;by&nbsp;..</tt><br>
<tt>in&nbsp;n_(rand)&nbsp;n@(multiply)&nbsp;n?(divide)&nbsp;n@n?(bar)</tt><br>
<tt></tt><br>
<tt>Verb&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;monad&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Ad<a href="#Verb">verb</a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Type&nbsp;</tt><br>
<tt>+&nbsp;+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'&nbsp;<a href="#each">each</a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#char">char</a>&nbsp;&nbsp;&nbsp;&quot;&nbsp;ab&quot;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt><br>
<tt>-&nbsp;-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/&nbsp;<a href="#cover">over</a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;sym&nbsp;&nbsp;&nbsp;&nbsp;``ab</tt><br>
<tt>*&nbsp;*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\&nbsp;<a href="#cscan">scan</a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#bool">bool</a>&nbsp;&nbsp;&nbsp;011b&nbsp;&nbsp;&nbsp;</tt><br>
<tt>%&nbsp;<a href="#div">div</a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#int">int</a>&nbsp;&nbsp;&nbsp;&nbsp;2&nbsp;3&nbsp;4</tt><br>
<tt>!&nbsp;<a href="#mod">mod</a>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#where">where</a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#System">System</a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;float&nbsp;&nbsp;2&nbsp;3e4&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt><br>
<tt>&amp;&nbsp;&amp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#flip">flip</a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#load">\l</a>&nbsp;load&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;-fixed&nbsp;&nbsp;2.0&nbsp;3.4</tt><br>
<tt>|&nbsp;|&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#reverse">reverse</a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#timing">\t</a>&nbsp;time&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;-locus&nbsp;&nbsp;-74::40.7&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt><br>
<tt>&lt;&nbsp;&lt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#asc">asc</a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#variables">\v</a>&nbsp;vars&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#z_002ed">z.d</a>&nbsp;<a href="#date">date</a>&nbsp;&nbsp;&nbsp;2001.02.03&nbsp;&nbsp;</tt><br>
<tt>&gt;&nbsp;&gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#desc">desc</a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\w&nbsp;work&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#z_002et">z.t</a>&nbsp;<a href="#time">time</a>&nbsp;&nbsp;&nbsp;12:34:56.789</tt><br>
<tt>=&nbsp;=&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;freq&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#z_002eT">z.T</a>&nbsp;<a href="#datetime">datetime</a></tt><br>
<tt>~&nbsp;~&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;~&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt><br>
<tt>,&nbsp;,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;,</tt><br>
<tt>#&nbsp;<a href="#take">take</a>&nbsp;&nbsp;&nbsp;<a href="#count">count</a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;I/O&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Class</tt><br>
<tt>_&nbsp;<a href="#drop">drop</a>&nbsp;&nbsp;&nbsp;<a href="#first">first</a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0'&nbsp;line&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Expression">expr</a>&nbsp;&nbsp;&nbsp;:2+a</tt><br>
<tt>^&nbsp;<a href="#cut">cut</a>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#sort">sort</a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1'&nbsp;char/stdout&nbsp;&nbsp;&nbsp;&nbsp;<a href="#User-Functions">func</a>&nbsp;&nbsp;&nbsp;f[a]&nbsp;2+a</tt><br>
<tt>@&nbsp;@&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#type">type</a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2'&nbsp;data/stderr&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt><br>
<tt>?&nbsp;<a href="#find">find</a>&nbsp;&nbsp;&nbsp;unique&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*3'&nbsp;set&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#List">list</a>&nbsp;&nbsp;&nbsp;(2;3.4)&nbsp;&nbsp;</tt><br>
<tt>$&nbsp;<a href="#parse">parse</a>&nbsp;&nbsp;<a href="#str">str</a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*4'&nbsp;get&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Dictionary">dict</a>&nbsp;&nbsp;&nbsp;{a:2&nbsp;3}</tt><br>
<tt>.&nbsp;<a href="#dict">dict</a>&nbsp;&nbsp;&nbsp;<a href="#value">value</a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*5'&nbsp;<a href="#ffi">ffi</a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Tables">table</a>&nbsp;&nbsp;[a:2&nbsp;3]</tt><br>
</p>

<ul class="section-toc">
<li><a href="#Introduction" accesskey="1">Introduction</a></li>
<li><a href="#Verb" accesskey="2">Verbs</a></li>
<li><a href="#Adverb" accesskey="3">Adverbs</a></li>
<li><a href="#Noun" accesskey="4">Noun</a></li>
<li><a href="#List" accesskey="5">List</a></li>
<li><a href="#Dictionary" accesskey="6">Dictionary</a></li>
<li><a href="#User-Functions" accesskey="7">User-defined Functions</a></li>
<li><a href="#Expression" accesskey="8">Expression Evaluation</a></li>
<li><a href="#Named-Functions" accesskey="9">Named Functions</a></li>
<li><a href="#Knit-Functions">Knit Functions</a></li>
<li><a href="#I_002fO">I/O and Interface</a></li>
<li><a href="#FF">Foreign Functions</a></li>
<li><a href="#Tables">Tables</a></li>
<li><a href="#kSQL">kSQL</a></li>
<li><a href="#System">System</a></li>
<li><a href="#Control-Flow">Control Flow</a></li>
<li><a href="#Temporal-Functions">Temporal Functions</a></li>
<li><a href="#Errors">Errors</a></li>
<li><a href="#Examples">Examples</a></li>
<li><a href="#Benchmark">Benchmark</a></li>
<li><a href="#Conclusion">Conclusion</a></li>
</ul>
<hr>
<div class="chapter" id="Introduction">
<div class="header">
<p>
Next: <a href="#Verb" accesskey="n" rel="next">Verbs</a>, Previous: <a href="#Top" accesskey="p" rel="prev">k9: Manual</a>, Up: <a href="#Top" accesskey="u" rel="up">k9: Manual</a> &nbsp; </p>
</div>
<span id="Introduction-1"></span><h2 class="chapter">1 Introduction</h2>
<p>The k9 programming language is designed primarily for the analysis of data.  It may surprise new users with two rather different paradigms, (1) fast data analysis and (2) concise syntax.  After you become familiar with the language, these features will both seem normal and intuitive.  Also, going back to slow and verbose programming will be surprisingly difficult.
</p>
<ul class="section-toc">
<li><a href="#Going-fast" accesskey="1">Going fast</a></li>
<li><a href="#Going-concise" accesskey="2">Going concise</a></li>
<li><a href="#Get-k9_002e" accesskey="3">Get k9.</a></li>
<li><a href="#Help-_002f-Info-Card" accesskey="4">Help / Info Card</a></li>
<li><a href="#rlwrap" accesskey="5">rlwrap</a></li>
<li><a href="#REPL" accesskey="6">REPL</a></li>
<li><a href="#Simple-example" accesskey="7">Simple example</a></li>
<li><a href="#Document-formatting-for-code-examples" accesskey="8">Document formatting for code examples</a></li>
<li><a href="#k9-idiosyncracies" accesskey="9">k9 idiosyncracies</a></li>
</ul>
<div class="section" id="Going-fast">
<h3 class="section">1.1 Going fast</h3>
<p>Imagine you have a small, on-disk, 100 million row database containing a time-series with two float values at each time.  Additionally this data could be split in three different tables covering different measurements.  Here&rsquo;s how fast k9 can read in the data from disk and compute a statistic, average difference over each table, which uses each and every row.
</p>
<p><b>This section requires 2: a feature only in the enterprise version of Shakti.  If that is not available then use the section below with 1:</b>
</p>
<div class="example">
<pre class="example"> bash-3.2$ ./k
 2021.xx.xx 17GB 4core (c) shakti
 \t q:2:`q;{select s:avg a-b from x}'q[!q]
884
</pre></div>

<p>That&rsquo;s 884 ms to read the data in from disk and compute over all the 100 million values.  The data read is the biggest bit.  If the data were already in memory then the computation would be  faster:
</p>
<div class="example">
<pre class="example"> \t {select s:avg a-b from x}'q[!q]
217
</pre></div>

<p>217 ms, not bad for 100 million calculations.
</p>
<p>The code to generate the on-disk database is presented below.  Speed of course will depend on your hardware so times will vary.
</p>
<div class="example">
<pre class="example"> nf:d+*|d:(|-d),d:683 954 997 1000;
 T:^`t ?[;_8.64e7]@
 B:100++\1e-2*-3+nf bin/:?[;*|nf]@
 S:?[;1e-2*2,2,8#1]@
 L:{select t,b,a:b+s from +`t`b`s!(T;B;S)@'x}
 q:`eurusd`usdjpy`usdchf!L'_60e6 20e6 20e6
 `q 2:q
</pre></div>

<p><b>This section requires 1: a feature in all versions of Shakti.</b>
</p>
<div class="example">
<pre class="example"> bash-3.2$ ./k
 2021.xx.xx 17GB 4core (c) shakti
 \t select s:avg a-b from q:`csv?1:&quot;q.csv&quot;
832
</pre></div>

<p>That&rsquo;s 832 ms to read the data in from disk and compute over all the 10 million values.  The data read and csv conversion process are the biggest bits.  
</p>
<p>Here is the code to generate the q.csv on-disk file.  Note in this example only 10 million lines are generated versus the 100 million lines in the previous example using 2:
</p>
<div class="example">
<pre class="example"> nf:d+*|d:(|-d),d:683 954 997 1000;
 T:^`t ?[;_8.64e7]@
 B:100++\1e-2*-3+nf bin/:?[;*|nf]@
 S:?[;1e-2*2,2,8#1]@
 L:{select t,b,a:b+s from +`t`b`s!(T;B;S)x'}
 q:L[_10e6]
 &quot;q.csv&quot;1:`csv@q
&quot;q.csv&quot;
</pre></div>

</div>
<div class="section" id="Going-concise">
<h3 class="section">1.2 Going concise</h3>

<p>The k9 language is more closely related to mathematics syntax than most programming lanauges.  It requires the developer to learn to &ldquo;speak&rdquo; k9 but once that happens most find an ability to speak quicker and more accurately in k9 than in other languages.  At this point an example might help.
</p>
<p>In mathematics, &ldquo;3+2&rdquo; is read as &ldquo;3 plus 2&rdquo; as you learn at an early age that &ldquo;+&rdquo; is the &ldquo;plus&rdquo; sign.  For trival operations like arithmetic most programming languages use symbols also.  When moving beyond arithmetic, most programming lanauges switch to words while k9 remains with symbols.  As an example, to determine the distinct values of a list most programming languages might use a syntax like <code>distinct()</code> while k9 uses <code>?</code>.  This requires the developer to learn how to say a number of symbols but once that happens it results in much shorter code that is quicker to write, easier to inspect, and easier to maintain.  
</p>
<p>This should not be surprising. In arithmetic, which do you find easier to understand?
</p>
<div class="example">
<pre class="example">/ math with text
Three plus two times open parenthesis six plus fourteen close parenthesis

/ math with symbols
3+2*(6+14)
</pre></div>

<p>In code, if you&rsquo;re new to k9 then it&rsquo;s unlikley you can understand the second example.
</p>
<div class="example">
<pre class="example">/ code with text
x = (0,12,3,11,3);y=5;
distinct_x = list(set(x));
sorted(i for i in distinct_x if i &gt;= y)

/ code with symbols
x:0 12 3 11 3;y:5;
z@&amp;y&lt;z:?x
</pre></div>

<p>When you first learned arithmetic you likely didn&rsquo;t have a choice.  Now you have a choice whether or not you want to learn k9.  If you give it a try, then you&rsquo;ll likely get it quickly and move onto the power phase fast enough that you&rsquo;ll be happy you gave it a chance.
</p>
</div>
<div class="section" id="Get-k9_002e">
<h3 class="section">1.3 Get k9.</h3>

<p><a href="https://shakti.com">https://shakti.com</a>
</p>
<p>k9 is available in two versions, standard (under download) and enterprise.  The enterprise version has additional features indicated on the k9 help page and also indicated in this tutorial.
</p>
<p>Once downloaded you will need to change the file mode with the following commmand
</p>
<div class="example">
<pre class="example"> chmod +x k
</pre></div>

<p>On the mac if you then attempt to run this file you likely won&rsquo;t succeed due to MacOS security.  You&rsquo;ll need to go to &ldquo;System Preferences...&rdquo; and then &ldquo;Security and Privacy&rdquo; and select to allow this binary to run.  (You&rsquo;ll have to have tried and failed to have it appear here automatically.)
</p>
<p>On linux (and macos if you have installed npm) one can download k from the command line via
</p>
<div class="example">
<pre class="example"> npm i @kparc/k -g
</pre></div>

</div>
<div class="section" id="Help-_002f-Info-Card">
<h3 class="section">1.4 Help / Info Card</h3>
<p>Typing <code>\</code> in a terminal window gives you a concise overview of the language.  This document aims to provide details to beginning user where the help screen is a bit too terse.  Some commands are not available in the basic version and thus marked with an asterisk, eg. *4: https get.
</p>
<div class="format">
<pre class="verbatim">select count first last min max sum avg var dev .. by ..
in n_(rand) n@(multiply) n?(divide) n@n?(bar)

Verb     monad        Adverb            Type 
+ +                   ' each            char   &quot; ab&quot;          
- -                   / over            sym    ``ab
* *                   \ scan            bool   011b   
% div                                   int    2 3 4
! mod    where        System            float  2 3e4      
&amp; &amp;      flip         \l load          -fixed  2.0 3.4
| |      reverse      \t time          -locus  -74::40.7      
&lt; &lt;      asc          \v vars       z.d date   2001.02.03  
&gt; &gt;      desc         \w work       z.t time   12:34:56.789
= =      freq                       z.T datetime
~ ~      ~                                      
, ,      ,
# take   count        I/O               Class
_ drop   first        0' line           expr   :2+a
^ cut    sort         1' char/stdout    func   f[a] 2+a
@ @      type         2' data/stderr              
? find   unique      *3' set            list   (2;3.4)  
$ parse  str         *4' get            dict   {a:2 3}
. dict   value       *5' ffi            table  [a:2 3]</pre></div>

</div>
<div class="section" id="rlwrap">
<h3 class="section">1.5 rlwrap</h3>
<p>Although you only need the <samp>k</samp> binary to run k9 most will also install rlwrap, if not already installed, in order to get command history in a terminal window.  rlwrap is &ldquo;Readline wrapper: adds readline support to tools that lack it&rdquo; and allows one to arrow up to go through the command buffer history.
</p>
<p>In order to start k9 you should either run <samp>k</samp> or <samp>rlwrap k</samp> to get started.  Here I will show both options but one should run as desired.  In this document lines with input are shown with a leading space and output will be without.  In the examples below the user starts a terminal window in the directory with the <samp>k</samp> binary file.  Then the users enters <kbd>rlwrap ./k <span class="key">RET</span></kbd>.  k9 starts and displays the date of the build, (c), and shakti and then listens to user input.  In this example I have entered the command to exit k9, <kbd>\\</kbd>.  Then I start k9 again without rlwrap and again exit the session.
</p>
<div class="example">
<pre class="example"> rlwrap ./k
Sep 13 2020 16GB (c) shakti
 \\

 ./k
Sep 13 2020 16GB (c) shakti
 \\
</pre></div>

</div>
<div class="section" id="REPL">
<h3 class="section">1.6 REPL</h3>
<p>k9 runs as a read, evaluation, print loop (REPL).  This means that one either programs in an interactive programming environment (eg. a shell/terminal window) or by running a script.  There is no reason to compile code into an executable.  
</p>
</div>
<div class="section" id="Simple-example">
<h3 class="section">1.7 Simple example</h3>

<p>Here I will start up k9, perform some trivial calculations, and then close the session.  After this example it will be assumed the user will have a k9 session running and working in repl mode.  Comments (<code>/</code>) will be added to the end of lines as needed.  One can review <a href="#plus">plus</a>, <a href="#where">where</a>, <a href="#floor">floor</a> and <a href="#timing">timing</a> as needed. 
</p>
<div class="example">
<pre class="example"> 1+2  / add 1 and 2
3

 !5   / generate a list of 5 integers from 0 to 4
0 1 2 3 4

 1+!5 / add one to each element of the list
1 2 3 4 5

 !_100e6;     / generate a list of 100 million integers (suppress output with ;)
 1+!_100e6;   / do 100 million sums
 \t 1+!_100e6 / time the operations in milliseconds
82
</pre></div>

<p>Now let&rsquo;s exit the session.
</p>
<div class="example">
<pre class="example"> \\
bash-3.2$ 
</pre></div>


</div>
<div class="section" id="Document-formatting-for-code-examples">
<h3 class="section">1.8 Document formatting for code examples</h3>
<p>This document uses a number of examples to familiarize the reader with k9.  The syntax is to have input with a leading space and output without a leading space.  This follows the terminal syntax where the REPL input has space but prints output without.
</p><div class="example">
<pre class="example"> 3+2 / this is input
5    / this is output
</pre></div>

</div>
<div class="section" id="k9-idiosyncracies">
<h3 class="section">1.9 k9 idiosyncracies</h3>
<p>One will need to understand some basic rules of k9 in order to progress.  These may seem strange at first but the faster you learn them, the faster you&rsquo;ll move forward. Also, some of them, like overloading based on number of arguments, add a lot of expressability to the language.
</p>
<ul class="section-toc">
<li><a href="#Colon-_0028_003a_0029-is-used-to-set-a-variable-to-a-value" accesskey="1">Colon (<code>:</code>) is used to set a variable to a value</a></li>
<li><a href="#Percent-_0028_0025_0029-is-used-to-divide-numbers" accesskey="2">Percent (<code>%</code>) is used to divide numbers</a></li>
<li><a href="#Evaluation-is-done-right-to-left" accesskey="3">Evaluation is done right to left</a></li>
<li><a href="#There-is-no-arithmetic-order" accesskey="4">There is no arithmetic order</a></li>
<li><a href="#Operators-are-overloaded-depending-on-the-number-of-arguments_002e" accesskey="5">Operators are overloaded depending on the number of arguments.</a></li>
<li><a href="#Lists-and-functions-are-very-similar_002e" accesskey="6">Lists and functions are very similar.</a></li>
<li><a href="#k9-notions-of-Noun_002c-Verb_002c-and-Adverb" accesskey="7">k9 notions of Noun, Verb, and Adverb</a></li>
</ul>
<div class="subsection" id="Colon-_0028_003a_0029-is-used-to-set-a-variable-to-a-value">
<h4 class="subsection">1.9.1 Colon (<code>:</code>) is used to set a variable to a value</h4>
<p><code>a:3</code> is used to set the variable, a, to the value, 3.  <code>a=3</code> is an equality test to determine if a is equal to 3.
</p>
</div>
<div class="subsection" id="Percent-_0028_0025_0029-is-used-to-divide-numbers">
<h4 class="subsection">1.9.2 Percent (<code>%</code>) is used to divide numbers</h4>
<p>Yeah, 2 divided by 5 is written as <code>2%5</code>, not <code>2/5</code>.  This choice is because <code>%</code> is similar to &#x00F7;, and the \ and / symbols are used elsewhere.
</p>
</div>
<div class="subsection" id="Evaluation-is-done-right-to-left">
<h4 class="subsection">1.9.3 Evaluation is done right to left</h4>
<p>2+5*3 is 17 and 2*5+3 is 16.  2+5*3 is first evaluated on the right most portion, 5*3, and once that is computed then it proceeds with 2+15.  2*5+3 goes to 2*8 which becomes 16.
</p>
</div>
<div class="subsection" id="There-is-no-arithmetic-order">
<h4 class="subsection">1.9.4 There is no arithmetic order</h4>
<p>+ has equal precedence as *.  The order of evaluation is done right to left unless parenthesis are used.  (2+5)*3 = 21 as the 2+5 in parenthesis is done before being multiplied by 3.
</p>
</div>
<div class="subsection" id="Operators-are-overloaded-depending-on-the-number-of-arguments_002e">
<h4 class="subsection">1.9.5 Operators are overloaded depending on the number of arguments.</h4>
<div class="example">
<pre class="example">&nbsp;*(13;6;9)    / single argument: * returns the first element
13
&nbsp;2*(13;6;9)   / two arguments: * is multiplication
26 12 18
</pre></div>

</div>
<div class="subsection" id="Lists-and-functions-are-very-similar_002e">
<h4 class="subsection">1.9.6 Lists and functions are very similar.</h4>
<p>k9 syntax encourages you to treat lists and functions in a similar function.  They should both be thought of a mapping from a value to another value or from a domain to a range. Lists and functions do not have the same type.
</p>
<div class="example">
<pre class="example"> l:3 4 7 12
 f:{3+x*x}
 l@2
7
 f@2
7
 @l
`I
 @f
`.
</pre></div>

</div>
<div class="subsection" id="k9-notions-of-Noun_002c-Verb_002c-and-Adverb">
<h4 class="subsection">1.9.7 k9 notions of Noun, Verb, and Adverb</h4>
<p>k9 uses an analogy with grammar to describe language syntax.  The k9 grammar consists of nouns (data), verbs (functions) and adverbs (function modifiers).
</p><ul>
<li> <tt>The boy ate an appple. (Noun verb noun)</tt>
</li><li> <tt>The girl ate each olive. (Noun verb adverb noun)</tt>
</li></ul>
<p>In k9 as the Help/Info card shows data are nouns, functions/lists are verbs and modifiers are adverbs.
</p><ul>
<li> <tt>3 &gt; 2 (Noun verb noun)</tt>
</li><li> <tt>3 &gt;' (1 12;1 4 5) (Noun verb adverb noun)</tt>
</li></ul>

<hr>
</div>
</div>
</div>
<div class="chapter" id="Verb">
<div class="header">
<p>
Next: <a href="#Adverb" accesskey="n" rel="next">Adverbs</a>, Previous: <a href="#Introduction" accesskey="p" rel="prev">Introduction</a>, Up: <a href="#Top" accesskey="u" rel="up">k9: Manual</a> &nbsp; </p>
</div>
<span id="Verbs"></span><h2 class="chapter">2 Verbs</h2>
<p>This chapter covers verbs which are the core primitives of k9.  Given how different it is to call functions in k9 than in most other languages, you may have to read this chapter  a few times.  Once you can &ldquo;speak&rdquo; k9 you&rsquo;ll read <code>|x</code> better than <code>reverse(x)</code>.
</p>
<p>Most functions are overloaded and change depending on the number of arguments.  This can confuse new users.  Eg. <code>(1 4)++(2 3;5 6;7 8)</code> contains the plus symbol once as flip and then for addition.  (Remember evaluation is right to left!)
</p>

<div class="example">
<pre class="example">Verb     monad   
+ +              
- -              
* *              
% <a href="#div">div</a>            
! <a href="#mod">mod</a>    <a href="#where">where</a>
&amp; &amp;      <a href="#flip">flip</a>  
| |      <a href="#reverse">reverse</a>
&lt; &lt;      <a href="#asc">asc</a>
&gt; &gt;      <a href="#desc">desc</a>
= =      <a href="#freq">freq</a>
~ ~      ~       
, ,      ,
# <a href="#take">take</a>   <a href="#count">count</a>
_ <a href="#drop">drop</a>   <a href="#first">first</a>
^ <a href="#cut">cut</a>    <a href="#sort">sort</a>
@ @      <a href="#type">type</a>
? <a href="#find">find</a>   <a href="#unique">unique</a>
$ <a href="#parse">parse</a>  <a href="#str">str</a>
. <a href="#dict">dict</a>   <a href="#value">value</a>
</pre></div>


<span id="plus"></span><ul class="section-toc">
<li><a href="#plus-_21d2-x_002by" accesskey="1">plus &rArr; x+y</a></li>
<li><a href="#negate-_21d2-_002dx_002e" accesskey="2">negate &rArr; -x.</a></li>
<li><a href="#minus-_21d2-x_002dy_002e" accesskey="3">minus &rArr; x-y.</a></li>
<li><a href="#first-_21d2-_005fx" accesskey="4">first &rArr; _x</a></li>
<li><a href="#times-_21d2-x_002ay" accesskey="5">times &rArr;  x*y</a></li>
<li><a href="#sqrt-_21d2-_0025x" accesskey="6">sqrt &rArr; %x</a></li>
<li><a href="#div-_21d2-x_0025y" accesskey="7">div &rArr; x<code>%</code>y</a></li>
<li><a href="#mod-_21d2-x_0021y" accesskey="8">mod &rArr; x!y</a></li>
<li><a href="#where-_21d2-_0021x" accesskey="9">where &rArr; !x</a></li>
<li><a href="#flip-_21d2-_0026x">flip &rArr; &amp;x</a></li>
<li><a href="#and-_21d2-x_0026y">and &rArr; x&amp;y</a></li>
<li><a href="#reverse-_21d2-_007cx">reverse &rArr; |x</a></li>
<li><a href="#or-_21d2-x_007cy">or &rArr; x|y</a></li>
<li><a href="#asc_0028desc_0029-_21d2-_003c-_0028_003e_0029-x">asc(desc) &rArr; &lt; (&gt;) x</a></li>
<li><a href="#less-_0028more_0029-_21d2-x-_003c-_0028_003e_0029-y">less (more) &rArr; x &lt; (&gt;) y</a></li>
<li><a href="#freq_21d2-_003dx">freq&rArr; =x</a></li>
<li><a href="#equal-_21d2-x_003dy">equal &rArr; x=y</a></li>
<li><a href="#not-_21d2-_007ex">not &rArr; ~x</a></li>
<li><a href="#match-_21d2-x_007ey">match &rArr; x~y</a></li>
<li><a href="#enlist-_21d2-_002cx">enlist &rArr; ,x</a></li>
<li><a href="#cat-_21d2-x_002cy">cat &rArr; x,y</a></li>
<li><a href="#sort-_21d2-_005ex">sort &rArr; ^x</a></li>
<li><a href="#g_t_005bf_005dcut-_21d2-x_005ey">[f]cut &rArr; x^y</a></li>
<li><a href="#count-_21d2-_0023x">count &rArr; #x</a></li>
<li><a href="#g_t_005bf_005dtake-_21d2-x_0023y">[f]take &rArr; x#y</a></li>
<li><a href="#floor-_21d2-_005fx">floor &rArr; _x</a></li>
<li><a href="#g_t_005bf_005ddrop-_21d2-x_005fy">[f]drop &rArr; x_y</a></li>
<li><a href="#str-_21d2-_0024x">str &rArr; $x</a></li>
<li><a href="#parse-_21d2-x_0024y">parse &rArr; x$y</a></li>
<li><a href="#unique-_21d2-_003fx">unique &rArr; ?x</a></li>
<li><a href="#find-_21d2-x_003fy">find &rArr; x?y</a></li>
<li><a href="#type-_21d2-_0040x">type &rArr; @x</a></li>
<li><a href="#g_t_005bf_005dat-_21d2-x_0040y">[f]at &rArr; x@y</a></li>
<li><a href="#value-_21d2-_002ex">value &rArr; .x</a></li>
<li><a href="#dict-_21d2-x_002ey">dict &rArr; x.y</a></li>
</ul>
<div class="section" id="plus-_21d2-x_002by">
<h3 class="section">2.1 plus &rArr; x+y</h3>
<p>Add x and y.  Arguments can be elements or lists but if both x and y are lists then they must be of equal length.
</p>
<div class="example">
<pre class="example"> 3+7
10

a:3;
 a+8
11

 3+4 5 6 7
7 8 9 10

3 4 5+4 5 6
7 9 11

 3 4+1 2 3        / lengths don't match
!length

 10:00+1         / add a minute
10:01

 10:00:00+1      / add a second
10:00:01

 10:00:00.000+1  / add a millisecond
10:00:00.001
</pre></div>

<span id="negate"></span></div>
<div class="section" id="negate-_21d2-_002dx_002e">
<h3 class="section">2.2 negate &rArr; -x.</h3>

<div class="example">
<pre class="example"> -3
-3

 --3
3

 x:4;
 -x
-4

 d:`a`b!((1 2 3);(4 5 6))
 -d
a|-1 -2 -3
b|-4 -5 -6
</pre></div>

<span id="minus"></span></div>
<div class="section" id="minus-_21d2-x_002dy_002e">
<h3 class="section">2.3 minus &rArr; x-y.</h3>
<p>Subtract y from x.
</p>
<div class="example">
<pre class="example"> 5-2
3

 x:4;y:1;
 x-y
3
</pre></div>

<span id="first"></span></div>
<div class="section" id="first-_21d2-_005fx">
<h3 class="section">2.4 first &rArr; _x</h3>
<p>Return the first value of x.  
</p>
<div class="example">
<pre class="example"> _1 2 3
1

 _((1 2);(3 4);(5 6))
1 2

 __((1 2);(3 4);(5 6))
1

 _`a`b.((1 2 3);(4 5 6))
1 2 3

 _|1 2 3
3
</pre></div>

<span id="times"></span></div>
<div class="section" id="times-_21d2-x_002ay">
<h3 class="section">2.5 times &rArr;  x*y</h3>
<p>Mutliply x and y.
</p>
<div class="example">
<pre class="example"> 3*4
12

3*4 5 6
12 15 18

1 2 3*4 5 6
4 10 18
</pre></div>

<span id="sqrt"></span></div>
<div class="section" id="sqrt-_21d2-_0025x">
<h3 class="section">2.6 sqrt &rArr; %x</h3>
<p>Return the square root of x.
</p>
<div class="example">
<pre class="example"> %25
5.000e+00
 %14.4
3.794e+00
</pre></div>

<span id="div"></span></div>
<div class="section" id="div-_21d2-x_0025y">
<h3 class="section">2.7 div &rArr; x<code>%</code>y</h3>
<p>Divide x by y.
</p>
<div class="example">
<pre class="example"> 12%5
2.400e+00

6%2
3.000e+00
</pre></div>

<span id="mod"></span></div>
<div class="section" id="mod-_21d2-x_0021y">
<h3 class="section">2.8 mod &rArr; x!y</h3>
<p>The remainder after y divided by x using integer division.  x and y must be integers.
</p>
<div class="example">
<pre class="example"> 12!27
3
 5!22
2
</pre></div>

<span id="where"></span></div>
<div class="section" id="where-_21d2-_0021x">
<h3 class="section">2.9 where &rArr; !x</h3>
<p>Given a list of boolean values return the non-zero indices.
</p>
<div class="example">
<pre class="example"> !00110011b
2 3 6 7

 &quot;banana&quot;=&quot;a&quot;
010101

 !&quot;banana&quot;=&quot;a&quot;
1 3 5

 x@!30&lt;x:12.7 0.1 35.6 -12.1 101.101
3.560e+01 1.011e+02
</pre></div>

<span id="flip"></span></div>
<div class="section" id="flip-_21d2-_0026x">
<h3 class="section">2.10 flip &rArr; &amp;x</h3>
<p>Flip, or transpose, x where x is list of 2 or more dimensions.  
</p>
<div class="example">
<pre class="example"> x:(1 2;3 4;5 6);x
(1 2;3 4;5 6)

 &amp;x
(1 3 5;2 4 6)

 `a`b.&amp;x
{a:1 3 5;b:2 4 6}

 &amp;`a`b.&amp;x
[a:1 3 5;b:2 4 6]
</pre></div>

<p>Given a list of boolean values return a list of indices where the value is zero (index 0) and non-zero (index 1).
</p>
<div class="example">
<pre class="example"> &amp;00110011b
(0 1 4 5;2 3 6 7)

 &quot;banana&quot;=&quot;a&quot;
010101

 &amp;&quot;banana&quot;=&quot;a&quot;
(0 2 4;1 3 5)

 x@&amp;30&lt;x:12.7 0.1 35.6 -12.1 101.101
(1.270e+01 0.100e+00 -1.210e+01;3.560e+01 1.011e+02)
</pre></div>

<p>Given a list of non-binary values, return the ascending sorted indices.
</p>
<div class="example">
<pre class="example"> &amp; 4 1 2 -3 4 1 
(,3;1 5;,2;0 4)

 &amp;`a`b`a`d
(0 2;,1;,3)

 &amp;&quot;blue red greeen&quot;
(4 8;,0;,7;3 6 11 12 13;,9;,1;,14;5 10;,2)

 &amp; 2023.01.01 2023.01.02 2023.01.01
(0 2;,1)
</pre></div>

<span id="min_002fand"></span></div>
<div class="section" id="and-_21d2-x_0026y">
<h3 class="section">2.11 and &rArr; x&amp;y</h3>
<p>The smaller of x and y.  One can use the over adverb to determine the min value in a list.
</p>
<div class="example">
<pre class="example"> 3&amp;2
2

 1 2 3&amp;4 5 6
1 2 3

0 1 0 0 1 0&amp;1 1 1 0 0 0
0 1 0 0 0 0

 `a&amp;`b
`a

 &amp;/ 3 2 10 -200 47
-200
</pre></div>

<span id="reverse"></span></div>
<div class="section" id="reverse-_21d2-_007cx">
<h3 class="section">2.12 reverse &rArr; |x</h3>
<p>Reverse the list x.
</p>
<div class="example">
<pre class="example"> |0 3 1 2
2 1 3 0

|&quot;banana&quot;
&quot;ananab&quot;

 |((1 2 3);4;(5 6))
(5 6;4;1 2 3)
</pre></div>

<p>To get the last element, one can take  the first element of the reverse list (*|<em class='math'>`</em>a<em class='math'>`</em>b<em class='math'>`</em>c).
</p>
<span id="max_002for"></span></div>
<div class="section" id="or-_21d2-x_007cy">
<h3 class="section">2.13 or &rArr; x|y</h3>
<p>The greater of x and y.  Max of a list can be determine by use of the adverb over.
</p>
<div class="example">
<pre class="example">  3|2
3

1 2 3|4 5 6
4 5 6

 1 0 1 1 0 1|0 0 0 1 1 1
1 0 1 1 1 1

 |/12 2 3 10 / use over to determine the max of a list
12
</pre></div>

<span id="asc"></span><span id="desc"></span></div>
<div class="section" id="asc_0028desc_0029-_21d2-_003c-_0028_003e_0029-x">
<h3 class="section">2.14 asc(desc) &rArr; &lt; (&gt;) x</h3>
<p>Sort a list or dictionary in ascending (&lt;) or descending (&gt;) order.  Applied to a list, these will return the indices to be used to achieve the sort.
</p>
<div class="example">
<pre class="example"> &lt;5 7 0 12
2 0 1 3

 x@&lt;x:5 7 0 12
0 5 7 12

 d:`a`b`c!3 2 1;d
a|3
b|2
c|1

 &lt;d / a dictionary is sorted by value
c|1
b|2
a|3
</pre></div>

<span id="less"></span><span id="more"></span></div>
<div class="section" id="less-_0028more_0029-_21d2-x-_003c-_0028_003e_0029-y">
<h3 class="section">2.15 less (more) &rArr; x &lt; (&gt;) y</h3>
<p>Return true (1b) if x is less (more) than y else false (0b).
</p>
<div class="example">
<pre class="example"> 3&lt;2
0b

2&lt;3
1b

 1 2 3&lt;4 5 6
1 1 1

 ((1 2 3);4;(5 6))&lt;((101 0 5);12;(10 0)) / size needs to match
1 0 1
1  
1 0

 &quot;a&quot;&lt;&quot;b&quot;
1b
</pre></div>

<span id="freq"></span></div>
<div class="section" id="freq_21d2-_003dx">
<h3 class="section">2.16 freq&rArr; =x</h3>
<p>Freq takes a list of uniform type, x, and returns a dictionary of the distinct values (key) and their number of occurences (value).
</p>
<div class="example">
<pre class="example"> =&quot;banana&quot;
abn.3 1 2

 =0 1 0 2 10 7 0 1 12
0 1 2 7 10 12.3 2 1 1 1 1
</pre></div>

<span id="equal"></span></div>
<div class="section" id="equal-_21d2-x_003dy">
<h3 class="section">2.17 equal &rArr; x=y</h3>
<p>Return true (1b) if x is equal to y else false (0b).  
</p>
<div class="example">
<pre class="example"> 2=2
1

2=3
0

2=2.
1

 &quot;banana&quot;=&quot;abnaoo&quot; / check strings of equal length by character
0 0 1 1 0 0

 &quot;banana&quot;=&quot;apple&quot;  / unequal length strings error
!length
</pre></div>

<span id="not"></span></div>
<div class="section" id="not-_21d2-_007ex">
<h3 class="section">2.18 not &rArr; ~x</h3>
<p>Boolean invert of x
</p>
<div class="example">
<pre class="example"> ~1
0

 ~1 0 1
0 1 0

 ~37 0 12
0 1 0
</pre></div>

<span id="match"></span></div>
<div class="section" id="match-_21d2-x_007ey">
<h3 class="section">2.19 match &rArr; x~y</h3>
<p>Return true (1) if x matches y else false (0).  A match happens if the two arguments evaluate to the same expression.
</p>
<div class="example">
<pre class="example"> 2~2
1

 2~3
0

 2~2.
0

 &quot;banana&quot;~&quot;apple&quot;
0

 `a`b~`a`b  / different than = which is element-wise comparison
1

 `a`b=`a`b
1 1

 f:{x+y}
 f~{x+y}
1
</pre></div>

<span id="enlist"></span></div>
<div class="section" id="enlist-_21d2-_002cx">
<h3 class="section">2.20 enlist &rArr; ,x</h3>
<p>Create a list from x
</p>
<div class="example">
<pre class="example"> ,3
,3

,1 2 3
1 2 3

 3=,3
,1

 3~,3
0
</pre></div>

<span id="cat"></span></div>
<div class="section" id="cat-_21d2-x_002cy">
<h3 class="section">2.21 cat &rArr; x,y</h3>
<p>Concatenate x and y.
</p>
<div class="example">
<pre class="example"> 3,7
3 7

 &quot;hello&quot;,&quot; &quot;,&quot;there&quot;
&quot;hello there&quot;

 C:(&quot;ab&quot;;&quot;c&quot;;(&quot;def&quot;;&quot;ghi&quot;));C
ab           
c            
(&quot;def&quot;;&quot;ghi&quot;)

 ,/C     / join the list once
a  
b  
c  
def
ghi

 ,//:C   / converge over join until single list
&quot;abcdefghi&quot;
</pre></div>

<span id="sort"></span></div>
<div class="section" id="sort-_21d2-_005ex">
<h3 class="section">2.22 sort &rArr; ^x</h3>
<p>Sort list, dictionary, or table x into ascending order.  Dictionaries are sorted using the keys and tables by the first column field.  One can sort tables by arbitrary columns by first reordering the columns in the table using <a href="#take">take</a> or by extracting the sort column by index or expression.
</p>
<div class="example">
<pre class="example"> ^0 3 2 1
0 1 2 3

^`b`a!((0 1 2);(7 6 5))     / sort dictionary by key
[a:7 6 5;b:0 1 2]

 ^[[]z:`c`a`b;y:3 2 1]      / sort table by 1st col
z y
- -
a 2
b 1
c 3

 ^`y`z#[[]z:`c`a`b;y:3 2 1] / sort table by new 1st col
y z
- -
1 b
2 a
3 c
</pre></div>

<span id="cut"></span></div>
<div class="section" id="g_t_005bf_005dcut-_21d2-x_005ey">
<h3 class="section">2.23 [f]cut &rArr; x^y</h3>
<p>Cut list y by size, indices, or function x.  Also, cut table y into key x and value.
</p>
<table>
<tr><td><b>action</b></td><td><b>x</b></td></tr>
<tr><td><a href="#cut1">rows</a></td><td>positive int</td></tr>
<tr><td><a href="#cut2">columns</a></td><td>negative int</td></tr>
<tr><td><a href="#cut3">indices</a></td><td>list</td></tr>
<tr><td><a href="#cut4">function</a></td><td>function</td></tr>
<tr><td><a href="#cut5">table</a></td><td>column</td></tr>
</table>

<span id="cut1"></span><p>Positve integer x, cut y into x rows
</p><div class="example">
<pre class="example"> 3^101+!18   / 3 rows
101 102 103 104 105 106
107 108 109 110 111 112
113 114 115 116 117 118
</pre></div>

<span id="cut2"></span><p>Negative integer, cut y into x elements per row
</p><div class="example">
<pre class="example"> -3^101+!18  / 3 columns
101 102 103
104 105 106
107 108 109
110 111 112
113 114 115
116 117 118
</pre></div>

<span id="cut3"></span><p>Positive integer array x, cut at each element in x
</p><div class="example">
<pre class="example"> 2 3 7 ^!17  / left list indicates start number of each row.
,2                        
3 4 5 6                   
7 8 9 10 11 12 13 14 15 16

 8 9 10 11 12^.1*!20
,0.8                           
,0.9                           
,1.                            
,1.1                           
1.2 1.3 1.4 1.5 1.6 1.7 1.8 1.9
</pre></div>

<span id="cut4"></span><p>Function returning boolean array, cut at each index where f is non-zero.
</p><div class="example">
<pre class="example"> {(x*x)within .5 1.5}^.1*!20
0.8                            
0.9                            
1.                             
1.1                            
1.2 1.3 1.4 1.5 1.6 1.7 1.8 1.9
</pre></div>

<span id="cut5"></span><p>Table returning utable (aka keyed table).
</p><div class="example">
<pre class="example"> t:[[]a:`x`y`z;b:1 20 1];t / an unkeyed table
a b 
- --
x  1
y 20
z  1

 kt:`a^t;kt                / set `a as the key
a|b 
-|--
x| 1
y|20
z| 1
</pre></div>
 
<span id="count"></span></div>
<div class="section" id="count-_21d2-_0023x">
<h3 class="section">2.24 count &rArr; #x</h3>
<p>Count the number of elements in list, dictionary, or table x.
</p>
<div class="example">
<pre class="example"> #0 1 2 12
4

 #((0 1 2);3;(4 5))
3
 #`a`b!((1 2 3);(4 5 6)) / count the number of keys
2

 #5                      / single element is 1
1
</pre></div>

<span id="take"></span></div>
<div class="section" id="g_t_005bf_005dtake-_21d2-x_0023y">
<h3 class="section">2.25 [f]take &rArr; x#y</h3>
<p>[f]take has a number of different actions depending on x.  These include head (take from front of list), tail (take from back of list), common (take common elements), filter (take where function is non-zero), and select (take columns from table).
</p>
<table>
<tr><td><b>action</b></td><td><b>x</b></td><td><b>y</b></td></tr>
<tr><td><a href="#take1">head</a></td><td>positive int</td><td>list</td></tr>
<tr><td><a href="#take1">tail</a></td><td>negative int</td><td>list</td></tr>
<tr><td><a href="#take2">common</a></td><td>list</td><td>list / dictionary</td></tr>
<tr><td><a href="#take3">filter</a></td><td>function</td><td>list</td></tr>
<tr><td><a href="#take4">select</a></td><td>name(s)</td><td>table</td></tr>
</table>

<span id="take1"></span><p>Postive (negative) x returns the first (last) x elements of y.  If abs[x]&gt;count[y] then repeatedly pull from y.
</p>
<div class="example">
<pre class="example"> 3#0 1 2 3 4 5          / take first 3 elements of a list
0 1 2

 10 # 17 12 25 / take repeat: take from list and repeat as needed
17 12 25 17 12 25 17 12 25 17

 -3#0 1 2 3 4 5         / take last elements of a list
3 4 5


</pre></div>

<span id="take2"></span><p>If x and y are lists, then take returns any values common in both x and y.  If x is a list and y is a dictionary, then take returns those values in y where the keys are in x.
</p>
<div class="example">
<pre class="example"> (1 2 3 7 8 9)#(2 8 20) / common
2 8

  (2 4 6 2 6 5 4) # (4 6 7 8 2 4 4 4) / substring of right argument
4 6 2 4 4 4
 
 (4 6 7 8 2 4 4 4) # (2 4 6 2 6 5 4)
2 4 6 2 6 4

 `b`d#`a`b`c`d!1 4 2 3
b|4
d|3
</pre></div>

<span id="take3"></span><p>If x is a function, then select the values where the function is non-zero.
</p>
<div class="example">
<pre class="example"> (0.5&lt;)#10?1.           / select values greater than 0.5
0.840732 0.5330717 0.7539563 0.643315 0.6993048f
</pre></div>

<span id="take4"></span><p>If x is a name or list of names, then take the name column or columns from the table.
</p>
<div class="example">
<pre class="example"> t:[[]x:`a`b`c;y:3 1 2;z:&quot;tab&quot;];t
x y z
- - -
a 3 t
b 1 a
c 2 b

 `y#t
y
-
3
1
2

 `z`y#t
z y
- -
t 3
a 1
b 2

 `x`z`y#t
x z y
- - -
a t 3
b a 1
c b 2
</pre></div>

<span id="floor"></span></div>
<div class="section" id="floor-_21d2-_005fx">
<h3 class="section">2.26 floor &rArr; _x</h3>
<p>Return the integer floor of float x.
</p><div class="example">
<pre class="example">&nbsp;_3.7
3
</pre></div>

<span id="drop"></span></div>
<div class="section" id="g_t_005bf_005ddrop-_21d2-x_005fy">
<h3 class="section">2.27 [f]drop &rArr; x_y</h3>
<p>[f]drop has a number of different actions depending on x.  This include de-head (drop from front of list), de-tail (drop from back of list), uncommon (drop common elements), and filter (drop where function is zero).
</p>
<table>
<tr><td><b>action</b></td><td><b>x</b></td><td><b>y</b></td></tr>
<tr><td><a href="#drop1">dehead</a></td><td>positive int</td><td>list</td></tr>
<tr><td><a href="#drop1">detail</a></td><td>negative int</td><td>list</td></tr>
<tr><td><a href="#drop2">uncommon</a></td><td>list</td><td>list / dictionary</td></tr>
<tr><td><a href="#drop3">filter</a></td><td>function</td><td>list</td></tr>
</table>

<span id="drop1"></span><p>Postive (negative) x drops the first (last) x elements of y.  
</p>
<div class="example">
<pre class="example"> 3_0 1 2 3 4 5          / drop first three
3 4 5

 -2_0 1 2 3 4 5         / drop last two
0 1 2 3
</pre></div>

<span id="drop2"></span><p>If x and y are lists, then drop returns any values from y not found in x.  If x is a list and y is a dictionary, then drop returns those values in y where the keys are not in x.
</p>
<div class="example">
<pre class="example"> (1 2 3 7 8 9)_(2 8 20) / uncommon
,20

 `b`d_`a`b`c`d!1 4 2 3
a|1
c|2
</pre></div>

<span id="drop3"></span><p>If x is a function, then select values where the function is zero.
</p>
<div class="example">
<pre class="example"> (0.5&lt;)_10?1.           / values less than or equal to 0.5
0.02049699 0.1269226
</pre></div>

<span id="str"></span></div>
<div class="section" id="str-_21d2-_0024x">
<h3 class="section">2.28 str &rArr; $x</h3>
<p>Cast x to string.
</p><div class="example">
<pre class="example"> $`abc
&quot;abc&quot;
 $4.7
&quot;4.7&quot;
</pre></div>

<span id="parse"></span></div>
<div class="section" id="parse-_21d2-x_0024y">
<h3 class="section">2.29 parse &rArr; x$y</h3>
<p>Parse string y into type x.
</p>
<div class="example">
<pre class="example"> `i$&quot;23&quot;
23

 `f$&quot;2.3&quot;
2.3

 `f$&quot;2&quot;
2

 `t$&quot;12:34:56.789&quot;
12:34:56.789

`d$&quot;2020.04.20&quot;
2020.04.20
</pre></div>

<span id="unique"></span></div>
<div class="section" id="unique-_21d2-_003fx">
<h3 class="section">2.30 unique &rArr; ?x</h3>
<p>Return the distinct values of the list x.  The <code>?</code> preceeding the return value explicitly shows that the list has no repeated values.
</p>
<div class="example">
<pre class="example"> ?`f`a`b`c`a`b`d`e`a
?`f`a`b`c`d`e

?&quot;banana&quot;
?&quot;ban&quot;
</pre></div>

<span id="find"></span></div>
<div class="section" id="find-_21d2-x_003fy">
<h3 class="section">2.31 find &rArr; x?y</h3>
<p>Find the first element of x that matches y otherwise return the end of vector.
</p>
<div class="example">
<pre class="example"> `a`b`a`c`b`a`a?`b
1

 `a`b`a`c`b`a`a?`d / missing thus return the list length
7

 0 1 2 3 4?10
5

(1;`a;&quot;blue&quot;;7.4)?3
4
</pre></div>

<p>Return x uniform random numbers between 0 and y or from list y with the same type as y. If x is negative then values are unique.  
</p>
<div class="example">
<pre class="example"> 3?1.      / values [0,1.)
0.01640292 0.8029538 0.9569196

 3?10      / values [0,9)
6 9 4

 5?`a`b`c  / sample from list y
`a`a`c`c`b

 -3?3      / unique values
1 2 0

 3?3       / duplicates are possible
2 2 1
</pre></div>

<span id="type"></span></div>
<div class="section" id="type-_21d2-_0040x">
<h3 class="section">2.32 type &rArr; @x</h3>
<p>Return the data type of x.  Lower-case represents a single element while upper-case represents a list of type indicated.
</p>
<div class="example">
<pre class="example"> @2
`i

 @1.2
`f

 @`a
`n

 @&quot;a&quot;
`c

 @2020.04.20
`d

 @12:34:56.789
`t

 @(1;1.2;`a;&quot;a&quot;;2020.04.20;12:34:56.789)  / type of a list
`:

 @'(1;1.2;`a;&quot;a&quot;;2020.04.20;12:34:56.789) / type of elements of the list
`i`f`s`c`d`t

 @{x*x}
`.

 @`a`b!1 2
`a

 @[[]x:`a`b;y:1 2]
`A

 @[x:`a`b]y:1 2]
`a
</pre></div>

<span id="at"></span></div>
<div class="section" id="g_t_005bf_005dat-_21d2-x_0040y">
<h3 class="section">2.33 [f]at &rArr; x@y</h3>
<p>Given a list or function x return the value(s) at index(indices) y.  
</p>
<div class="example">
<pre class="example"> (3 4 7 12)@2              / list
7

 `a`b`c@2
`c

 ((1 2);3;(4 5 6))@(0 1)   / values at indices 0 and 1
1 2
3

 {x*x}@3                   / function
9

 (sin;cos;1*)@\:0.01
0.009999833 0.99995 0.01

 (sqr;sqrt;|;#)@'(3;10;&quot;word&quot;;`a`b`c) / list of fuctions applied to list of inputs
9       
3.162278
drow    
3       
</pre></div>

<span id="value"></span></div>
<div class="section" id="value-_21d2-_002ex">
<h3 class="section">2.34 value &rArr; .x</h3>
<p>Evaluate a string of valid k code, list of k code, or a system command.  Can also be used to covert from a string to a numeric, temporal or name type.
</p>
<p>String of k code
</p><div class="example">
<pre class="example"> .&quot;3+2&quot;
5

 .&quot;20*1+!3&quot;
20 40 60
</pre></div>

<p>List of k code
</p><div class="example">
<pre class="example"> .(*;16;3)
48

 n:3;p:+(n?(+;-;*;%);1+n?10;1+n?10);p
% 6 3
* 2 7
- 5 5

 .'p
2 
14
0

 .(:;`a;12 14 16) / set a to (12 14 16)
 a
12 14 16
</pre></div>

<p>System command (must be prefixed with \\)
</p><div class="example">
<pre class="example"> .&quot;\\ls .&quot;
Mi2.0     
json.dylib
</pre></div>

<p>Convert from string to numeric or name.
</p><div class="example">
<pre class="example"> .&quot;15&quot;
15

 .&quot;12.7&quot;
12.7

 .&quot;`abc&quot;
`abc
</pre></div>

<span id="dict"></span></div>
<div class="section" id="dict-_21d2-x_002ey">
<h3 class="section">2.35 dict &rArr; x.y</h3>
<p>Create a dictionary from key x and value y.  Keys and vlaues can be of the various types, eg. numbers, symbols, characters, strings, dates, and times.  There is a an alternative form to create dictionaries using curly brack notation, eg. {a:2 3}. 
</p>
<div class="example">
<pre class="example"> d:`a`b`c.1 2 3;d
`a`b`c.1 2 3

 d`b
2

 d:1 2 3 . 4 5 6;d
1 2 3.4 5 6

 d:&quot;blue&quot; . 1 2 3 4;d
blue.1 2 3 4

 d:2023.01.01 2023.02.01 2023.03.01 . 1 2 3;d
2023.01.01 2023.02.01 2023.03.01.1 2 3

 d:`a`b`c . (1 2 3;4 5;6);d
{a:1 2 3;b:4 5;c:6}

 fa[a] a+1
 fb[a] a+2
 fc[a] a+3

 d:`f1`f2`f3 . (fa;fb;fc);d
{f1:(,`a;0a+;(1); a+1);f2:(,`a;0a+;(2); a+2);f3:(,`a;0a+;(3); a+3)}

 (d@`f1)@99
100

(d@`f3)@99
102
</pre></div>


<hr>
</div>
</div>
<div class="chapter" id="Adverb">
<div class="header">
<p>
Next: <a href="#Noun" accesskey="n" rel="next">Noun</a>, Previous: <a href="#Verb" accesskey="p" rel="prev">Verbs</a>, Up: <a href="#Top" accesskey="u" rel="up">k9: Manual</a> &nbsp; </p>
</div>
<span id="Adverbs"></span><h2 class="chapter">3 Adverbs</h2>
<p>This chapter may be one of the most difficult for users new to array langauges but one must master adverbs to exploit the full power of k9.  Nouns and verbs naturally come but adverbs need to be learned so that one can reach for them when needed.
</p>
<div class="example">
<pre class="example">Adverb
   f'  <a href="#each">each</a>
[x]f/  <a href="#scan">over</a>      c/ <a href="#join">join</a>
[x]f\  <a href="#scan">scan</a>      c\ <a href="#split">split</a>
[y]f': <a href="#eachprior">eachprior</a>
   f/: <a href="#eachright">eachright</a> g/:<a href="#cover">over</a> 
   f\: <a href="#eachleft">eachleft</a>  g\:<a href="#cscan">scan</a> 
</pre></div>

<p>Adverbs modify verbs to operative iteratively over nouns.  This previous sentence likely will  make sense only once you understand it so let&rsquo;s jump into an example.  Imagine you have a list of 4 lists.  Using <code>first</code> you will retrieve the first sub-list.  In order to retrieve the first element of each sub-list you&rsquo;ll have to modify the function <code>first</code> with a modifier <code>each</code>.
</p>
<div class="example">
<pre class="example"> x:(1 2; 3 4; 5 6; 7 8);x
1 2
3 4
5 6
7 8

*x   / first
1 2

*'x  / each first
1 3 5 7
</pre></div>

<p>Adverbs are also used where one might use a <code>for</code>, <code>do</code>, or <code>while</code> loop to calculate over a list of value or recursively until a condition is met.
</p>
<div class="example">
<pre class="example"> f:{x*y}   
 f\1 .1 .1 .1 / f\ scan over list
1    
0.1  
0.01 
0.001

 g:{x*x}
 g\:.99       / g\: scan until convergence
0.99 0.9801 0.960596 .. 8.87948e-287 0
</pre></div>

<span id="each"></span><ul class="section-toc">
<li><a href="#each-_21d2-f_0027x" accesskey="1">each &rArr; f&rsquo;x</a></li>
<li><a href="#over-_21d2-f_002fy-or-x-f_002fy" accesskey="2">over &rArr; f/y or x f/y</a></li>
<li><a href="#scan-_21d2-f_005cy-or-x-f_005cy" accesskey="3">scan &rArr; f\y or x f\y</a></li>
<li><a href="#join-_21d2-c_002fx" accesskey="4">join &rArr; c/x</a></li>
<li><a href="#split-_21d2-c_005cx" accesskey="5">split &rArr; c\x</a></li>
<li><a href="#eachprior-_21d2-f_0027_003a_005bx_003by_005d-or-y-f_0027_003ax" accesskey="6">eachprior &rArr; f&rsquo;:[x;y] or y f&rsquo;:x</a></li>
<li><a href="#eachright-_21d2-f_002f_003a_005bx_003by_005d" accesskey="7">eachright &rArr; f/:[x;y]</a></li>
<li><a href="#eachleft-_21d2-f_005c_003a_005bx_003by_005d" accesskey="8">eachleft &rArr; f\:[x;y]</a></li>
<li><a href="#Converge-Over-_21d2-g_002f_003ax-or-_0028n_003bg_0029_002f_003ax" accesskey="9">Converge Over &rArr; g/:x or (n;g)/:x</a></li>
<li><a href="#Converge-Scan-_21d2-g_005c_003ax-or-_0028n_003bg_0029_005c_003ax">Converge Scan &rArr; g\:x or (n;g)\:x</a></li>
</ul>
<div class="section" id="each-_21d2-f_0027x">
<h3 class="section">3.1 each &rArr; f&rsquo;x</h3>
<p>Apply function f to each value in list x in a single thread.  Multithread operation is done with <a href="#eachprior">eachprior</a>.  
</p>
<div class="example">
<pre class="example"> *((1 2 3);4;(5 6);7)   / first element of the list
1 2 3

 *'((1 2 3);4;(5 6);7)  / first element of each element
1 4 5 7

 !3                     / simple list
0 1 2
 +/!3                   / sum of the list
3
 2#'!3                  / take 5 copies of the list
0 0
1 1
2 2
 +/2#'!3                / sum
3 3
 +/'2#'!3               / sum each, eg. (0 1 2)+(0 1 2)
0 2 4
</pre></div>

<span id="over"></span></div>
<div class="section" id="over-_21d2-f_002fy-or-x-f_002fy">
<h3 class="section">3.2 over &rArr; f/y or x f/y</h3>
<p>Over has the same function as <a href="#scan">scan</a> but returns only the last value.
</p>
<span id="scan"></span></div>
<div class="section" id="scan-_21d2-f_005cy-or-x-f_005cy">
<h3 class="section">3.3 scan &rArr; f\y or x f\y</h3>
<p>Compute f, a function of two arguments, over list y with optional initial value x.  On the first iteration return y<sub>0</sub>.  On each subsequent iteration function will be called with previous output and the next element of y as arguments, i.e. f<sub>i</sub>=f[f<sub>i-1</sub>;y<sub>i</sub>].  Calling with f, a function of one argument, is covered in <a href="#each">each</a>.
</p>
<table>
<tr><td><b>i</b></td><td><b>x</b></td><td><b>f[x]</b></td><td><b>a f[x]</b></td><td><b>x:0 1 4 9 16 25</b></td><td><b>+\x</b></td><td><b>3+\x</b></td><td><b>+/x</b></td><td><b>3+/x</b></td></tr>
<tr><td>0</td><td>x<sub>0</sub></td><td>x<sub>0</sub></td><td>f<sub>0</sub>[a;x<sub>0</sub>]</td><td>0</td><td>0</td><td>3</td><td></td><td></td></tr>
<tr><td>1</td><td>x<sub>1</sub></td><td>f<sub>1</sub>[f<sub>0</sub>;x<sub>1</sub>]</td><td>f<sub>1</sub>[f<sub>0</sub>;x<sub>1</sub>]</td><td>1</td><td>1</td><td>4</td><td></td><td></td></tr>
<tr><td>..</td><td>..</td><td>..</td><td>..</td><td>..</td><td>..</td><td>..</td><td></td><td></td></tr>
<tr><td>j</td><td>x<sub>j</sub></td><td>f<sub>j</sub>[f<sub>j-1</sub>;x<sub>j</sub>]</td><td>f<sub>j</sub>[f<sub>j-1</sub>;x<sub>j</sub>]</td><td>..</td><td>..</td><td>..</td><td></td><td></td></tr>
<tr><td>..</td><td>..</td><td>..</td><td>..</td><td>..</td><td>..</td><td>..</td><td></td><td></td></tr>
<tr><td>n-2</td><td>x<sub>n-2</sub></td><td>f<sub>n-2</sub>[f<sub>n-3</sub>;x<sub>n-2</sub>]</td><td>f<sub>n-2</sub>[f<sub>n-3</sub>;x<sub>n-2</sub>]</td><td>16</td><td>30</td><td>33</td><td></td><td></td></tr>
<tr><td>n-1</td><td>x<sub>n-1</sub></td><td>f<sub>n-1</sub>[f<sub>n-2</sub>;x<sub>n-1</sub>]</td><td>f<sub>n-1</sub>[f<sub>n-2</sub>;x<sub>n-1</sub>]</td><td>25</td><td>55</td><td>58</td><td>55</td><td>58</td></tr>
</table>


<p>Examples
</p><div class="example">
<pre class="example"> (,\)(&quot;a&quot;;&quot;b&quot;;&quot;c&quot;)   / scan and cat to build up a list
a
ab
abc

 +\1 20 300          / scan and plus to sum over a list
1 21 321

 {y+10*x}\1 20 300   / scan and user func
1 30 600

 {y+10*x}/1 20 300   / over and user func
600

 x:1 2 3               / x+y0, +y1, +y2
 y:10 10 10
 x+\y
11 12 13
21 22 23
31 32 33

 {x+.5*y}\[1 2 3;20 20 20]  / f\y syntax
11 12 13
21 22 23
31 32 33

 1 2 3{x+.5*y}\20 20 20    / i f\x syntax
11 12 13
21 22 23
31 32 33
</pre></div>

<span id="join"></span></div>
<div class="section" id="join-_21d2-c_002fx">
<h3 class="section">3.4 join &rArr; c/x</h3>
<p>Join a list of strings x using character c between each pair.
</p>
<div class="example">
<pre class="example"> &quot;-&quot;/(&quot;Some&quot;;&quot;random text&quot;;&quot;plus&quot;;,&quot;.&quot;)
&quot;Some-random text-plus-.&quot;
</pre></div>

<p>The notaion c/x converts a list of integers x via base c into base 10. In the example below, assuming 2 0 1 are digits in base 8, they convert to  1 + (0*8) + (2*8*8) = 129
</p>
<div class="example">
<pre class="example"> 8/2 0 1  
129
</pre></div>

<span id="split"></span></div>
<div class="section" id="split-_21d2-c_005cx">
<h3 class="section">3.5 split &rArr; c\x</h3>
<p>Split the string x using character c to determine the locations.
</p>
<div class="example">
<pre class="example"> &quot; &quot;\&quot;Here is a short sentence.&quot;
Here     
is       
a        
short    
sentence.
</pre></div>

<p>c\x splits a number x into base c digits.
</p>
<div class="example">
<pre class="example"> 8\129
2 0 1
</pre></div>

<span id="eachprior"></span></div>
<div class="section" id="eachprior-_21d2-f_0027_003a_005bx_003by_005d-or-y-f_0027_003ax">
<h3 class="section">3.6 eachprior &rArr; f&rsquo;:[x;y] or y f&rsquo;:x</h3>
<p>Compute f, a function of two arguments, over list x with optional initial value y.   Concretely f<sub>i</sub>=f[x<sub>i</sub>;x<sub>i-1</sub>] where f<sub>0</sub> returns f[x<sub>0</sub>;i].
</p>
<div class="example">
<pre class="example"> ,':[`i;(`$&quot;x&quot;,'$!5)]
x0 i 
x1 x0
x2 x1
x3 x2
x4 x3

 %':[100;100 101.9 105.1 102.3 106.1] / compute returns
1 1.019 1.031403 0.9733587 1.037146

 100%':100 101.9 105.1 102.3 106.1    / using infix notation
1 1.019 1.031403 0.9733587 1.037146

 101.9{($x),&quot; % &quot;,($y),&quot; = &quot;,$x%y}':100.1 101.9 105.1 102.3 106.1
100.1 % 101.9 = 0.9823356
101.9 % 100.1 = 1.017982 
105.1 % 101.9 = 1.031403 
102.3 % 105.1 = 0.9733587
106.1 % 102.3 = 1.037146 
</pre></div>

<p>Additionally eachp (&rsquo;:) is a multithreaded (parallel) each.  This will allow a function to run using multiple threads over a list of arguments.
</p>
<div class="example">
<pre class="example">\t {L:x?1.;sum L%sin L*cos L*sin L+L*L}':8#_50e6 / multiple threads
831

\t {L:x?1.;sum L%sin L*cos L*sin L+L*L}'8#_50e6  / single thread
1202
</pre></div>

<span id="eachright"></span></div>
<div class="section" id="eachright-_21d2-f_002f_003a_005bx_003by_005d">
<h3 class="section">3.7 eachright &rArr; f/:[x;y]</h3>
<p>Apply f[x;y] to each value of y, i.e. the right one.
</p>
<div class="example">
<pre class="example"> (!2)+/:!3
0 1
1 2
2 3

 {x+10*y}/:[!2;!3]
0 1  
10 11
20 21

 &quot;pre-&quot;,/:(&quot;apple&quot;;&quot;banana&quot;;&quot;cherry&quot;)
pre-apple 
pre-banana
pre-cherry
</pre></div>

<span id="eachleft"></span></div>
<div class="section" id="eachleft-_21d2-f_005c_003a_005bx_003by_005d">
<h3 class="section">3.8 eachleft &rArr; f\:[x;y]</h3>
<p>Apply f[x;y] to each value of x, i.e. the left one.
</p>
<div class="example">
<pre class="example"> (!2)+\:!3
0 1 2
1 2 3

 {x+10*y}\:[!2;!3]
0 10 20
1 11 21

 (&quot;apple&quot;;&quot;banana&quot;;&quot;cherry&quot;),\:&quot;-post&quot;
apple-post 
banana-post
cherry-post
</pre></div>

<span id="cover"></span></div>
<div class="section" id="Converge-Over-_21d2-g_002f_003ax-or-_0028n_003bg_0029_002f_003ax">
<h3 class="section">3.9 Converge Over &rArr; g/:x or (n;g)/:x</h3>
<p>Converge Over is the same function as <a href="#cscan">Converge Scan</a> but only returns the final value(s).
</p>
<div class="example">
<pre class="example"> r:((1;2);3;(,4));r
1 2
3  
,4 

 ,//:r  / raze over the list until it converges to a flat list
1 2 3 4
</pre></div>

<span id="cscan"></span></div>
<div class="section" id="Converge-Scan-_21d2-g_005c_003ax-or-_0028n_003bg_0029_005c_003ax">
<h3 class="section">3.10 Converge Scan &rArr; g\:x or (n;g)\:x</h3>
<p>Compute function g where g<sub>i</sub>=g[g<sub>i-1</sub>] and g<sub>0</sub>=x.  If n is specified then it is either (DO) the number of iterations or (WHILE) a function returning a non-zero result.  
</p>
<div class="example">
<pre class="example">  {x*x}\:.99           / converge to value
0.99 0.9801 0.9605961 ... 1.323698e-18 1.752177e-36 0.

 (3;{x*x})\:.99        / do 3 times, return 4 values (first is initial)
0.99 0.9801 0.960596 0.9227448

 (.5&lt;;{x*x})\:.99      / while .5 &lt; r, i.e. r is greater than 0.5
0.99 0.9801 0.960596 0.9227448 0.8514579 0.7249806 0.5255968 0.276252

 (4;{x,x+/x+1})\:,0    / do function 4 times
,0                                         
0 1                                        
0 1 3 4                                    
0 1 3 4 12 13 15 16                        
0 1 3 4 12 13 15 16 72 73 75 76 84 85 87 88

 (10&gt;#;{x,x+/x+1})\:,0 / while output is less than 10 long
,0                                         
0 1                                        
0 1 3 4                                    
0 1 3 4 12 13 15 16                        
0 1 3 4 12 13 15 16 72 73 75 76 84 85 87 88

 x:3 4 2 1 4 99        / until output is x
 x\:0
0 3 1 4

 / the latter example worked out manually
 x 0
3
 x 3
1
 x 1
4
 x 4                   / x[4]=4 so will stop
4
</pre></div>


<hr>
</div>
</div>
<div class="chapter" id="Noun">
<div class="header">
<p>
Next: <a href="#List" accesskey="n" rel="next">List</a>, Previous: <a href="#Adverb" accesskey="p" rel="prev">Adverbs</a>, Up: <a href="#Top" accesskey="u" rel="up">k9: Manual</a> &nbsp; </p>
</div>
<span id="Noun-1"></span><h2 class="chapter">4 Noun</h2>
<p>The basic data types of the k9 language are booleans, numbers (integer and float), text (characters and enumerated/name) and temporal (date and time).  It is common to have functions operate on multiple data types.
</p>
<p>In additional to the basic data types, data can be put into lists (uniform, i.e., all elements of the same type, and non-uniform), dictionaries (key-value pairs), and tables (transposed/flipped dictionaries).  Dictionaries and tables will be covered in another chapter.
</p>
<p>Here are some examples of each of these types (note that 0N is a null integer and 0n a null float).
</p>
<div class="example">
<pre class="example">Type
<a href="#char">char</a>   &quot; ab&quot;          
<a href="#sym">sym</a>    ``ab
<a href="#bool">bool</a>   011b   
<a href="#int">int</a>    2 3 4
<a href="#float">float</a>  2 3e4          
<a href="#fixed">fixed</a>  2.0 3.4
<a href="#locus">locus</a>  -74::40.7      
<a href="#date">date</a>   2001.02.03  
<a href="#time">time</a>   12:34:56.789
<a href="#datetime">datetime</a>
</pre></div>

<p>Data types can be determined by using the <code>@</code> function on values or lists of values.  In the case of non-uniform lists <code>@</code> returns the type of the list <code>`L</code> but the function can be modified to evaluate the type of each element in the list using <code>@'</code>.
</p>
<div class="example">
<pre class="example">&nbsp;@1            / integer atom
`i
&nbsp;@1 2 3        / integer list
`I
&nbsp;@12:34:56.789 / time atom
&nbsp;@(3;3.1;&quot;b&quot;;`a;12:01:02.123;2020.04.05) / mixed list
`L
&nbsp;@'(3;3.1;&quot;b&quot;;`a;12:01:02.123;2020.04.05)
`i`f`c`n`t`d
</pre></div>

<span id="Atom-Types"></span><ul class="section-toc">
<li><a href="#Atom-Types-1" accesskey="1">Atom Types</a></li>
<li><a href="#bool-_21d2-Boolean-b" accesskey="2">bool &rArr; Boolean b</a></li>
<li><a href="#Numeric-Data" accesskey="3">Numeric Data</a></li>
<li><a href="#Text-Data" accesskey="4">Text Data</a></li>
<li><a href="#Temporal-Data" accesskey="5">Temporal Data</a></li>
<li><a href="#Extreme-values" accesskey="6">Extreme values</a></li>
</ul>
<div class="section" id="Atom-Types-1">
<h3 class="section">4.1 Atom Types</h3>
<p>This section lists all the different types available.  Generally lower case specifies atoms and upper case as lists.
</p>
<table>
<tr><td width="10%"><b>name</b></td><td width="15%"><b>type</b></td><td width="45%"><b>example</b></td><td width="40%"><b>note</b></td></tr>
<tr><td width="10%"></td><td width="15%"></td><td width="45%"></td></tr>
<tr><td width="10%">b</td><td width="15%">boolean</td><td width="45%">1b</td><td width="40%"></td></tr>
<tr><td width="10%">c</td><td width="15%">character</td><td width="45%">&ldquo;a&rdquo;</td><td width="40%"></td></tr>
<tr><td width="10%">d</td><td width="15%">date</td><td width="45%">2020.06.14</td><td width="40%"></td></tr>
<tr><td width="10%">e</td><td width="15%">float</td><td width="45%">3.1</td><td width="40%"></td></tr>
<tr><td width="10%">f</td><td width="15%">float</td><td width="45%">3.1f</td><td width="40%"></td></tr>
<tr><td width="10%">g</td><td width="15%">int</td><td width="45%">2g</td><td width="40%">1 byte unsigned</td></tr>
<tr><td width="10%">h</td><td width="15%">int</td><td width="45%">2h</td><td width="40%">2 byte unsigned</td></tr>
<tr><td width="10%">i</td><td width="15%">int</td><td width="45%">2</td><td width="40%">4 byte unsigned</td></tr>
<tr><td width="10%">j</td><td width="15%">int</td><td width="45%">2j</td><td width="40%">8 byte signed</td></tr>
<tr><td width="10%">n</td><td width="15%">name</td><td width="45%"><em class='math'>`</em>abc</td><td width="40%">8 char max</td></tr>
<tr><td width="10%">s</td><td width="15%">time</td><td width="45%">12:34:56</td><td width="40%">second</td></tr>
<tr><td width="10%">S</td><td width="15%">datetime</td><td width="45%">2020.06.15T12:34:56</td><td width="40%">second</td></tr>
<tr><td width="10%">t</td><td width="15%">time</td><td width="45%">12:34:56.123</td><td width="40%">millisecond</td></tr>
<tr><td width="10%">T</td><td width="15%">datetime</td><td width="45%">2020.06.15T12:34:56.123</td><td width="40%">millisecond</td></tr>
<tr><td width="10%">u</td><td width="15%">time</td><td width="45%">12:34:56.123456</td><td width="40%">microsecond</td></tr>
<tr><td width="10%">U</td><td width="15%">datetime</td><td width="45%">2020.06.15T12:34:56.123456</td><td width="40%">microsecond</td></tr>
<tr><td width="10%">v</td><td width="15%">time</td><td width="45%">12:34:56.123456789</td><td width="40%">nanosecond</td></tr>
<tr><td width="10%">V</td><td width="15%">datetime</td><td width="45%">2020.06.15T12:34:56.123456789</td><td width="40%">nanosecond</td></tr>
</table>


<span id="bool"></span></div>
<div class="section" id="bool-_21d2-Boolean-b">
<h3 class="section">4.2 bool &rArr; Boolean b</h3>
<p>Booleans have two possible values 0 and 1 and have a &rsquo;b&rsquo; to avoid confusion with integers, eg. 0b or 1b.
</p>
<div class="example">
<pre class="example">&nbsp;0b
0b
&nbsp;1b
1b
&nbsp;10101010b
10101010b
</pre></div>

<ul class="section-toc">
<li><a href="#boolean-logic" accesskey="1">boolean logic</a></li>
</ul>
<div class="subsection" id="boolean-logic">
<h4 class="subsection">4.2.1 boolean logic</h4>
<p>k9 implements logic operations in the usual way.
</p>
<div class="example">
<pre class="example"> x:0101b;y:0011b

[[x:x;y:y]AND:x&amp;y;OR:x|y;NAND:~x&amp;y;NOR:~x|y;XOR:~x=y;XNOR:x=y]
x y|AND OR NAND NOR XOR XNOR
- -|--- -- ---- --- --- ----
0 0|  0  0    1   1   0    1
1 0|  0  1    1   0   1    0
0 1|  0  1    1   0   1    0
1 1|  1  1    0   0   0    1
</pre></div>

</div>
</div>
<div class="section" id="Numeric-Data">
<h3 class="section">4.3 Numeric Data</h3>
<p>Numbers can be stored as integers and floats.
</p>
<span id="int"></span><ul class="section-toc">
<li><a href="#int-_21d2-Integer-g_002c-h_002c-i_002c-j" accesskey="1">int &rArr; Integer g, h, i, j</a></li>
<li><a href="#float-_21d2-Float-e_002c-f" accesskey="2">float &rArr; Float e, f</a></li>
<li><a href="#fixed-_21d2-Float-e_002c-f" accesskey="3">fixed &rArr; Float e, f</a></li>
<li><a href="#locus-_21d2-Float-e_002c-f" accesskey="4">locus &rArr; Float e, f</a></li>
</ul>
<div class="subsection" id="int-_21d2-Integer-g_002c-h_002c-i_002c-j">
<h4 class="subsection">4.3.1 int &rArr; Integer g, h, i, j</h4>
<p>Integers can be stored in four different ways which correspond 1, 2, 4, and 8 bytes.  The first three are unsigned and the last (j) is signed.  Positive numbers default to i and negative and very large numbers default to j.  One can specify a non-default type by adding one of the four letters immediately following the number.
</p>
<div class="example">
<pre class="example"> @37    / will default to i
`i
 @-37   / negative so will default to j
`j

 @37g   / cast as g, one byte unsigned
`g

b:{-1+*/x#256}
 `g b[1]
255g
 `h b[2]
65535h
 `i b[4]
4294967295
 `j b[7]
72057594037927935
</pre></div>

<span id="float"></span></div>
<div class="subsection" id="float-_21d2-Float-e_002c-f">
<h4 class="subsection">4.3.2 float &rArr; Float e, f</h4>
<p>Float
</p><div class="example">
<pre class="example"> 3.1
3.1
 3.1+1.2
4.3
 3.1-1.1   
2.
 @3.1-1.1
`e
 @3.1
`e
 a:3.1;
 @a
`e
 @1%3
`f
</pre></div>

<span id="fixed"></span></div>
<div class="subsection" id="fixed-_21d2-Float-e_002c-f">
<h4 class="subsection">4.3.3 fixed &rArr; Float e, f</h4>
<p>Fixed TBD
</p>
<div class="example">
<pre class="example"> 2 3e4
2.000e+00 3.000e+04
</pre></div>

<span id="locus"></span></div>
<div class="subsection" id="locus-_21d2-Float-e_002c-f">
<h4 class="subsection">4.3.4 locus &rArr; Float e, f</h4>
<p>Locus TBD
</p>
<div class="example">
<pre class="example"> -74::40.7
4.07e+01
</pre></div>

</div>
</div>
<div class="section" id="Text-Data">
<h3 class="section">4.4 Text Data</h3>
<p>Text data come in characters, lists of characters (aka strings) and enumerated types.  Enumerated types are displayed as text but stored internally as integers.
</p>
<span id="char"></span><ul class="section-toc">
<li><a href="#char-_21d2-Character-c" accesskey="1">char &rArr; Character c</a></li>
<li><a href="#sym-_21d2-Name-n" accesskey="2">sym &rArr; Name n</a></li>
</ul>
<div class="subsection" id="char-_21d2-Character-c">
<h4 class="subsection">4.4.1 char &rArr; Character c</h4>
<p>Characters are stored as their ANSI value and can be seen by conversion to integers.  A string is a list of characters (including blanks).
</p>
<div class="example">
<pre class="example">&nbsp;@&quot;b&quot;
`c
&nbsp;@&quot;bd&quot;
`C 
</pre></div>

<span id="sym"></span></div>
<div class="subsection" id="sym-_21d2-Name-n">
<h4 class="subsection">4.4.2 sym &rArr; Name n</h4>
<p>A symbol (sym) is an enumerated type displayed as a text string but stored internally as an integer value.
</p>
<div class="example">
<pre class="example">&nbsp;@`blue
`n
&nbsp;@`blue`red
`N
</pre></div>

</div>
</div>
<div class="section" id="Temporal-Data">
<h3 class="section">4.5 Temporal Data</h3>
<p>Temporal data can be expressed as time, date, or a combined date and time.
</p>
<span id="time"></span><ul class="section-toc">
<li><a href="#time-_21d2-Time-s_002c-t_002c-u_002c-v" accesskey="1">time &rArr; Time s, t, u, v</a></li>
<li><a href="#date-_21d2-Date-d" accesskey="2">date &rArr; Date d</a></li>
<li><a href="#datetime-_21d2-Datetime-d" accesskey="3">datetime &rArr; Datetime d</a></li>
</ul>
<div class="subsection" id="time-_21d2-Time-s_002c-t_002c-u_002c-v">
<h4 class="subsection">4.5.1 time &rArr; Time s, t, u, v</h4>
<p>Time has four types depending on the level of precision.  The types are seconds (s), milliseconds (t), microseconds (u), and nanoseconds (v).  The times are all stored internally as integers.  The integers are the number of time units.  For example 00:00:00.012 and 00:00:00.000000012 are both stored as 12 internally.
</p>
<div class="example">
<pre class="example"> @12:34:56.789             / time
`t
 .z.t                       / current time in GMT (Greenwich Mean Time)
17:32:57.995
 t: .z.t-17:30:00.000; t
00:03:59.986
 t
17:33:59.986
 `i 00:00:00.001            / numeric representation of 1ms
1
 `i 00:00:01.000            / numeric representation of 1s
1000
 `i 00:01:00.000            / numeric representation of 1m
60000
 `t 12345                   / convert number to milliseconds
00:00:12.345
</pre></div>

<span id="date"></span></div>
<div class="subsection" id="date-_21d2-Date-d">
<h4 class="subsection">4.5.2 date &rArr; Date d</h4>
<p>Dates are in yyyy.mm.dd format.  Dates are stored internally as integers with 0 corresponding to 2001.01.01.
</p>
<div class="example">
<pre class="example"> @2020.04.20               / date
`d
 .z.d                       / current date in GMT
2020.12.05
 `i .z.d                    / numeric representation of date
7278
 `i 2001.01.01              / zero date
0
 `d 0                       / zero date
2001.01.01
</pre></div>

<span id="datetime"></span></div>
<div class="subsection" id="datetime-_21d2-Datetime-d">
<h4 class="subsection">4.5.3 datetime &rArr; Datetime d</h4>
<p>Dates and times can be combined into a single datetime element by combining a date, the letter T, and the time together without spaces.  The datetime use the same lettering as the time precision but in uppercase.  Datetimes are stored interally as integers.  For example 2001.01.02T00:00:00.000 is stored as 86,400,000, the number of milliseconds in a day.
</p>
<div class="example">
<pre class="example"> @2020.04.20T12:34:56.789  / date and time
`d
 `T$&quot;2020.04.20 12:34:56.789&quot; / converting from string
2020.04.20T12:34:56.789
</pre></div>

</div>
</div>
<div class="section" id="Extreme-values">
<h3 class="section">4.6 Extreme values</h3>
<p>Data types can represent in-range, null, and out-of-range values.
</p>
<table>
<tr><td width="15%"><b>type</b></td><td width="15%"><b>null</b></td><td width="20%"><b>out of range</b></td></tr>
<tr><td width="15%">i</td><td width="15%">0N</td><td width="20%">0W</td></tr>
<tr><td width="15%">f</td><td width="15%">0n</td><td width="20%">0w</td></tr>
</table>

<div class="example">
<pre class="example">&nbsp;0%0
0n
&nbsp;1e500
0w
</pre></div>

<hr>
</div>
</div>
<div class="chapter" id="List">
<div class="header">
<p>
Next: <a href="#Dictionary" accesskey="n" rel="next">Dictionary</a>, Previous: <a href="#Noun" accesskey="p" rel="prev">Noun</a>, Up: <a href="#Top" accesskey="u" rel="up">k9: Manual</a> &nbsp; </p>
</div>
<span id="List-1"></span><h2 class="chapter">5 List</h2>
<p>Lists and derivatives of lists are fundamental to k9 which makes sense given that the language is made to process large quantites of data.  Performance will be best when working with uniform lists of a single data type but k9 supports list of non-uniform type also.
</p>
<p>Lists are automatically formed when a sequence of uniform type are entered or generated by any function.
</p>
<div class="example">
<pre class="example"> 1 3 12      / list of ints
1 3 12

 3.1 -4.1 5. / list of floats
3.1 -4.1 5.

 &quot;abc&quot;       / list of chars
&quot;abc&quot;

 `x`y`z      / list of names
`x`y`z
</pre></div>

<p>In order to determine if data is an atom or a list, one can use the <a href="#type">type</a> command.  The command returns a lower case value for atoms and an upper case value for lists.
</p>
<div class="example">
<pre class="example"> @1          / an integer
`i

@1 3 12     / list of ints
`I

@,1         / list of single int via <a href="#enlist">list</a>
`I
</pre></div>

<p>Commands that generate sequences of numbers return lists regardless of whether the count (length of the list) is 1 or many.
</p>
<div class="example">
<pre class="example"> @!0
`I
 @!1
`I
 @!2
`I
</pre></div>

<ul class="section-toc">
<li><a href="#List-Syntax" accesskey="1">List Syntax</a></li>
<li><a href="#List-Indexing" accesskey="2">List Indexing</a></li>
<li><a href="#List-of-Lists-Indexing" accesskey="3">List of Lists Indexing</a></li>
<li><a href="#Updating-List-Elements" accesskey="4">Updating List Elements</a></li>
<li><a href="#Function-Applied-to-Lists" accesskey="5">Function Applied to Lists</a></li>
<li><a href="#Functions-Applied-to-Two-Lists" accesskey="6">Functions Applied to Two Lists</a></li>
</ul>
<div class="section" id="List-Syntax">
<h3 class="section">5.1 List Syntax</h3>
<p>In general, lists consist of elements separated by semicolons and encased by parenthesis.
</p>
<div class="example">
<pre class="example"> (1;3;12)         / list of ints
1 3 12

@(1;3.;`a;&quot;b&quot;)   / non-uniform list
`L

@((1;3);(12;0))  / list of integer lists
LI

@'((1;3);(12;0)) / each list is type I
`I`I

,,,,,(3;1)      / a list of a list of a list..
,,,,,3 1
</pre></div>

</div>
<div class="section" id="List-Indexing">
<h3 class="section">5.2 List Indexing</h3>
<p>Lists can be indexed in different ways.  The @ notation is often used as it&rsquo;s fewer characters than [] and the explicit @ instead of space is likely more clear.
</p>
<div class="example">
<pre class="example"> a:2*1+!10 / 2 4 ... 20
 a[9]      / square bracket
20
 a@9       / at
20
 a 9       / space 
20
 a(9)      / parenthesis
20
 a[10]     / out of range return zero
0
</pre></div>

</div>
<div class="section" id="List-of-Lists-Indexing">
<h3 class="section">5.3 List of Lists Indexing</h3>
<p>A list of lists can be indexed by succesive index operations left to right.
</p>
<div class="example">
<pre class="example"> x:3^!12;x  / cut a list into a matrix or list of lists
0 1 2 3  
4 5 6 7  
8 9 10 11

 x[0]        / index the first element which is a list
0 1 2 3

 x[0 2]      / index two elements, the 0 and 2 elements
0 1 2 3  
8 9 10 11

 x[0;2]      / index the first row and then 2 element of that row
2

 x[;2][0]    / index the 2 column and then the 0 row
2

 x[0][2]     / index the 0 row and then the 2 column
2
</pre></div>

</div>
<div class="section" id="Updating-List-Elements">
<h3 class="section">5.4 Updating List Elements</h3>
<p>Lists can be updated elementwise by  setting the indexed element to a required value.  There is also a syntax for updating many elements and that is found at <a href="#amend">amend</a>.
</p>
<div class="example">
<pre class="example"> a:2*1+!10;a
2 4 6 8 10 12 14 16 18 20
 a[3]:80
 a
2 4 6 80 10 12 14 16 18 20
</pre></div>

</div>
<div class="section" id="Function-Applied-to-Lists">
<h3 class="section">5.5 Function Applied to Lists</h3>
<p>Most functions can be applied to lists without special syntax as if it was an element.
</p>
<div class="example">
<pre class="example"> x:!3;x
0 1 2

 x+10
10 11 12

 +\x
0 1 3

 +/x
3

 {x*x:sin x}[x]
0 0.7080734 0.8268218
</pre></div>

</div>
<div class="section" id="Functions-Applied-to-Two-Lists">
<h3 class="section">5.6 Functions Applied to Two Lists</h3>
<p>This section will focus on functions (f) that operate on two lists (x and y).  As these are internal functions, examples will be shown with infix notation (x+y) but prefix notation (+[x;y]) would  also be possible.
</p>
<ul class="section-toc">
<li><a href="#Pairwise" accesskey="1">Pairwise</a></li>
<li><a href="#Each-Element-of-One-List-Compared-to-Entire-Other-List" accesskey="2">Each Element of One List Compared to Entire Other List</a></li>
<li><a href="#Each-List-Used-Symmetrically" accesskey="3">Each List Used Symmetrically</a></li>
</ul>
<div class="subsection" id="Pairwise">
<h4 class="subsection">5.6.1 Pairwise</h4>
<p>These functions operate on list elements pairwise and thus requires that x and y are equal length.
</p><ul>
<li> <tt>x+y : Add</tt>
</li><li> <tt>x-y : Subtract</tt>
</li><li> <tt>x*y : Multiply</tt>
</li><li> <tt>x%y : Divide</tt>
</li><li> <tt>x&amp;y : AND/Min</tt>
</li><li> <tt>x|y : OR/Max</tt>
</li><li> <tt>x&gt;y : Greater Than</tt>
</li><li> <tt>x&lt;y : Less Than</tt>
</li><li> <tt>x=y : Equals</tt>
</li><li> <tt>x!y : Dictionary</tt>
</li></ul>

<div class="example">
<pre class="example">&nbsp;x:1+!5; y:10-2*!5
&nbsp;x
1 2 3 4 5
&nbsp;y
10 8 6 4 2
&nbsp;x+y
11 10 9 8 7
&nbsp;x-y
-9 -6 -3 0 3
&nbsp;x*y
10 16 18 16 10
&nbsp;x%y
0.1 0.25 0.5 1 2.5f
&nbsp;x&amp;y
1 2 3 4 2
&nbsp;x|y
10 8 6 4 5
&nbsp;x&gt;y
00001b
&nbsp;x&lt;y
11100b
&nbsp;x=y
00010b
&nbsp;x!y
1|10
2| 8
3| 6
4| 4
5| 2
</pre></div>

</div>
<div class="subsection" id="Each-Element-of-One-List-Compared-to-Entire-Other-List">
<h4 class="subsection">5.6.2 Each Element of One List Compared to Entire Other List</h4>
<p>These functions compare x[i] to y or x to y[i]. They are  not symmetric to their inputs, i.e. f[x;y] does not equal f[y;x];
</p>
<ul>
<li> <tt>x^y : Reshape all element in y by x</tt>
</li><li> <tt>x#y : List all elements in x that appear in y</tt>
</li><li> <tt>x?y : Indices of elements of y in x else return the length of x.</tt>
</li></ul>

<div class="example">
<pre class="example"> x:0 2 5 10
 y:!20
 x^y
0 1                          
2 3 4                        
5 6 7 8 9                    
10 11 12 13 14 15 16 17 18 19

 x:2 8 20
 y:1 2 3 7 8 9
 x#y
2 8
 x?y
3 0 3 3 1 3
</pre></div>

</div>
<div class="subsection" id="Each-List-Used-Symmetrically">
<h4 class="subsection">5.6.3 Each List Used Symmetrically</h4>
<p>This is symmetric in its inputs f[x;y]=f[y;x] and the lists are not required to be equal length.
</p>
<ul>
<li> <tt>x_y : Values present in only one of the two lists</tt>
</li></ul>

<div class="example">
<pre class="example">&nbsp;x:2 8 20
&nbsp;y:1 2 3 7 8 9
&nbsp;x_y
1 3 7 9
</pre></div>


<hr>
</div>
</div>
</div>
<div class="chapter" id="Dictionary">
<div class="header">
<p>
Next: <a href="#User-Functions" accesskey="n" rel="next">User-defined Functions</a>, Previous: <a href="#List" accesskey="p" rel="prev">List</a>, Up: <a href="#Top" accesskey="u" rel="up">k9: Manual</a> &nbsp; </p>
</div>
<span id="Dictionary-1"></span><h2 class="chapter">6 Dictionary</h2>
<p>Dictionaries are a data type of key-value pairs typically used to retrieve the value by using the key.  In other computer languages they are also known as associative arrays and maps.  Keys should be unique to avoid lookup value confusion but uniqueness is not enforced.  The values in the dictionary can be single elements, lists, tables, or even other dictionaries.
</p>
<p>Dictionaries in k9 are often used.  As an example from finance, market quotes and trade data are dictionaries of symbols (name keys) and market data (table values).  
</p>
<ul class="section-toc">
<li><a href="#Dictionary-Creation-_21d2-x_0021y-or-_005bxi_003ayi_005d" accesskey="1">Dictionary Creation &rArr; x!y or [x<sub>i</sub>:y<sub>i</sub>]</a></li>
<li><a href="#Dictionary-Selection-_21d2-x_0023y-or-x_005fy" accesskey="2">Dictionary Selection &rArr; x#y or x_y</a></li>
<li><a href="#Dictionary-Join-_21d2-x_002cy" accesskey="3">Dictionary Join &rArr; x,y</a></li>
<li><a href="#Dictionary-Indexing-_21d2-x_0040y" accesskey="4">Dictionary Indexing &rArr; x@y</a></li>
<li><a href="#Dictionary-Key-_21d2-_0021x" accesskey="5">Dictionary Key &rArr; !x</a></li>
<li><a href="#Dictionary-Value-_21d2-x_005b_005d" accesskey="6">Dictionary Value &rArr; x[]</a></li>
<li><a href="#Sorting-a-Dictionary-by-Key-_21d2-_005ex" accesskey="7">Sorting a Dictionary by Key &rArr; ^x</a></li>
<li><a href="#Sorting-a-Dictionary-by-Value-_21d2-_003cx-_0028_003ex_0029" accesskey="8">Sorting a Dictionary by Value &rArr; &lt;x (&gt;x)</a></li>
<li><a href="#Flipping-a-Dictionary-into-a-Table-_21d2-_002bx" accesskey="9">Flipping a Dictionary into a Table &rArr; +x</a></li>
<li><a href="#Functions-that-operate-on-each-value-in-a-dictionary">Functions that operate on each value in a dictionary</a></li>
<li><a href="#Functions-that-return-over-values-from-a-dictionary">Functions that return over values from a dictionary</a></li>
</ul>
<div class="section" id="Dictionary-Creation-_21d2-x_0021y-or-_005bxi_003ayi_005d">
<h3 class="section">6.1 Dictionary Creation &rArr; x!y or [x<sub>i</sub>:y<sub>i</sub>]</h3>

<p>Dictionaries are created by using the key symbol or square bracket notation and listing the keys (x) and values (y).  
</p>
<p><code>x!y</code>
</p>
<div class="example">
<pre class="example"> d0:`a37!12; d0                          / key is `a37 and value is 12
a37|12

 d1:`pi`e`c!3.14 2.72 3e8;d1             / three keys `pi, `e, `c
pi|3.14 
e |2.72 
c |3e+08

 `a`b`c!(1 2 3;10 20 30;100 200 300 499) / values are lists
a|1 2 3      
b|10 20 30   
c|100 200 300 499
</pre></div>

<p><code>[x<sub>0</sub>:y<sub>0</sub>;x<sub>1</sub>:y<sub>1</sub>;...;x<sub>n</sub>:y<sub>n</sub>]</code>
</p>
<div class="example">
<pre class="example"> d0:[a37:12]
a37|12

 d1:[pi:3.14;e:2.72;c:3e8];d1
pi|3.14
e |2.72
c |3e+08

 [a:1 2 3;b:10 20 30;c:100 200 300]
a|1 2 3      
b|10 20 30   
c|100 200 300
</pre></div>

<p>Often one will need to modify the data while building the dictionary.  User defined functions can easily accomplish this task.
</p>
<div class="example">
<pre class="example"> `x`sinX`cosX!{(x;sin y;cos z)} . 3#,0.1*(!62)
x   |0 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1 1.1 ..
sinX|0 0.09983342 0.1986693 0.2955202 0.3894183 0..
cosX|1 0.9950042 0.9800666 0.9553365 0.921061 0.8..

</pre></div>

</div>
<div class="section" id="Dictionary-Selection-_21d2-x_0023y-or-x_005fy">
<h3 class="section">6.2 Dictionary Selection &rArr; x#y or x_y</h3>
<p>One can select a portion of a dictionary either by <a href="#take">take</a> or <a href="#drop">drop</a> which keeps and removes keys respectively.
</p>
<div class="example">
<pre class="example"> x:`a`b`c`d!4 2 3 1;x
a|4
b|2
c|3
d|1

 `b`c#x / take
b|2
c|3

 `b`c_x / drop
a|4
d|1
</pre></div>

</div>
<div class="section" id="Dictionary-Join-_21d2-x_002cy">
<h3 class="section">6.3 Dictionary Join &rArr; x,y</h3>
<p>This joins dictionaries together and the right or y dictionary will overwrite the left or x dictionary if common keys are present.
</p>
<div class="example">
<pre class="example"> d1:`a`b`c!3 2 1;d1
a|3
b|2
c|1

 d2:`c`d`e!90 80 70;d2
c|90
d|80
e|70

 ^d1,d2 / ^ sort by key
a| 3
b| 2
c|90
d|80
e|70

 ^d2,d1 / ^ sort by key
a| 3
b| 2
c| 1
d|80
e|70
</pre></div>

</div>
<div class="section" id="Dictionary-Indexing-_21d2-x_0040y">
<h3 class="section">6.4 Dictionary Indexing &rArr; x@y</h3>

<p>Dictionaries, like lists, can be key indexed in a number of ways.
</p>
<div class="example">
<pre class="example"> x:`a`b`c!(1 2;3 4;5 6);x
a|1 2
b|3 4
c|5 6

x@`a   / single index     
1 2

x@`a`c / multiple index   
1 2
5 6

/ all these notations for indexing work (output not shown)
 x@`b;  / at
 x(`b); / parenthesis
 x `b;  / space
 x[`b]; / square bracket
</pre></div>

</div>
<div class="section" id="Dictionary-Key-_21d2-_0021x">
<h3 class="section">6.5 Dictionary Key &rArr; !x</h3>
<p>The keys from a dictionary are retreived by using the ! function.
</p>
<div class="example">
<pre class="example">&nbsp;!d0
`pi`e`c
&nbsp;!d1
`time`temp
&nbsp;!d2
0 10 1
</pre></div>

</div>
<div class="section" id="Dictionary-Value-_21d2-x_005b_005d">
<h3 class="section">6.6 Dictionary Value &rArr; x[]</h3>
<p>The values from a dictionary are retrieved using bracket notation.
</p>
<div class="example">
<pre class="example"> d0[]
3.14 2.72 3e+08
 d1[]
12:00 12:01 12:10
25.   25.1  25.6 

 d2[]
37.4 46.3 0.1
</pre></div>

<p>One could return a specific value by indexing into a specific location.  As an example, in order to query the first value of the values associated with the key temp from d1, one would convert d1 into values (a pair of lists), and index that by [1;0]. 
</p>
<div class="example">
<pre class="example">&nbsp;d1
time|12:00 12:01 12:10
temp|25 25.1 25.6     

&nbsp;d1[]
12:00 12:01 12:10
25    25.1  25.6 

&nbsp;d1[][1]
25 25.1 25.6
&nbsp;d1[][1;0]
25.
</pre></div>

</div>
<div class="section" id="Sorting-a-Dictionary-by-Key-_21d2-_005ex">
<h3 class="section">6.7 Sorting a Dictionary by Key &rArr; ^x</h3>

<div class="example">
<pre class="example">&nbsp;d0
pi|3.14 
e |2.72 
c |3e+08

&nbsp;^d0
c |3e+08
e |2.72 
pi|3.14 
</pre></div>

</div>
<div class="section" id="Sorting-a-Dictionary-by-Value-_21d2-_003cx-_0028_003ex_0029">
<h3 class="section">6.8 Sorting a Dictionary by Value &rArr; &lt;x (&gt;x)</h3>

<div class="example">
<pre class="example">&nbsp;d0
pi|3.14 
e |2.72 
c |3e+08

&nbsp;&lt;d0
e |2.72 
pi|3.14 
c |3e+08

&nbsp;&gt;d0
c |3e+08
pi|3.14 
e |2.72 
</pre></div>

</div>
<div class="section" id="Flipping-a-Dictionary-into-a-Table-_21d2-_002bx">
<h3 class="section">6.9 Flipping a Dictionary into a Table &rArr; +x</h3>
<p>This command flips a dictionary into a table and will be covered in detail in the table chapter.
</p>
<div class="example">
<pre class="example"> d1
time|12:00 12:01 12:10
temp|25 25.1 25.6     

 +d1
time  temp
----- ----
12:00 25  
12:01 25.1
12:10 25.6

 d1~+d1
0b
</pre></div>

</div>
<div class="section" id="Functions-that-operate-on-each-value-in-a-dictionary">
<h3 class="section">6.10 Functions that operate on each value in a dictionary</h3>
<p>There are a number of simple functions on dictionaries that operate on their values.  If &rsquo;f&rsquo; is a function then f applied to a dictionary returns a dictionary with the same keys and the values resulting from the application of &rsquo;f&rsquo;.
</p>
<ul>
<li> <tt>-d : Negate</tt>
</li><li> <tt>d + N : Add N to d</tt>
</li><li> <tt>d - N : Subtract N from d</tt>
</li><li> <tt>d * N : Multiple d by N</tt>
</li><li> <tt>d % N : Divide d by N</tt>
</li><li> <tt>|d : Reverse</tt>
</li><li> <tt>&lt;d : Sort Ascending</tt>
</li><li> <tt>&gt;d : Sort Descending</tt>
</li><li> <tt>~d : Not d</tt>
</li><li> <tt>&amp;d : Given d:x!y output each x, y times, where y must be an integer</tt>
</li><li> <tt>=d : Given d:x!y y!x</tt>
</li></ul>

<p>Examples
</p><div class="example">
<pre class="example">&nbsp;d2
&nbsp;0|37.4
10|46.3
&nbsp;1|0.1 

&nbsp;-d2
&nbsp;0|-37.4
10|-46.3
&nbsp;1|-0.1 

&nbsp;d2+3
&nbsp;0|40.4
10|49.3
&nbsp;1|3.1 

&nbsp;d2-1.7
&nbsp;0|35.7
10|44.6
&nbsp;1|-1.6

&nbsp;d2*10
&nbsp;0|374
10|463
&nbsp;1|1  

&nbsp;d2%100
&nbsp;0|0.374
10|0.463
&nbsp;1|0.001
</pre></div>

</div>
<div class="section" id="Functions-that-return-over-values-from-a-dictionary">
<h3 class="section">6.11 Functions that return over values from a dictionary</h3>
<p>There are functions on dictionaries that operate over the values.  Given function f applied to a dictionary d, f d returns one or more values  without the original keys.
</p>
<ul>
<li> *d : First value
</li></ul>
<div class="example">
<pre class="example">&nbsp;d0
pi|3.14
e |2.72
c |3e+08

&nbsp;*d0
3.14
</pre></div>

<hr>
</div>
</div>
<div class="chapter" id="User-Functions">
<div class="header">
<p>
Next: <a href="#Expression" accesskey="n" rel="next">Expression Evaluation</a>, Previous: <a href="#Dictionary" accesskey="p" rel="prev">Dictionary</a>, Up: <a href="#Top" accesskey="u" rel="up">k9: Manual</a> &nbsp; </p>
</div>
<span id="User_002ddefined-Functions"></span><h2 class="chapter">7 User-defined Functions</h2>
<p>User-defined functions are treated as verbs in k9, so can benefit from the adverbs.
</p>
<p>Multi-line functions must be defined with an initial space on all lines except the first.  These can be loaded into memory by using the <a href="#load">\l</a> command and then used by calling by name.
</p>
<div class="example">
<pre class="example">Func {[a;b]a+b}
</pre></div>

<ul class="section-toc">
<li><a href="#Function-arguments" accesskey="1">Function arguments</a></li>
<li><a href="#Function-Defitions" accesskey="2">Function Defitions</a></li>
<li><a href="#Function-Return" accesskey="3">Function Return</a></li>
<li><a href="#Calling-functions" accesskey="4">Calling functions</a></li>
<li><a href="#Anonymous-functions" accesskey="5">Anonymous functions</a></li>
<li><a href="#Recursive-functions" accesskey="6">Recursive functions</a></li>
<li><a href="#Chained-functions" accesskey="7">Chained functions</a></li>
</ul>
<div class="section" id="Function-arguments">
<h3 class="section">7.1 Function arguments</h3>
<p>Functions default to arguments of x, y, and z for the first three parameters but one  can  explicitly spell out these or other argument names.  Given k9&rsquo;s terseness, many k9 programmers prefer short variable names. But this is a matter of taste.
</p>
<div class="example">
<pre class="example"> f1:{x+2*y}         / implicit arguments x and y
 f1[2;10]
22

 f2:{[x;y]x+2*y}    / explicit
 f2[2;10]
22

 f3:{[g;h]g+2*h}    / explicit arguments other than x and y
 f3[2;10]
22

 f4:{[please;dont]please+2*dont} / longer argument names are possible
 f4[2;10]
22

 @f1
`.
</pre></div>

</div>
<div class="section" id="Function-Defitions">
<h3 class="section">7.2 Function Defitions</h3>
<p>Functions can have intermediate calcuations and local variables.  Function local variables do not affect the values of  global variables.
</p>
<div class="example">
<pre class="example"> a:3;a
3

 f:{a:12;x:sqrt x;x+a}

 f 10
15.16228

a
3
</pre></div>

</div>
<div class="section" id="Function-Return">
<h3 class="section">7.3 Function Return</h3>
<p>Function return the last value in the definition unless the definition ends with a semicolon in which case the function returns nothing.
</p>
<div class="example">
<pre class="example"> f:{x+2;};f 10  / returns nothing because of final semi-colon

 f:{x+2;27};f 10  / returns the last value which is 27
27

 f:{x+2};f 10
12
</pre></div>

</div>
<div class="section" id="Calling-functions">
<h3 class="section">7.4 Calling functions</h3>
<p>Functions, like lists, can be called in a variety of ways.  Typically one uses square bracket notation when the function takes multiple argruments.  If a function is called with fewer than the required number of arguments then it will return a function that requires the remaining arguemnts.
</p>
<div class="example">
<pre class="example"> f1:{[x] x}
 f2:{[x;y](x;y)}
 f3:{[x;y;z](x;y;z)}
 
 f1[`a]
`a

 f2[37;`a]
37
a 

 f3[&quot;hi&quot;;37;`a]
hi
37
a 

 f2[37]     
{[x;y](x;y)}[37]
 f2[;`a]
{[x;y](x;y)}[;`a]

 f1[`a]
`a
 f1 `a
`a
 f1@`a
`a
</pre></div>

</div>
<div class="section" id="Anonymous-functions">
<h3 class="section">7.5 Anonymous functions</h3>
<p>It&rsquo;s possible to define a function without naming it. If the function is to be used in just one place, this can make sense.
</p>
<div class="example">
<pre class="example"> {x+2*y}[2;10]
22
</pre></div>

</div>
<div class="section" id="Recursive-functions">
<h3 class="section">7.6 Recursive functions</h3>
<p>k9 allows one to define a function which calls itself.  Care should be taken to avoid an infinite loop.
</p>
<div class="example">
<pre class="example"> f:{$[x&gt;1;x*f@x-1;1]};f 5
120
</pre></div>

</div>
<div class="section" id="Chained-functions">
<h3 class="section">7.7 Chained functions</h3>
<p>It may be necessary to define a function to call a function without specifying arguments.  Imagine this trivial case.
</p>
<div class="example">
<pre class="example"> fa:{!x}
 fb:{x+2} fa
{x+2}
^
:rank
</pre></div>

<p>In order to succeed fa needs to have an <code>@</code> in the definition of fb.  This is required because fb calls fa without specifying an argument for fa. So the argument for fb becomes the argument for fa so the net effect is 2 + !3.
</p>
<div class="example">
<pre class="example"> fa:{!x}
 fb:{x+2} fa@
 fb 3
2 3 4
</pre></div>

<hr>
</div>
</div>
<div class="chapter" id="Expression">
<div class="header">
<p>
Next: <a href="#Named-Functions" accesskey="n" rel="next">Named Functions</a>, Previous: <a href="#User-Functions" accesskey="p" rel="prev">User-defined Functions</a>, Up: <a href="#Top" accesskey="u" rel="up">k9: Manual</a> &nbsp; </p>
</div>
<span id="Expression-Evaluation"></span><h2 class="chapter">8 Expression Evaluation</h2>
<p>k9 has a compact way to evaluate expressions on dictionaries.  This allows one to use the dictionary keys as local variables to get to results with less code.
</p>
<pre class="verbatim">Expr :a+b
</pre>
<ul class="section-toc">
<li><a href="#expr-_21d2-x-_003ay" accesskey="1">expr &rArr; x :y</a></li>
</ul>
<div class="section" id="expr-_21d2-x-_003ay">
<h3 class="section">8.1 expr &rArr; x :y</h3>
<p>Evaluate expression(s) <code>y</code> on table or dictionary <code>x</code>.  The space between <code>x</code> and <code>:</code> is required otherwise it becomes set, i.e., assignment.
</p>
<div class="example">
<pre class="example"> d:[city:`Chongqing`Shanhai`Beijing`Delhi`Chengdu]; d
city|`Chongqin`Shanhai`Beijing`Delhi`Chengdu

 d,:[country:`cn`cn`cn`in`cn;size:30 24 22 17 16] ; d
city   |`Chongqin`Shanhai`Beijing`Delhi`Chengdu
country|`cn`cn`cn`in`cn                        
size   |30 24 22 17 16                         

 d :&amp;country=`in       / using country like a local variable
,3

 d :sum'size@=country  / sum size by country
cn|92
in|17

 d :+/size*country=`cn
92
</pre></div>

<p>As keys come in scope as variables, variables fall out of scope.  One can evaluate the variable name as string to get around this.
</p>
<div class="example">
<pre class="example"> d :sum size@&amp;size&gt;20
76

 x:20;
 d :sum size@&amp;size&gt;x  / out of scope
!value

 d :sum size@&amp;size&gt;.&quot;x&quot;
76
</pre></div>

<p>Reorder a table using column index and expresssions.
</p>
<div class="example">
<pre class="example"> t:[[]x:`b`a`c;y:1 3 2];t
x y
- -
b 1
a 3
c 2

 t@&lt;t :y
x y
- -
b 1
c 2
a 3

 t@&lt;t`y
x y
- -
b 1
c 2
a 3
</pre></div>

<hr>
</div>
</div>
<div class="chapter" id="Named-Functions">
<div class="header">
<p>
Next: <a href="#Knit-Functions" accesskey="n" rel="next">Knit Functions</a>, Previous: <a href="#Expression" accesskey="p" rel="prev">Expression Evaluation</a>, Up: <a href="#Top" accesskey="u" rel="up">k9: Manual</a> &nbsp; </p>
</div>
<span id="Named-Functions-1"></span><h2 class="chapter">9 Named Functions</h2>
<p>This chapter covers the built-in  named functions.  This includes some math (eg. sqrt but not +), wrapper (eg. count for #) and range (eg. within) functions.
</p>
<div class="format">
<div class="example">
<pre class="example"><a href="#Hcount">count</a> <a href="#Hfirst">first</a> <a href="#Hlast">last</a> <a href="#Hmin">min</a> <a href="#Hmax">max</a> <a href="#Hsum">sum</a> <a href="#Hdot">dot</a> <a href="#avg">avg</a> <a href="#var">var</a> [dev med mode countd ..]
<a href="#sqrt">sqrt</a> <a href="#sqr">sqr</a> <a href="#exp">exp</a> <a href="#log">log</a> <a href="#sin">sin</a> <a href="#cos">cos</a> <a href="#div">div</a> <a href="#mod">mod</a> <a href="#bar">bar</a> <a href="#in">in</a> 
</pre></div>
</div>

<span id="Hcount"></span><ul class="section-toc">
<li><a href="#count-_21d2-count-x" accesskey="1">count &rArr; count x</a></li>
<li><a href="#first-_21d2-first-x" accesskey="2">first &rArr; first x</a></li>
<li><a href="#last-_21d2-last-x" accesskey="3">last &rArr; last x</a></li>
<li><a href="#min-_21d2-min-x" accesskey="4">min &rArr; min x</a></li>
<li><a href="#max-_21d2-max-x" accesskey="5">max &rArr; max x</a></li>
<li><a href="#sum-_21d2-sum-x" accesskey="6">sum &rArr; sum x</a></li>
<li><a href="#dot-_21d2-dot-x" accesskey="7">dot &rArr; dot x</a></li>
<li><a href="#avg-_21d2-avg-x" accesskey="8">avg &rArr; avg x</a></li>
<li><a href="#var-_21d2-var-x" accesskey="9">var &rArr; var x</a></li>
<li><a href="#dev-_21d2-dev-x">dev &rArr; dev x</a></li>
<li><a href="#med-_21d2-med-x">med &rArr; med x</a></li>
<li><a href="#mode-_21d2-mode-x">mode &rArr; mode x</a></li>
<li><a href="#countd-_21d2-countd-x">countd &rArr; countd x</a></li>
<li><a href="#exp-_21d2-exp-x">exp &rArr; exp x</a></li>
<li><a href="#log-_21d2-log-x">log &rArr; log x</a></li>
<li><a href="#sin-_21d2-sin-x">sin &rArr; sin x</a></li>
<li><a href="#cos-_21d2-cos-x">cos &rArr; cos x</a></li>
<li><a href="#sqr-_21d2-sqr-x">sqr &rArr; sqr x</a></li>
<li><a href="#prm-_21d2-prm-x">prm &rArr; prm x</a></li>
<li><a href="#sums-_21d2-sums-x">sums &rArr; sums x</a></li>
<li><a href="#deltas-_21d2-deltas-x-and-x-deltas-y">deltas &rArr; deltas x and x deltas y</a></li>
<li><a href="#has-_21d2-x-has-y">has &rArr; x has y</a></li>
<li><a href="#bin-_21d2-x-bin-y">bin &rArr; x bin y</a></li>
<li><a href="#in-_21d2-x-in-y">in &rArr; x in y</a></li>
<li><a href="#within-_21d2-x-within-y">within &rArr; x within y</a></li>
<li><a href="#bar-_21d2-x-bar-y">bar &rArr; x bar y</a></li>
<li><a href="#msum-_21d2-x-msum-y">msum &rArr; x msum y</a></li>
<li><a href="#mavg-_21d2-x-mavg-y">mavg &rArr; x mavg y</a></li>
</ul>
<div class="section" id="count-_21d2-count-x">
<h3 class="section">9.1 count &rArr; count x</h3>
<p>Same as <a href="#count">count</a>.
</p>
<div class="example">
<pre class="example"> count 5 1 2
3
</pre></div>

<span id="Hfirst"></span></div>
<div class="section" id="first-_21d2-first-x">
<h3 class="section">9.2 first &rArr; first x</h3>
<p>Same as <a href="#first">first</a>.
</p>
<div class="example">
<pre class="example"> first 5 1 2
5
</pre></div>

<span id="Hlast"></span></div>
<div class="section" id="last-_21d2-last-x">
<h3 class="section">9.3 last &rArr; last x</h3>
<p>Retrieve the last element of list x.
</p>
<div class="example">
<pre class="example"> last 5 1 2
2
</pre></div>

<span id="Hmin"></span></div>
<div class="section" id="min-_21d2-min-x">
<h3 class="section">9.4 min &rArr; min x</h3>
<p>Retrieve the minimum element of list x.  Same as <code>|/</code>.
</p>
<div class="example">
<pre class="example"> min 5 1 2
1
</pre></div>

<span id="Hmax"></span></div>
<div class="section" id="max-_21d2-max-x">
<h3 class="section">9.5 max &rArr; max x</h3>
<p>Retrieve the maximum element of list x.  Same as <code>&amp;/</code>.
</p>
<div class="example">
<pre class="example"> max 5 1 2
5
</pre></div>

<span id="Hsum"></span></div>
<div class="section" id="sum-_21d2-sum-x">
<h3 class="section">9.6 sum &rArr; sum x</h3>
<p>Compute the sum of list x.  Same as <code>+/</code>.
</p>
<div class="example">
<pre class="example"> sum 5 1 2
8
</pre></div>

<span id="Hdot"></span></div>
<div class="section" id="dot-_21d2-dot-x">
<h3 class="section">9.7 dot &rArr; dot x</h3>
<p>Compute the dot product of list x.  Same as <code>+/x*x</code>.
</p>
<div class="example">
<pre class="example"> dot 1.2 1.3 1.4
5.09

 {+/x*x} 1.2 1.3 1.4
5.09
</pre></div>

<span id="avg"></span></div>
<div class="section" id="avg-_21d2-avg-x">
<h3 class="section">9.8 avg &rArr; avg x</h3>
<p>Compute the average of list x.  Same as <code>+/x%#x</code>.
</p>
<div class="example">
<pre class="example"> avg 2 4 7 10
5.75

 {+/x%#x} 2 4 7 10
5.75
</pre></div>

<span id="var"></span></div>
<div class="section" id="var-_21d2-var-x">
<h3 class="section">9.9 var &rArr; var x</h3>
<p>Compute the variance of list x.
</p>
<div class="example">
<pre class="example"> var !10
8.25

 {(+/x*x:x-avg x)%#x}@!10
8.25
</pre></div>

<span id="dev"></span></div>
<div class="section" id="dev-_21d2-dev-x">
<h3 class="section">9.10 dev &rArr; dev x</h3>
<p>TBD
</p>
<span id="med"></span></div>
<div class="section" id="med-_21d2-med-x">
<h3 class="section">9.11 med &rArr; med x</h3>
<p>TBD
</p>
<span id="mode"></span></div>
<div class="section" id="mode-_21d2-mode-x">
<h3 class="section">9.12 mode &rArr; mode x</h3>
<p>TBD
</p>
<span id="countd"></span></div>
<div class="section" id="countd-_21d2-countd-x">
<h3 class="section">9.13 countd &rArr; countd x</h3>
<p>TBD
</p>
<span id="exp"></span></div>
<div class="section" id="exp-_21d2-exp-x">
<h3 class="section">9.14 exp &rArr; exp x</h3>
<p>Compute the exponent of x, i.e. e<sup>x</sup>.
</p>
<div class="example">
<pre class="example">&nbsp;exp 1
2.718282
</pre></div>

<span id="log"></span></div>
<div class="section" id="log-_21d2-log-x">
<h3 class="section">9.15 log &rArr; log x</h3>
<p>Log computes the natural log.
</p>
<div class="example">
<pre class="example">&nbsp;log 10
2.302585
</pre></div>

<span id="sin"></span></div>
<div class="section" id="sin-_21d2-sin-x">
<h3 class="section">9.16 sin &rArr; sin x</h3>
<p>sin computes the sine of x where x is in radians.
</p><div class="example">
<pre class="example">&nbsp;sin 0
0f
&nbsp;sin 3.1416%2
1.
</pre></div>

<span id="cos"></span></div>
<div class="section" id="cos-_21d2-cos-x">
<h3 class="section">9.17 cos &rArr; cos x</h3>
<p>cos computes the cosine of x where x is in radians.
</p><div class="example">
<pre class="example">&nbsp;cos 0
1f
&nbsp;cos 3.1416%4
0.7071055
</pre></div>

<span id="sqr"></span></div>
<div class="section" id="sqr-_21d2-sqr-x">
<h3 class="section">9.18 sqr &rArr; sqr x</h3>
<p>Compute the square of x.
</p>
<div class="example">
<pre class="example">&nbsp;sqr 2
4.0
</pre></div>

<span id="prm"></span></div>
<div class="section" id="prm-_21d2-prm-x">
<h3 class="section">9.19 prm &rArr; prm x</h3>
<p>Write out all permutations of integers up x-1. Display them as columns.
</p>
<div class="example">
<pre class="example"> prm 3
0 1 1 0 2 2
1 0 2 2 0 1
2 2 0 1 1 0
</pre></div>

<span id="sums"></span></div>
<div class="section" id="sums-_21d2-sums-x">
<h3 class="section">9.20 sums &rArr; sums x</h3>
<p>Compute the running sum of list x.  Sames as <code>+\</code>.
</p>
<div class="example">
<pre class="example"> sums !10
0 1 3 6 10 15 21 28 36 45
</pre></div>

<span id="deltas"></span></div>
<div class="section" id="deltas-_21d2-deltas-x-and-x-deltas-y">
<h3 class="section">9.21 deltas &rArr; deltas x and x deltas y</h3>
<p>Compute the difference between each element in list x and the previous value.  If delta is called with two parameters then x will be used as the first value to delta instead of the default 0.
</p>
<div class="example">
<pre class="example"> deltas 1 5 10
1 4 5

 1 deltas 1 5 10
0 4 5
</pre></div>

<span id="has"></span></div>
<div class="section" id="has-_21d2-x-has-y">
<h3 class="section">9.22 has &rArr; x has y</h3>
<p>Determine whether vector x has element y. Simliar to <a href="#in">in</a> but with the arguments reversed.
</p>
<div class="example">
<pre class="example"> `a`b`c`a`b has `a
1b

`a`b`c`a`b has `d
0b

 `a`b`c`a`b has `a`b`x`y`z
11000b

 (1 2;4 5 6;7 9)has(1 2;8 9)
10b
</pre></div>

<span id="bin"></span></div>
<div class="section" id="bin-_21d2-x-bin-y">
<h3 class="section">9.23 bin &rArr; x bin y</h3>
<p>Given a sorted (increasing) list x, find the greatest index, i, where y&gt;x[i].
</p>
<div class="example">
<pre class="example"> n:exp 0.01*!5;n
1 1.01005 1.020201 1.030455 1.040811
 n bin 1.025
3
</pre></div>

<span id="in"></span></div>
<div class="section" id="in-_21d2-x-in-y">
<h3 class="section">9.24 in &rArr; x in y</h3>
<p>Determine if x is in list y.  Similar to <a href="#has">has</a> but arguments reversed.
</p>
<div class="example">
<pre class="example">&nbsp;`b in `a`b`d`e
1b
&nbsp;`c in `a`b`d`e
0b
</pre></div>

<span id="within"></span></div>
<div class="section" id="within-_21d2-x-within-y">
<h3 class="section">9.25 within &rArr; x within y</h3>
<p>Test if x is equal to or greater than y[0] and less than y[1].
</p>
<div class="example">
<pre class="example"> 3 within 0 12
1b

0 within 0 12
1b

12 within 0 12
0b

23 within 0 12
0b
</pre></div>

<span id="bar"></span></div>
<div class="section" id="bar-_21d2-x-bar-y">
<h3 class="section">9.26 bar &rArr; x bar y</h3>
<p>For each value in y determine the maximum multiple of x that is less than or equal to each y.
</p>
<div class="example">
<pre class="example">&nbsp;10 bar 9 10 11 19 20 21
0 10 10 10 20 20
</pre></div>

<span id="msum"></span></div>
<div class="section" id="msum-_21d2-x-msum-y">
<h3 class="section">9.27 msum &rArr; x msum y</h3>
<p>Compute the length x  moving sum of list y.
</p>
<div class="example">
<pre class="example"> 3 msum !10
0 1 3 6 9 12 15 18 21 24
</pre></div>


<span id="mavg"></span></div>
<div class="section" id="mavg-_21d2-x-mavg-y">
<h3 class="section">9.28 mavg &rArr; x mavg y</h3>
<p>Compute the length x  moving average of list y.
</p>
<div class="example">
<pre class="example"> 3 mavg !10
0 0.3333333 1 2 3 4 5 6 7 8
</pre></div>

<hr>
</div>
</div>
<div class="chapter" id="Knit-Functions">
<div class="header">
<p>
Next: <a href="#I_002fO" accesskey="n" rel="next">I/O and Interface</a>, Previous: <a href="#Named-Functions" accesskey="p" rel="prev">Named Functions</a>, Up: <a href="#Top" accesskey="u" rel="up">k9: Manual</a> &nbsp; </p>
</div>
<span id="Knit-Functions-1"></span><h2 class="chapter">10 Knit Functions</h2>
<p>These functions modify lists and dictionaries given a list of indices and functions or values to replace.
</p>
<div class="example">
<pre class="example">@[r;i;f[;y]] <a href="#amend">amend</a>
.[r;i;f[;y]] <a href="#dmend">dmend</a>
</pre></div>

<span id="amend"></span><ul class="section-toc">
<li><a href="#amend-_21d2-_0040_005br_003bi_003bf_005b_003by_005d_005d" accesskey="1">amend &rArr; @[r;i;f[;y]]</a></li>
<li><a href="#dmend-_21d2-_002e_005br_003bi_003bf_005b_003by_005d_005d" accesskey="2">dmend &rArr; .[r;i;f[;y]]</a></li>
</ul>
<div class="section" id="amend-_21d2-_0040_005br_003bi_003bf_005b_003by_005d_005d">
<h3 class="section">10.1 amend &rArr; @[r;i;f[;y]]</h3>
<p>Replace the values in list / dictionary r at indices i with element f or function f and parameter y.  The original list is not modified.  Indices are rows for lists and keys for dictionaries.
</p>
<table>
<tr><td><b>action</b></td><td><b>f</b></td><td><b>y</b></td></tr>
<tr><td><a href="#amend1">amend with element</a></td><td>element</td><td>n/a</td></tr>
<tr><td><a href="#amend2">amend with element/array</a></td><td>:</td><td>element/list</td></tr>
<tr><td><a href="#amend3">amend with function 1 param</a></td><td>function</td><td>n/a</td></tr>
<tr><td><a href="#amend4">amend with function 2 param</a></td><td>function</td><td>2nd param</td></tr>
</table>

<span id="amend1"></span><p>Amend to element.
</p>
<div class="example">
<pre class="example"> r:(0 1;2 3;4 5;6);r
0 1
2 3
4 5
6  

 @[r;0 3;29]      / change the first and fourth rows
29 
2 3
4 5
29 

 r               / r doesn't change
0 1
2 3
4 5
6  
</pre></div>

<span id="amend2"></span><p>Amend with element/array.  If using an array, then the <code>i</code> and <code>y</code> must be arrays of equal length.
</p>
<div class="example">
<pre class="example"> r:(0 1;2 3;4 5;6);r
0 1
2 3
4 5
6  

 @[r;1 2;:;(0;3 5)]
0 1
0  
3 5
6  
</pre></div>

<span id="amend3"></span><p>Amend with function f[r] at indices i.
</p>
<div class="example">
<pre class="example"> r:(0 1;2 3;4 5;6);r
0 1
2 3
4 5
6  

 @[r;1 2;sqrt]
0 1              
1.414214 1.732051
2.0 2.236068     
6

 d:[x:`a`b`c;y:9 4 1];d / dictionary example
x|`a`b`c
y|9 4 1 

 @[d;`y;sqrt]
x|`a`b`c
y|3 2 1.
</pre></div>

<span id="amend4"></span><p>Amend with function f[r;y] at indices i.
</p>
<div class="example">
<pre class="example"> r:(0 1;2 3;4 5;6);r
0 1
2 3
4 5
6  

 @[r;1 2;*;10 100]
0 1    
20 30  
400 500
6      

 d:[x:`a`b`c;y:9 4 1];d / dictionary
x|`a`b`c
y|9 4 1 

 @[d;`y;*;10]
x|`a`b`c  
y|90 40 10
</pre></div>

<span id="dmend"></span></div>
<div class="section" id="dmend-_21d2-_002e_005br_003bi_003bf_005b_003by_005d_005d">
<h3 class="section">10.2 dmend &rArr; .[r;i;f[;y]]</h3>
<p>Similar to <a href="#amend">amend</a> but using <code>i</code> to fully index <code>r</code>.
</p>
<table>
<tr><td><b>action</b></td><td><b>f</b></td><td><b>y</b></td></tr>
<tr><td><a href="#dmend1">dmend with element</a></td><td>element</td><td>n/a</td></tr>
<tr><td><a href="#dmend3">dmend with function 1 param</a></td><td>function</td><td>n/a</td></tr>
<tr><td><a href="#dmend4">dmend with function 2 param</a></td><td>function</td><td>2nd param</td></tr>
</table>

<span id="dmend1"></span><p>Dmend to element.
</p>
<div class="example">
<pre class="example"> r:(0 1;2 3;4 5;6);r
0 1
2 3
4 5
6  

 .[r;0 1;12]       / modify the entry at [0;1]
0 12
2 3 
4 5 
6   
</pre></div>

<span id="dmend3"></span><p>Dmend with function f[r] at indices i.
</p>
<div class="example">
<pre class="example"> r:(0 1;2 3;4 5;6);r
0 1
2 3
4 5
6  

 .[r;1 1;sqrt]
0 1         
2.0 1.732051
4 5         
6           
</pre></div>

<span id="dmend4"></span><p>Dmend with function f[r;y] at indices i.
</p>
<div class="example">
<pre class="example"> r:(0 1;2 3;4 5;6);r
0 1
2 3
4 5
6  

 .[r;1 1;+;100]
0 1  
2 103
4 5  
6    
</pre></div>

<hr>
</div>
</div>
<div class="chapter" id="I_002fO">
<div class="header">
<p>
Next: <a href="#FF" accesskey="n" rel="next">Foreign Functions</a>, Previous: <a href="#Knit-Functions" accesskey="p" rel="prev">Knit Functions</a>, Up: <a href="#Top" accesskey="u" rel="up">k9: Manual</a> &nbsp; </p>
</div>
<span id="I_002fO-and-Interface"></span><h2 class="chapter">11 I/O and Interface</h2>
<p>This chapter covers reading and writing to file (File I/O), interprocess communication (IPC), and working with pre-built shared libraries (csv, json, lz4, and zstd).
</p>
<div class="example">
<pre class="example"> i/o(*enterprise)
 0: <a href="#r-line">r</a>/<a href="#w-line">w</a> line
 1: <a href="#r-char">r</a>/<a href="#w-char">w</a> char
*2: <a href="#r-data">r</a>/<a href="#w-data">w</a> data
*3: <a href="#k_002dipc">k-ipc</a> <a href="#g_t3set">set</a>    
*4: <a href="#https">https</a> <a href="#g_t4get">get</a>
 5: <a href="#ffi">ffi</a>/<a href="#import">import</a>

 `<a href="#csv">csv</a>?`<a href="#csv">csv</a> t;`<a href="#json">json</a>?`<a href="#json">json</a> t                                                   
 `<a href="#compress">lz4</a>?`<a href="#compress">lz4</a> t;`<a href="#compress">zstd</a>?`<a href="#compress">zstd</a> t  

</pre></div>

<ul class="section-toc">
<li><a href="#File-I_002fO" accesskey="1">File I/O</a></li>
<li><a href="#IPC" accesskey="2">IPC</a></li>
<li><a href="#ffi_002fimport" accesskey="3">ffi/import</a></li>
</ul>
<div class="section" id="File-I_002fO">
<h3 class="section">11.1 File I/O</h3>
<p>k9 reads and writes to files in three different formats including line (list of strings), char (list of characters), and data (k9 format).
</p>
<ul class="section-toc">
<li><a href="#Example-File-I_002fO" accesskey="1">Example File I/O</a></li>
<li><a href="#read-line-_21d2-0_003ax" accesskey="2">read line &rArr; 0:x</a></li>
<li><a href="#write-line-_21d2-x-0_003ay" accesskey="3">write line &rArr; x 0:y</a></li>
<li><a href="#read-char-_21d2-1_003ax" accesskey="4">read char &rArr; 1:x</a></li>
<li><a href="#write-char-_21d2-x-1_003ay" accesskey="5">write char &rArr; x 1:y</a></li>
<li><a href="#read-data-_21d2-2_003a-x" accesskey="6">read data &rArr; 2: x</a></li>
<li><a href="#write-data-_21d2-x-2_003a-y" accesskey="7">write data &rArr; x 2: y</a></li>
</ul>
<div class="subsection" id="Example-File-I_002fO">
<h4 class="subsection">11.1.1 Example File I/O</h4>
<p>Let&rsquo;s begin with a simple example to creat a sample table, write to csv and then read it back in again.  We&rsquo;ll use a function so the table can easily grow to a larger size.
</p>
<div class="example">
<pre class="example"> g:{+`s`f`i!(x?&quot;abc&quot;;x?10.;x?10)} / generate function for table

g[5]                              / generate table with 5 rows
s f          i
- ---------- -
c 1.296544   4
c 0.03771765 7
c 3.371475   0
b 1.352739   4
b 1.187619   5

`csv@g[5]                         / convert table to csv string
&quot;s,f,i\nb,1.08707,3\na,5.506882,0\nc,8.938667,1\nc,6.217895,6\nb,1.542842,6\n&quot;

 &quot;sample.csv&quot;1:`csv@g[5]          / write to sample.csv file
&quot;sample.csv&quot;

 1:&quot;sample.csv&quot;                   / read from file
&quot;s,f,i\na,3.669518,1\na,0.001226037,7\nb,2.792163,3\nc,8.539221,7\nb,9.333188,7\n&quot;

 `csv?1:&quot;sample.csv&quot;              / read from file and convert from csv
s f           i
- ----------- -
a 3.669518    1
a 0.001226037 7
b 2.792163    3
c 8.539221    7
b 9.333188    7
</pre></div>

<p>Given the small size of the file all this happens too quickly to notice the speed.  Let&rsquo;s give it a go with a bigger file.
</p>
<div class="example">
<pre class="example"> \t &quot;sample.csv&quot;1:`csv@g[_1e7]
2587
 \t t:`csv?1:&quot;sample.csv&quot;
388
</pre></div>

<p>Ten million rows via csv in under 1/2 a second.  Of course results will depend on hardware and number of columns also.
</p>
<span id="r-line"></span></div>
<div class="subsection" id="read-line-_21d2-0_003ax">
<h4 class="subsection">11.1.2 read line &rArr; 0:x</h4>
<p>Read from file x.
</p>
<div class="example">
<pre class="example"> 0:&quot;some.csv&quot;
a,b 
1,3.
2,4.
</pre></div>

<span id="w-line"></span></div>
<div class="subsection" id="write-line-_21d2-x-0_003ay">
<h4 class="subsection">11.1.3 write line &rArr; x 0:y</h4>
<p>Output to string x (file name or null for stdout) the list of strings in y.  y must be a list of strings.  If y is a single string then convert to list via <a href="#enlist">list</a>.
</p>
<div class="example">
<pre class="example"> &quot;&quot;0:(&quot;blue&quot;;&quot;red&quot;)      / &quot;&quot; represents stdout
blue
red

 &quot;file.txt&quot; 0: (&quot;blue&quot;; &quot;red&quot;) / write to file, one line per element
</pre></div>

<span id="r-char"></span></div>
<div class="subsection" id="read-char-_21d2-1_003ax">
<h4 class="subsection">11.1.4 read char &rArr; 1:x</h4>
<p>Read in file x (string).
</p>
<div class="example">
<pre class="example"> / file.bin contains the binary value 0x0010FA37
 1:&quot;file.bin&quot;
0010fa37

 / file.txt contains the ascii string 37\ntest\n
 1:&quot;file.txt&quot;
&quot;37\ntest\n&quot;
</pre></div>

<span id="w-char"></span></div>
<div class="subsection" id="write-char-_21d2-x-1_003ay">
<h4 class="subsection">11.1.5 write char &rArr; x 1:y</h4>
<p>Write to file x (string) data y (list of characters).
</p>
<div class="example">
<pre class="example"> &quot;some.txt&quot;1:&quot;0123ABab&quot;
&quot;some.txt&quot;

 1:&quot;some.txt&quot;
&quot;0123ABab&quot;

 &quot;some.csv&quot; 1:`csv [[]a:1 2;b:3. 4.]
&quot;some.csv&quot;

 1: &quot;some.csv&quot;
&quot;a,b\n1,3.00\n2,4.00\n&quot;

 `csv?1:&quot;some.csv&quot;
a b
- -
1 3
2 4
</pre></div>

<span id="r-data"></span></div>
<div class="subsection" id="read-data-_21d2-2_003a-x">
<h4 class="subsection">11.1.6 read data &rArr; 2: x</h4>
<p>Enterprise Only
</p>
<p>Load file, eg. csv or from a (x 2: y) save.  For the latter, one can find a &ldquo;save then load&rdquo; example in the next section.
</p>
<div class="example">
<pre class="example"> 2:`t.csv
s    t        e p  z   
---- -------- - -- ----
AABL 09:30:00 D 11 4379
AABL 09:30:00 B 40 3950

&nbsp;2:`r                / read from file
a          b          c          d          e         
---------- ---------- ---------- ---------- ----------
0.5366064  0.8250996  0.8978589  0.4895149  0.6811532 
0.1653467  0.05017282 0.4831432  0.4657975  0.4434603 
0.08842649 0.8885677  0.23108    0.3336785  0.6270692 
..

</pre></div>

<span id="w-data"></span></div>
<div class="subsection" id="write-data-_21d2-x-2_003a-y">
<h4 class="subsection">11.1.7 write data &rArr; x 2: y</h4>
<p>Enterprise only
</p>
<p>Save to file x non-atomic data y (e.g., lists, dictionaries, or tables). 
</p>
<p>This example saves 100 million 8-byte doubles to file.  The session is then closed and a fresh session reads in the file.  Both the write (420 ms) and compute statistics from the file  have impressive speeds (146 ms) given the file size (800 MB).
</p>
<div class="example">
<pre class="example"> n:_1e8
 r:+`a`b`c`d`e!5^n?1.;r
 `r 2:r              / write to file 
</pre></div>

<p>Start new session.
</p>
<div class="example">
<pre class="example"> \t r:2:`r;select avg a,sum b, max c, min d, sum e from r
148
</pre></div>

</div>
</div>
<div class="section" id="IPC">
<h3 class="section">11.2 IPC</h3>
<p>k9 has the ability to comunicate between separate k9 instances via interprocess communication (IPC).  These processes can be on the same or separate machines.  A user will start multiple instances specifying the port (via the command line argurment -p) that the k9 session will use, opening a handle to that port, and then running remote commands via the handle and <code>3:</code> or <code>4:</code>.  The commands to be run are sent as a string, eg. &ldquo;3+12&rdquo;.
</p>
<span id="k_002dipc"></span><ul class="section-toc">
<li><a href="#k_002dipc-_21d2-3_003ax" accesskey="1">k-ipc &rArr; 3:x</a></li>
<li><a href="#set-_21d2-x-3_003ay" accesskey="2">set &rArr; x 3:y</a></li>
<li><a href="#https-_21d2-4_003ax" accesskey="3">https &rArr; 4:x</a></li>
<li><a href="#get-_21d2-x-4_003ay" accesskey="4">get &rArr; x 4:y</a></li>
</ul>
<div class="subsection" id="k_002dipc-_21d2-3_003ax">
<h4 class="subsection">11.2.1 k-ipc &rArr; 3:x</h4>
<p>Open a connection to port <code>x</code> and return a handle.  If the port has been forwarded from another machine (eg. ssh -L 1280:server.com:1280 laptop.com) then this handle allows remote execution.
</p>
<div class="example">
<pre class="example"> / before running this session start another k session in another
 / terminal window specifying that port 1251 should be used
 / k -p 1251
 h:3:1251 / create handle to port 1251 and save to h
 h        / h is an integer
4
</pre></div>

<span id="g_t3set"></span></div>
<div class="subsection" id="set-_21d2-x-3_003ay">
<h4 class="subsection">11.2.2 set &rArr; x 3:y</h4>
<p>Exectute string y using handle x.  Handle x should have already been created using k-ipc.  <code>set</code> is asynchronous, thus once the command is sent the session immediately returns to the user.  One will not be able to return any results via <code>set</code>.  If a result is required then one should use <a href="#g_t4get">get</a>.
</p>
<div class="example">
<pre class="example"> h:3:1251               / create handle to port 1251
 h 3:&quot;a:12&quot;             / set a to 12 on remote session
 h 3:&quot;n:_1e8;b:1?n?1.&quot;  / set b to a random number on remote
</pre></div>

<span id="https"></span></div>
<div class="subsection" id="https-_21d2-4_003ax">
<h4 class="subsection">11.2.3 https &rArr; 4:x</h4>
<p>TBD
</p>
<span id="g_t4get"></span></div>
<div class="subsection" id="get-_21d2-x-4_003ay">
<h4 class="subsection">11.2.4 get &rArr; x 4:y</h4>
<p>Execute string y using handle x.  Handle x should have already been created using k-ipc.  <code>get</code> is synchronous, thus once the command is sent the session waits until there result is ready.
</p>
<div class="example">
<pre class="example"> h:3:1251               / create handle to port 1251
 h 3:&quot;a:12&quot;             / set a to 12 on remote session
 h 3:&quot;n:_1e8;b:1?n?1.&quot;  / set b to a random number on remote
 h 4:&quot;a&quot;
12

 h 4:&quot;b&quot;
,0.07820029

 a:&quot;local&quot;              / set a locally to a string value
 a
&quot;local&quot;

4:&quot;a&quot;
12
</pre></div>

</div>
</div>
<div class="section" id="ffi_002fimport">
<h3 class="section">11.3 ffi/import</h3>
<p>These topics will be covered in the <a href="#FF">Foreign Functions</a> chapter.
</p>
<span id="csv"></span><ul class="section-toc">
<li><a href="#export_002c-import-csv-_21d2-_0060csv_0040x_002c-_0060csv_003fx" accesskey="1">export, import csv &rArr; &lsquo;csv@x, <em class='math'>`</em>csv?x</a></li>
<li><a href="#export_002c-import-json-_21d2-_0060json_0040x_002c-_0060json_003fx" accesskey="2">export, import json &rArr; &lsquo;json@x, <em class='math'>`</em>json?x</a></li>
<li><a href="#lz4-zstd-_21d2-_0060lz4-_0060zstd" accesskey="3">lz4 zstd &rArr; <em class='math'>`</em>lz4 <em class='math'>`</em>zstd</a></li>
</ul>
<div class="subsection" id="export_002c-import-csv-_21d2-_0060csv_0040x_002c-_0060csv_003fx">
<h4 class="subsection">11.3.1 export, import csv &rArr; &lsquo;csv@x, <em class='math'>`</em>csv?x</h4>
<p>Enterprise only
</p>
<p>csv tools allows one to export tables into csv and import from csv.  Generally these functions are used with file i/o <code>1:</code>
</p>
<div class="example">
<pre class="example"> &quot;test.csv&quot;1:`csv@[[]x:`a`b;y:3 2]  / write sample table to file
&quot;test.csv&quot;

 `csv?1:&quot;test.csv&quot;                  / read csv from file
x y
- -
a 3
b 2
</pre></div>

<span id="json"></span></div>
<div class="subsection" id="export_002c-import-json-_21d2-_0060json_0040x_002c-_0060json_003fx">
<h4 class="subsection">11.3.2 export, import json &rArr; &lsquo;json@x, <em class='math'>`</em>json?x</h4>
<p>Export object x to json format or import string x from json format.  The json shared library will be automatically pulled from the Shakti website into the current directory.  Use of symbolic links with path on the binary may cause issues.
</p>
<div class="example">
<pre class="example"> &quot;test.json&quot;1:`json@[[]x:`a`b;y:3 2]
&quot;test.json&quot;

`json?1:&quot;test.json&quot;
(,&quot;x&quot;;,&quot;y&quot;)!(,&quot;a&quot;;3)
(,&quot;x&quot;;,&quot;y&quot;)!(,&quot;b&quot;;2)
</pre></div>

<span id="compress"></span></div>
<div class="subsection" id="lz4-zstd-_21d2-_0060lz4-_0060zstd">
<h4 class="subsection">11.3.3 lz4 zstd &rArr; <em class='math'>`</em>lz4 <em class='math'>`</em>zstd</h4>
<p>lz4 and zstd are compression algorythms which can be used to reduce the size of files.  As with other foreign libraries k9 does the work behind the scenes.  Here is an example of writing a large csv file to disk and reading it back in.  In the second (lz4) and third (zstd) examples the csv&rsquo;s are compressed and decompressed with lz4 and zstd respectively.  One can look at the file sizes to see how well the compression worked.
</p>
<div class="example">
<pre class="example"> g:{+`s`f`i!(x?&quot;abc&quot;;x?10.;x?10)}

&quot;t.csv&quot;1:`csv@g[_1e7]
&quot;t.csv&quot;

\t tc:`csv?1:&quot;t.csv&quot;            / read from csv
314

&quot;t.lz4&quot;1:`lz4@`csv@g[_1e7]      / write to lz4
&quot;t.lz4&quot;

\t tz:`csv?`lz4?1:&quot;t.lz4&quot;       / read from lz4 compressed csv
525

 &quot;t.zstd&quot;1:`zstd@`csv@g[_1e7]   / write to zstd
&quot;t.zstd&quot;

 \t tz:`csv?`zstd?1:&quot;t.zstd&quot;    / read from zstd compressed csv
535
</pre></div>

<hr>
</div>
</div>
</div>
<div class="chapter" id="FF">
<div class="header">
<p>
Next: <a href="#Tables" accesskey="n" rel="next">Tables</a>, Previous: <a href="#I_002fO" accesskey="p" rel="prev">I/O and Interface</a>, Up: <a href="#Top" accesskey="u" rel="up">k9: Manual</a> &nbsp; </p>
</div>
<span id="Foreign-Functions"></span><h2 class="chapter">12 Foreign Functions</h2>

<div class="example">
<pre class="example"><a href="#python">python</a>:from k import k;k('+',2,3);<a href="#nodejs">nodejs</a>:k=require('k').k;k('+',2,3)
*5: <a href="#ffi">ffi</a>/<a href="#import">import</a>
</pre></div>

<p>Enterprise only
</p>
<p>k9 is able to interface with other programing laguages (python and nodejs) via shared libraries and the foreign function interface (ffi).
</p>
<span id="python"></span><ul class="section-toc">
<li><a href="#python-1" accesskey="1">python</a></li>
<li><a href="#nodejs-1" accesskey="2">nodejs</a></li>
<li><a href="#ffi-_21d2-5_003a" accesskey="3">ffi &rArr; 5:</a></li>
<li><a href="#import-_21d2-x-5_003ay" accesskey="4">import &rArr; x 5:y</a></li>
</ul>
<div class="section" id="python-1">
<h3 class="section">12.1 python</h3>
<p>In order to have python call k, one has to download the shared object file (k.so for linux and m.so for mac) and save it in the appropriate directory.
</p>
<div class="example">
<pre class="example">user1@hw1:~$ python3 -m site --user-site
/Users/user1/Library/Python/3.8/lib/python/site-packages
</pre></div>

<p>Once the file is stored (and it must be called k.so even on the mac) then one can start a python session and call k.
</p>
<div class="example">
<pre class="example">user1@hw1:~$ python3
Python 3.8.5 (v3.8.5:580fbb018f, Jul 20 2020, 12:11:27) 
[Clang 6.0 (clang-600.0.57)] on darwin
Type &quot;help&quot;, &quot;copyright&quot;, &quot;credits&quot; or &quot;license&quot; for more information.
&gt;&gt;&gt; import k
&gt;&gt;&gt; k.k('x:5?10.')
&gt;&gt;&gt; k.k('x')
[7.691266643814743, 6.843659253790975, 6.399056380614638, 9.637191963847727, 4.250652831979096]
&gt;&gt;&gt; len(k.k('x'))
5
&gt;&gt;&gt; 
</pre></div>

<span id="nodejs"></span></div>
<div class="section" id="nodejs-1">
<h3 class="section">12.2 nodejs</h3>
<p>One can call k9 from nodejs using the k.node shared libary.  (If using a mac then download m.node and rename it k.node.)
</p>
<p>From the terminal...
</p>
<pre class="verbatim">% node
Welcome to Node.js v14.17.4.
Type &quot;.help&quot; for more information.
&gt; k=require('./k')
{}
&gt; k.k('+/!20')
190
&gt; 
</pre>
<p>There&rsquo;s also the ability to send information from k9 to nodejs via <a href="#k_002dipc">IPC</a>.
</p>
<p>ipc.js file
</p><pre class="verbatim">p=1299;s=new require('net').Server();
s.listen(p, function()            {console.log(`Port ${p} is open.`);})
s.on('connection',function(socket){console.log(`Port ${p} is connected.`);
 socket.on('data',     function(chunk) {console.log(`Data: ${chunk.toString()}` );});
 socket.on('end',      function()      {console.log(`Port ${p} is disconnected.`);});
});
</pre>
<p>Start nodejs
</p><pre class="verbatim">% node ipc.js
</pre>
<p>In k9...
</p><div class="example">
<pre class="example"> h:3:1299
 h 3: &quot;\nLine1\nLine2\n&quot;
</pre></div>

<p>In nodejs...
</p><pre class="verbatim">Port 1299 is open.
Port 1299 is connected.
Data: 
Line1
Line2
</pre>
<span id="ffi"></span></div>
<div class="section" id="ffi-_21d2-5_003a">
<h3 class="section">12.3 ffi &rArr; 5:</h3>

<p>Load shared library.
</p>
<p>Contents of file &rsquo;a.c&rsquo;
</p><div class="example">
<pre class="example">int add1(int x){return 1+x;}
int add2(int x){return 2+x;}
int indx(int x[],int y){return x[y];}
</pre></div>

<p>Compile into a shared library (done on macos here)
</p><div class="example">
<pre class="example">% clang -dynamiclib -o a.so a.c
</pre></div>

<p>Load the shared library into the session.
</p><div class="example">
<pre class="example">&nbsp;f:&quot;./dev/a.so&quot;5:{add1:&quot;i&quot;;add2:&quot;i&quot;;indx:&quot;Ii&quot;}
&nbsp;f[`add1] 12
13
&nbsp;f[`indx][12 13 14;2]
14
</pre></div>

<span id="import"></span></div>
<div class="section" id="import-_21d2-x-5_003ay">
<h3 class="section">12.4 import &rArr; x 5:y</h3>
<p>Import as name x library y.
</p>
<div class="example">
<pre class="example"> .(:;`json;5:`json) / using dot notation
</pre></div>

<hr>
</div>
</div>
<div class="chapter" id="Tables">
<div class="header">
<p>
Next: <a href="#kSQL" accesskey="n" rel="next">kSQL</a>, Previous: <a href="#FF" accesskey="p" rel="prev">Foreign Functions</a>, Up: <a href="#Top" accesskey="u" rel="up">k9: Manual</a> &nbsp; </p>
</div>
<span id="Tables-1"></span><h2 class="chapter">13 Tables</h2>
<p>k9 has the ability to store data in a tabular format containing named columns and rows of information as tables.  If the data to be stored and queried is large, then you should use tables.  This chapter introduces the different types of data tables available in k9.  Table and utable are very similar and as you&rsquo;ll see in the <a href="#kSQL">kSQL</a> chapter are easy to query.  In the <a href="#Benchmark">Benchmark</a> chapter, you&rsquo;ll see that tables are fast to save, read, and query.
</p>
<div class="example">
<pre class="example"> <a href="#table">table</a> t:[[]n:`b`c;i:2 3]
<a href="#utable">utable</a> u: [[n:`b`c]i:2 3]
</pre></div>

<span id="table"></span><ul class="section-toc">
<li><a href="#table-1" accesskey="1">table</a></li>
<li><a href="#utable-1" accesskey="2">utable</a></li>
</ul>
<div class="section" id="table-1">
<h3 class="section">13.1 table</h3>
<p>The table is the most basic of the three types.  A table consists of columns and rows of information where each column has a name.  Tables can be created in three different ways (1) specification via table format, (2) flipping a dictionary, or (3) reading in from a file.
</p>
<ul class="section-toc">
<li><a href="#Table-format" accesskey="1">Table format</a></li>
<li><a href="#Dictionary-format" accesskey="2">Dictionary format</a></li>
<li><a href="#File-import" accesskey="3">File import</a></li>
</ul>
<div class="subsection" id="Table-format">
<h4 class="subsection">13.1.1 Table format</h4>
<p>Tables can be created with the table square bracket notation.
</p>
<p>As an example, let&rsquo;s create a table with two columns named &ldquo;a&rdquo; and &ldquo;col2&rdquo; having three rows.  The syntax is to surround the definition with square brackets and then have a first element of empty square brackets. Following those brackets comes first column name, colon, and the list of values, then the second column, and continuing for all the columns. For keyed tables, the initial square brackets will contain key column names as we will discuss later.  
</p>
<div class="example">
<pre class="example"> [[] a:1 20 3; col2: 3.6 4.8 0.1]
a  col2
-- ----
 1 3.6 
20 4.8 
 3 0.1

 [[] a:1; col2:3.6]   / will error :class as lists required
[[] a:1; col2:3.6]

:class

 [[] a:,1; col2:,3.6] / using list will succeed
[[]a:,1;col2:,3.6]
</pre></div>

</div>
<div class="subsection" id="Dictionary-format">
<h4 class="subsection">13.1.2 Dictionary format</h4>
<p>Tables can also be created by flipping a dictionary into a table.  
</p>
<div class="example">
<pre class="example"> +`a`col2!(1 20 3;  3.6 4.8 0.1)      / +columnnames!(values)
a  col2
-- ----
 1 3.6 
20 4.8 
 3 0.1 
</pre></div>

</div>
<div class="subsection" id="File-import">
<h4 class="subsection">13.1.3 File import</h4>
<p>Tables can also be created by reading in a file.
</p>
<p>t.csv
</p><pre class="verbatim">a, col2
1, 3.6
20, 4.8
3, 0.1
</pre>
<p>Use load file <code>2:x</code> which returns a table.
</p>
<div class="example">
<pre class="example"> 2:`t.csv
a   col2
-- -----
 1  3.6 
20  4.8 
 3  0.1 
</pre></div>

<span id="utable"></span></div>
</div>
<div class="section" id="utable-1">
<h3 class="section">13.2 utable</h3>
<p>utable (or key table) is a table where some of the columns are keyed. The combination of those columns  should not have two rows with the same values. This must be enforced by the application.
</p>
<div class="example">
<pre class="example"> [[d:2020.09.08 2020.09.09 2020.09.10]p:140 139 150]
d         |p  
----------|---
2020.09.08|140
2020.09.09|139
2020.09.10|150

 `d^ [[]d:2020.09.08 2020.09.09 2020.09.10;p:140 139 150]
d         |p  
----------|---
2020.09.08|140
2020.09.09|139
2020.09.10|150
</pre></div>


<hr>
</div>
</div>
<div class="chapter" id="kSQL">
<div class="header">
<p>
Next: <a href="#System" accesskey="n" rel="next">System</a>, Previous: <a href="#Tables" accesskey="p" rel="prev">Tables</a>, Up: <a href="#Top" accesskey="u" rel="up">k9: Manual</a> &nbsp; </p>
</div>
<span id="kSQL-1"></span><h2 class="chapter">14 kSQL</h2>
<p>kSQL is a powerful query language for tables.  It has similarities to ANSI SQL but additional features to make it easier to work with ordered data, such as time series data.
</p>
<div class="example">
<pre class="example">Database
{<a href="#select">select</a>|<a href="#update">update</a>} <a href="#A">A</a> <a href="#by-B">by B</a> from T <a href="#where-C">where C</a>; <a href="#delete">delete</a> from T <a href="#where-C">where C</a>

<a href="#Joins">Joins</a>
x,y      / <a href="#insert">insert</a>, <a href="#upsert">upsert</a>, <a href="#union">union</a>, equi-and-asof <a href="#leftjoin">leftjoin</a>
x+y      / equi-and-asof outerjoin (e.g. combine markets through time)
x#y      / take/intersect innerjoin
x_y      / drop/difference
</pre></div>

<ul class="section-toc">
<li><a href="#Queries" accesskey="1">Queries</a></li>
<li><a href="#Joins-1" accesskey="2">Joins</a></li>
<li><a href="#Insert-and-Upsert" accesskey="3">Insert and Upsert</a></li>
</ul>
<div class="section" id="Queries">
<h3 class="section">14.1 Queries</h3>
<p>Queries can be done either via the kSQL or functional forms.  The kSQL form is general simplier to write while the functional form allows one to more easily run multithreaded or build queries programmatically.  
</p>
<span id="select"></span><ul class="section-toc">
<li><a href="#select-1" accesskey="1">select</a></li>
<li><a href="#A-1" accesskey="2">A</a></li>
<li><a href="#by-B-1" accesskey="3">by B</a></li>
<li><a href="#where-C-1" accesskey="4">where C</a></li>
<li><a href="#Query-with-By-and-Where" accesskey="5">Query with By and Where</a></li>
<li><a href="#update-1" accesskey="6">update</a></li>
<li><a href="#delete-1" accesskey="7">delete</a></li>
</ul>
<div class="subsection" id="select-1">
<h4 class="subsection">14.1.1 select</h4>
<p>There a number of ways to return a complete table with kSQL.  You can use the table name, a kSQL query without columns, or a fully specified query with columns.
</p>
<div class="example">
<pre class="example"> n:5;t:[[]x:!n;y:sin !n]
 t
x y         
- ----------
0 0.        
1 0.841471  
2 0.9092974 
3 0.14112   
4 -0.7568025

 select x,y from t
x y         
- ----------
0 0.        
1 0.841471  
2 0.9092974 
3 0.14112   
4 -0.7568025

 `x`y#t
x y         
- ----------
1 0.841471  
2 0.9092974 
3 0.14112   
4 -0.7568025
</pre></div>

<span id="A"></span></div>
<div class="subsection" id="A-1">
<h4 class="subsection">14.1.2 A</h4>
<p>A is the list of fields to return from the select or update query.  A can create new column names.  
</p>
<div class="example">
<pre class="example"> n:5;t:[[]x:!n;y:sin !n];t
x y         
- ----------
0 0.        
1 0.841471  
2 0.9092974 
3 0.14112   
4 -0.7568025

 select x from t
x
-
0
1
2
3
4

`x#t
x
-
0
1
2
3
4


 select y,x from t    / reorder columns
y          x
---------- -
0.         0
0.841471   1
0.9092974  2
0.14112    3
-0.7568025 4

 `y`x#t
y          x
---------- -
0          0
0.841471   1
0.9092974  2
0.14112    3
-0.7568025 4

 select x,z:y from t  / create new column z
x z         
- ----------
0 0.        
1 0.841471  
2 0.9092974 
3 0.14112   
4 -0.7568025
</pre></div>

<span id="by-B"></span></div>
<div class="subsection" id="by-B-1">
<h4 class="subsection">14.1.3 by B</h4>
<p>kSQL also has a way to group rows using <code>by B</code>.  The result is a utable where the key is determined by the grouping clause.
</p>
<div class="example">
<pre class="example"> n:5;t:[[]x:!n;y:sin !n]
 select sum y by x&gt;2 from t
x|y         
-|----------
0|1.750768  
1|-0.6156825

 t :+/'y@=x&gt;2
0|1.750768  
1|-0.6156825
</pre></div>

<span id="where-C"></span></div>
<div class="subsection" id="where-C-1">
<h4 class="subsection">14.1.4 where C</h4>
<p>kSQL makes it easy to build up a where clause to filter down the table.  C is the list of constraints.
</p>
<div class="example">
<pre class="example"> n:5;t:[[]x:!n;y:sin !n]
 select from t where x&gt;0
x y         
- ----------
1 0.841471  
2 0.9092974 
3 0.14112   
4 -0.7568025

 (:x&gt;0)#t
x y         
- ----------
1 0.841471  
2 0.9092974 
3 0.14112   
4 -0.7568025

select from t where (x&gt;0), y within 0 .9
x y       
- --------
1 0.841471
3 0.14112

 (:x&gt;0;:y within .0 .9)#t
x y       
- --------
1 0.841471
3 0.14112 
</pre></div>

</div>
<div class="subsection" id="Query-with-By-and-Where">
<h4 class="subsection">14.1.5 Query with By and Where</h4>

<div class="example">
<pre class="example"> n:5;t:[[]x:!n;y:sin !n]
 select sum y by x&gt;2 from t where y&gt;0
x|y       
-|--------
0|1.750768
1|0.14112

 ((:y&gt;0)#t) :+/'y@=x&gt;2
0|1.750768
1|0.14112 
</pre></div>

<span id="update"></span></div>
<div class="subsection" id="update-1">
<h4 class="subsection">14.1.6 update</h4>
<p>update allows one to modify values without specifying all the fields that pass through.  update is also used to add new columns in a table.  update does not, by itself, save the modifications to the table. If you want to preserve those modifications, use assignment.
</p>
<div class="example">
<pre class="example"> t:[[]x:`a`b`c;y:1 2 3];t
x y
- -
a 1
b 2
c 3

 update y+18 from t
x y 
- --
a 19
b 20
c 21

 update z:y+18 from t
x y z 
- - --
a 1 19
b 2 20
c 3 21

 t:update z:y+18 from t; / save the updates into table t
 t                       / Now t has the updated values.
x y z 
- - --
a 1 19
b 2 20
c 3 21
</pre></div>

<span id="delete"></span></div>
<div class="subsection" id="delete-1">
<h4 class="subsection">14.1.7 delete</h4>
<p>Delete rows from a table that satisfy one or more conditions.  Currently not working.
</p>
<div class="example">
<pre class="example"> t:[[]x:`a`b`c;y:1 2 1];t
x y
- -
a 1
b 2
c 1

 delete from t where y&gt;1
!value

 delete from t where x=`c,y=1
!nyi
</pre></div>

<span id="Joins"></span></div>
</div>
<div class="section" id="Joins-1">
<h3 class="section">14.2 Joins</h3>
<p>k9 has a number of methods to join tables together which are described below.  In this section t, t1 and t2 represent tables and k, k1 and k2 represent utables.
</p>
<table>
<tr><td><b>join</b></td><td><b>syntax</b></td></tr>
<tr><td><a href="#union">union</a></td><td>t1,t2</td></tr>
<tr><td><a href="#leftjoin">leftjoin</a></td><td>t,k</td></tr>
<tr><td><a href="#outer">outer</a></td><td>k1,k2</td></tr>
<tr><td><a href="#asof">asof</a></td><td>t,k</td></tr>
<tr><td><a href="#asof_002b">asof+</a></td><td>k1+k2</td></tr>
</table>

<span id="union"></span><ul class="section-toc">
<li><a href="#union-join-_21d2-t1_002ct2" accesskey="1">union join &rArr; t1,t2</a></li>
<li><a href="#leftjoin-_21d2-t_002ck" accesskey="2">leftjoin &rArr; t,k</a></li>
<li><a href="#outer-join-_21d2-k1_002ck2" accesskey="3">outer join &rArr; k1,k2</a></li>
<li><a href="#asof-join-_21d2-t_002ck" accesskey="4">asof join &rArr; t,k</a></li>
<li><a href="#asof_002b-join-_21d2-k1_002bk2" accesskey="5">asof+ join &rArr; k1+k2</a></li>
</ul>
<div class="subsection" id="union-join-_21d2-t1_002ct2">
<h4 class="subsection">14.2.1 union join &rArr; t1,t2</h4>
<p>Union join table t1 with table t2.  The tables should have the same columns and the join results in a table with t2 appended to t1.  If the tables do not have the same columns then return t1.
</p>
<div class="example">
<pre class="example">&nbsp;t1:[[]s:`a`b;p:1 2;q:3 4]
&nbsp;t2:[[]s:`b`c;p:11 12;q:21 22]
&nbsp;t1
s p q
- - -
a 1 3
b 2 4

&nbsp;t2
s p  q 
- -- --
b 11 21
c 12 22

&nbsp;t1,t2
s p  q 
- -- --
a  1  3
b  2  4
b 11 21
c 12 22
</pre></div>

<span id="leftjoin"></span></div>
<div class="subsection" id="leftjoin-_21d2-t_002ck">
<h4 class="subsection">14.2.2 leftjoin &rArr; t,k</h4>
<p>leftjoin table t with utable k.  Result includes all rows from t and the values from table k having the same key values.
If a row of t has key values not found in k, then the t values are shown and 0 for the columns coming from k.
</p>
<div class="example">
<pre class="example"> t:[[]s:`a`b`c;p:1 2 3;q:7 8 9]
 k:[[s:`a`b`x`y`z]q:101 102 103 104 105;r:51 52 53 54 55]
 t
s p q
- - -
a 1 7
b 2 8
c 3 9

 k
s|q   r 
-|--- --
a|101 51
b|102 52
x|103 53
y|104 54
z|105 55

 / t.s includes the value `c. Because k.s does not include c,
 / the last row shows a 0 under the r column (which comes from k).
 t,k       
s p q   r 
- - --- --
a 1 101 51
b 2 102 52
c 3   9  0
</pre></div>

<span id="outer"></span></div>
<div class="subsection" id="outer-join-_21d2-k1_002ck2">
<h4 class="subsection">14.2.3 outer join &rArr; k1,k2</h4>
<p>Outer join utable k1 and k2. 
</p>
<div class="example">
<pre class="example"> k1:[[s:`a`b]p:1 2;q:3 4]
 k2:[[s:`b`c]p:9 8;q:7 6]
 k1
s|p q
-|- -
a|1 3
b|2 4

 k2
s|p q
-|- -
b|9 7
c|8 6

 k1,k2
s|p q
-|- -
a|1 3
b|9 7
c|8 6

 k1:[[s:`a`b]p:1 1;q:10 10]
 k2:[[s:`b`c]p:2 2;q:20 20]
 k3:[[s:`c`d]p:3 3;q:30 30]

k1,k2,k3       / joining a 3rd
s|p q 
-|- --
a|1 10
b|2 20
c|3 30
d|3 30

 ,/(k1;k2;k3)  / join over
s|p q 
-|- --
a|1 10
b|2 20
c|3 30
d|3 30
</pre></div>

<span id="asof"></span></div>
<div class="subsection" id="asof-join-_21d2-t_002ck">
<h4 class="subsection">14.2.4 asof join &rArr; t,k</h4>
<p>Asof joins each row rt of table t to a row rk in utable k (keyed by time) provided rk has the maximum time value of any row in k while obeying the constraint that the time value in rt &gt;= the time value of rk. Intuitively, rk should be the row in k that is most up-to-date with respect to rt. 
</p>
<div class="example">
<pre class="example"> t:[[]t:09:30+5*!5;p:100+!5];t
t     p  
----- ---
09:30 100
09:35 101
09:40 102
09:45 103
09:50 104

 k:[[t:09:32 09:41 09:45]q:50 51 52];k
t    |q 
-----|--
09:32|50
09:41|51
09:45|52

 / Notice below the t row at 09:45 is linked with the k row at 09:45.
 / The k row at 09:41 is not linked with any t row.
 / By contrast, both the 09:35 and the 09:40 rows of t
 / are linked to the 09:32 row of k.
 t,k      
          
t     p   q 
----- --- --
09:30 100  0
09:35 101 50
09:40 102 50
09:45 103 52
09:50 104 52
</pre></div>

<p>Scaling this up to a bigger set of tables one can see the performance of k9 on joins.
</p>
<div class="example">
<pre class="example"> N:_1e8;T:[[]t:N?`t 0;q:N?100];5#T
t            q 
------------ --
00:00:00.001 44
00:00:00.002 46
00:00:00.002 48
00:00:00.003 35
00:00:00.003 43

 n:_1e5;K:[[t:n?`t 0]p:n?100];5#K
t           |p 
------------|--
00:00:00.481|54
00:00:00.961|63
00:00:01.094|67
00:00:01.479|16
00:00:01.917|58

 \t T,K
222
</pre></div>

<span id="asof_002b"></span></div>
<div class="subsection" id="asof_002b-join-_21d2-k1_002bk2">
<h4 class="subsection">14.2.5 asof+ join &rArr; k1+k2</h4>
<p>Asof+ joins  allows one to aggregate over markets to find the total available at a given time.  The utables need to be specified with <code>`a</code>. The effect is to merge the two key fields (the field t in this case) and for each row rk1 from table k1, add the non-key field (bs in this case) from rk1 to the bs field of the most recent row in k2 whose t value is less than or equal to the t value in rk1. And symmetrically for each row of table k2.
</p>
<div class="example">
<pre class="example"> k1:`a [[t:09:30+5*!5]bs:100*1 2 3 2 1];k1
t    |bs 
-----|---
09:30|100
09:35|200
09:40|300
09:45|200
09:50|100

 k2:`a [[t:09:32 09:41 09:45]bs:1 2 3];k2
t    |bs
-----|--
09:32| 1
09:41| 2
09:45| 3

 k1+k2
t    |bs 
-----|---
09:30|100
09:32|101
09:35|201
09:40|301
09:41|302
09:45|203
09:50|103
</pre></div>

</div>
</div>
<div class="section" id="Insert-and-Upsert">
<h3 class="section">14.3 Insert and Upsert</h3>
<p>One can add data to tables via insert or upsert.  The difference between the two is that insert adds data to a table while upsert on some key x will replace the values if x is present in the target table or insert x with its associated value otherwise. 
</p>
<span id="insert"></span><ul class="section-toc">
<li><a href="#insert-_21d2-t_002cd" accesskey="1">insert &rArr; t,d</a></li>
<li><a href="#upsert-_21d2-k_002cd" accesskey="2">upsert &rArr; k,d</a></li>
</ul>
<div class="subsection" id="insert-_21d2-t_002cd">
<h4 class="subsection">14.3.1 insert &rArr; t,d</h4>
<p>Insert dictionary d into table t.
</p><div class="example">
<pre class="example"> t:[[]c1:`a`b`a;c2:1 2 7];t
c1 c2
-- --
a   1
b   2
a   7

 t,`c1`c2!(`a;12)
c1 c2
-- --
a   1
b   2
a   7
a  12

 t,`c1`c2!(`c;12)
c1 c2
-- --
a   1
b   2
a   7
c  12
</pre></div>

<span id="upsert"></span></div>
<div class="subsection" id="upsert-_21d2-k_002cd">
<h4 class="subsection">14.3.2 upsert &rArr; k,d</h4>
<p>Insert dictionary d into utable k.
</p><div class="example">
<pre class="example"> k:[[c1:`a`b`c]c2:1 2 7];k
c1|c2
--|--
a | 1
b | 2
c | 7

 k,`c1`c2!(`a;12)
c1|c2
--|--
a |12
b | 2
c | 7

 k,`c1`c2!(`b;12)
c1|c2
--|--
a | 1
b |12
c | 7

 k,`c1`c2!(`d;12)
c1|c2
--|--
a | 1
b | 2
c | 7
d |12
</pre></div>

<hr>
</div>
</div>
</div>
<div class="chapter" id="System">
<div class="header">
<p>
Next: <a href="#Control-Flow" accesskey="n" rel="next">Control Flow</a>, Previous: <a href="#kSQL" accesskey="p" rel="prev">kSQL</a>, Up: <a href="#Top" accesskey="u" rel="up">k9: Manual</a> &nbsp; </p>
</div>
<span id="System-1"></span><h2 class="chapter">15 System</h2>
<p>k9 comes with a few system functions and measurement commands.  The commands allow you to load a script, change the working directory, measure execution times and memory usage, and list defined variables.
</p>
<div class="example">
<pre class="example">System
\l a.k  <a href="#load">load</a>
\t:n x  <a href="#timing">timing</a>
\u:n x
\v      <a href="#variables">variables</a>
\w      <a href="#memory">memory</a>

\cmd    <a href="#OS-command">OS command</a>
</pre></div>

<span id="load"></span><ul class="section-toc">
<li><a href="#load-_21d2-_005cl-a_002ek" accesskey="1">load &rArr; \l a.k</a></li>
<li><a href="#timing-_21d2-_005ct-x-or-_005ct_003an-x" accesskey="2">timing &rArr; \t x or \t:n x</a></li>
<li><a href="#u-_21d2-_005cu-x-or-_005cu_003an-x" accesskey="3">u &rArr; \u x or \u:n x</a></li>
<li><a href="#variables-_21d2-_005cv" accesskey="4">variables &rArr; \v</a></li>
<li><a href="#memory-_21d2-_005cw" accesskey="5">memory &rArr; \w</a></li>
<li><a href="#OS-command-_21d2-_005ccmd" accesskey="6">OS command &rArr; \cmd</a></li>
</ul>
<div class="section" id="load-_21d2-_005cl-a_002ek">
<h3 class="section">15.1 load &rArr; \l a.k</h3>
<p>Load a text file of k9 commands.  The file name must end in .k.
</p>
<div class="example">
<pre class="example"> \l func.k
\l func.k

\l func.k9  / will error as not .k
:nyi
</pre></div>

<span id="timing"></span></div>
<div class="section" id="timing-_21d2-_005ct-x-or-_005ct_003an-x">
<h3 class="section">15.2 timing &rArr; \t x or \t:n x</h3>
<p>List time elapsed in milliseconds in evaluting x.  If n is supplied then repeat x, n times.
</p>
<div class="example">
<pre class="example"> \t ^(_10e6)? _1e8     / sort 10 million numbers
227

 \t:10 ^(_10e6)? _1e8  / perform 10 times the sort
2027
</pre></div>

</div>
<div class="section" id="u-_21d2-_005cu-x-or-_005cu_003an-x">
<h3 class="section">15.3 u &rArr; \u x or \u:n x</h3>
<p>TBD
</p>
<span id="variables"></span></div>
<div class="section" id="variables-_21d2-_005cv">
<h3 class="section">15.4 variables &rArr; \v</h3>
<p>List variables
</p><div class="example">
<pre class="example">a:1;b:2;c:3

 \v
,3
i|`a`b`c
</pre></div>

<span id="memory"></span></div>
<div class="section" id="memory-_21d2-_005cw">
<h3 class="section">15.5 memory &rArr; \w</h3>
<p>List memory usage
</p><div class="example">
<pre class="example"> \w
930

 r:(_10e6)?10

 \w
2098106
</pre></div>

<span id="OS-command"></span></div>
<div class="section" id="OS-command-_21d2-_005ccmd">
<h3 class="section">15.6 OS command &rArr; \cmd</h3>
<p>Run any valid command via OS.
</p>
<div class="example">
<pre class="example"> \cd &quot;/Users/user123/&quot;

 \pwd
,&quot;/Users/user123&quot;

 \echo $PATH             / query environmental variable
,&quot;/opt/local/bin:/usr/bin:/bin&quot;
</pre></div>

<hr>
</div>
</div>
<div class="chapter" id="Control-Flow">
<div class="header">
<p>
Next: <a href="#Temporal-Functions" accesskey="n" rel="next">Temporal Functions</a>, Previous: <a href="#System" accesskey="p" rel="prev">System</a>, Up: <a href="#Top" accesskey="u" rel="up">k9: Manual</a> &nbsp; </p>
</div>
<span id="Control-Flow-1"></span><h2 class="chapter">16 Control Flow</h2>
<p>Though looping statements are not necessary in k9, if-then-else statements are sometimes useful.
</p>
<pre class="verbatim">$[b;t;f] cond
</pre>
<span id="cond"></span><ul class="section-toc">
<li><a href="#cond-_21d2-_0024_005bb_003bt_003bf_005d" accesskey="1">cond &rArr; $[b;t;f]</a></li>
</ul>
<div class="section" id="cond-_21d2-_0024_005bb_003bt_003bf_005d">
<h3 class="section">16.1 cond &rArr; $[b;t;f]</h3>
<p>If b is non zero then x else y.  x and y are not required to be of the same type.
</p>
<div class="example">
<pre class="example"> $[3&gt;2;`a;`b]
`a

 $[2&gt;3;`a;`b]
`b

 $[37;12;10]
12

 $[1b;`a`b!(1 2;3 4);`n]
a|1 2
b|3 4

 $[1b;a:3;b:2]
3
 a
3
 b   / is not set as the f case not evaluated
!value
</pre></div>

<hr>
</div>
</div>
<div class="chapter" id="Temporal-Functions">
<div class="header">
<p>
Next: <a href="#Errors" accesskey="n" rel="next">Errors</a>, Previous: <a href="#Control-Flow" accesskey="p" rel="prev">Control Flow</a>, Up: <a href="#Top" accesskey="u" rel="up">k9: Manual</a> &nbsp; </p>
</div>
<span id="Temporal-Functions-1"></span><h2 class="chapter">17 Temporal Functions</h2>
<p>k9 has functions (within <code>.z</code>) to get the current date and time to various degrees of precision.  There are also functions to retrieve partial date and time using dot notation.
</p>
<pre class="verbatim">z.d date   2001.02.03  
z.t time   12:34:56.789
z.T datetime
</pre>
<span id="z_002ed"></span><ul class="section-toc">
<li><a href="#z_002ed-date" accesskey="1">z.d date</a></li>
<li><a href="#z_002et-time" accesskey="2">z.t time</a></li>
<li><a href="#z_002eT-datetime" accesskey="3">z.T datetime</a></li>
<li><a href="#Temporal-dot-functions" accesskey="4">Temporal dot functions</a></li>
</ul>
<div class="section" id="z_002ed-date">
<h3 class="section">17.1 z.d date</h3>
<p>These functions retrieve the date as day (d) or month (m) precision.
</p>
<div class="example">
<pre class="example"> .z.d
2023.03.11
</pre></div>

<span id="z_002et"></span></div>
<div class="section" id="z_002et-time">
<h3 class="section">17.2 z.t time</h3>
<p>These functions retrieve the time millisecond precision.
</p>
<div class="example">
<pre class="example"> z.t
09:09:02.451
</pre></div>

<p>One could use the current time commands to measure run time but typically this is done via <code>\t</code>
</p>
<div class="example">
<pre class="example"> t1:z.t;(_2e8)?1.;t2:z.t;t2-t1
00:00:00.001

 \t (_2e8)?1.
610
</pre></div>

<span id="z_002eT"></span></div>
<div class="section" id="z_002eT-datetime">
<h3 class="section">17.3 z.T datetime</h3>
<p>These functions retrieve the date and time as datetime.
</p>
<div class="example">
<pre class="example"> .z.T
2023.03.11 09:09:49.654
</pre></div>

</div>
<div class="section" id="Temporal-dot-functions">
<h3 class="section">17.4 Temporal dot functions</h3>
<p>These functions use dot notation to retrieve partial date and times.
</p>
<div class="example">
<pre class="example"> now:.z.v;now
11:27:18.049558016
 now.h
11
 now.r
11:27
 now.s
11:27:18
 now.t
11:27:18.049
 now.u
11:27:18.049558
 now.v
11:27:18.049558016
</pre></div>

<hr>
</div>
</div>
<div class="chapter" id="Errors">
<div class="header">
<p>
Next: <a href="#Examples" accesskey="n" rel="next">Examples</a>, Previous: <a href="#Temporal-Functions" accesskey="p" rel="prev">Temporal Functions</a>, Up: <a href="#Top" accesskey="u" rel="up">k9: Manual</a> &nbsp; </p>
</div>
<span id="Errors-1"></span><h2 class="chapter">18 Errors</h2>
<p>Given the terse syntax of k9, it likely won&rsquo;t be a surprise  that  error messages are also rather short.  The errors are listed on the help page and described in more detail below.
</p>
<div class="example">
<pre class="example">error: <a href="#class">class</a> <a href="#rank">rank</a> <a href="#length">length</a>
<a href="#g_t_005ftype">type</a> <a href="#domain">domain</a> <a href="#limit">limit</a>
stack <a href="#eparse">parse</a> <a href="#g_t_005fvalue">value</a>
</pre></div>

<span id="class"></span><ul class="section-toc">
<li><a href="#g_t_003aclass" accesskey="1">:class</a></li>
<li><a href="#g_t_003arank" accesskey="2">:rank</a></li>
<li><a href="#g_t_003alength" accesskey="3">:length</a></li>
<li><a href="#g_t_003atype" accesskey="4">:type</a></li>
<li><a href="#g_t_003adomain" accesskey="5">:domain</a></li>
<li><a href="#g_t_003alimit" accesskey="6">:limit</a></li>
<li><a href="#g_t_003anyi" accesskey="7">:nyi</a></li>
<li><a href="#g_t_003aparse" accesskey="8">:parse</a></li>
<li><a href="#g_t_003avalue" accesskey="9">:value</a></li>
</ul>
<div class="section" id="g_t_003aclass">
<h3 class="section">18.1 :class</h3>
<p>Calling a function on mismatched types.
</p><div class="example">
<pre class="example">&nbsp;3+`b
:class
</pre></div>

<span id="rank"></span></div>
<div class="section" id="g_t_003arank">
<h3 class="section">18.2 :rank</h3>
<p>Calling a function with too many parameters.
</p><div class="example">
<pre class="example">&nbsp;{x+y}[1;2;3]
{x+y}[1;2;3]
^
:rank
</pre></div>

<span id="length"></span></div>
<div class="section" id="g_t_003alength">
<h3 class="section">18.3 :length</h3>
<p>Operations on unequal length lists that require equal length.
</p><div class="example">
<pre class="example">&nbsp;(1 2 3)+(4 5)
:length
</pre></div>

<span id="g_t_005ftype"></span></div>
<div class="section" id="g_t_003atype">
<h3 class="section">18.4 :type</h3>
<p>Calling a function with an unsupported variable type.
</p><div class="example">
<pre class="example">`a+`b
&nbsp; ^
:type
</pre></div>

<span id="domain"></span></div>
<div class="section" id="g_t_003adomain">
<h3 class="section">18.5 :domain</h3>
<p>Exhausted the number of input values
</p><div class="example">
<pre class="example">&nbsp;-12?10   / only 10 unique value exist
:domain
</pre></div>

<span id="limit"></span></div>
<div class="section" id="g_t_003alimit">
<h3 class="section">18.6 :limit</h3>
<p>Exceeded a limit above the software maximum, eg. writing a single file above 1GB.
</p><div class="example">
<pre class="example">&nbsp;n:_100e6;d:+`x`y!(!n;n?1.);`d 2:d
n:_100e6;d:+`x`y!(!n;n?1.);`d 2:d

:limit
</pre></div>

<span id="nyi"></span></div>
<div class="section" id="g_t_003anyi">
<h3 class="section">18.7 :nyi</h3>
<p>Running code that is not yet implemented.  This may come from running code in this document with a different version of k9.
</p>
<p>2020.05.31 (c) shakti
</p>
<div class="example">
<pre class="example">&nbsp;=+`a`b!(1 2;1 3)
a b| 
- -|-
1 1|0
2 3|1
</pre></div>

<p>Aug  6 2020 16GB (c) shakti
</p>
<div class="example">
<pre class="example">&nbsp;=+`a`b!(1 2;1 3)
=+`a`b!(1 2;1 3)
^
:nyi
</pre></div>

<span id="eparse"></span></div>
<div class="section" id="g_t_003aparse">
<h3 class="section">18.8 :parse</h3>
<p>Syntax is wrong.  This may be due to mismatched parentheses or  brackets, e.g., (), {}, [], &quot;&quot;.
</p><div class="example">
<pre class="example">&nbsp;{37 . &quot;hello&quot;
:parse
</pre></div>

<span id="g_t_005fvalue"></span></div>
<div class="section" id="g_t_003avalue">
<h3 class="section">18.9 :value</h3>
<p>Undefined variable is used.
</p><div class="example">
<pre class="example">&nbsp;g    / assuming 'g' has not be defining in this session
:value
</pre></div>
<hr>
</div>
</div>
<div class="chapter" id="Examples">
<div class="header">
<p>
Next: <a href="#Benchmark" accesskey="n" rel="next">Benchmark</a>, Previous: <a href="#Errors" accesskey="p" rel="prev">Errors</a>, Up: <a href="#Top" accesskey="u" rel="up">k9: Manual</a> &nbsp; </p>
</div>
<span id="Examples-1"></span><h2 class="chapter">19 Examples</h2>
<p>This chapter presents an example from finance, as this is one of the primary application domains for k.  For those not familiar with this field, here is a short introduction.
</p>
<ul class="section-toc">
<li><a href="#A-Tiny-Introduction-to-Financial-Market-Data" accesskey="1">A Tiny Introduction to Financial Market Data</a></li>
<li><a href="#Data-Manipulation" accesskey="2">Data Manipulation</a></li>
<li><a href="#Understanding-Code-Examples" accesskey="3">Understanding Code Examples</a></li>
</ul>
<div class="section" id="A-Tiny-Introduction-to-Financial-Market-Data">
<h3 class="section">19.1 A Tiny Introduction to Financial Market Data</h3>
<p>Finance has a large amount of data associated with it.  In this section finance data will be limited to price and transaction information which typically includes prices to buy and sell (called quotes) and transactions (called trades).  This data includes the date, financial instrument symbol, time, and exchange / venue.  Additionally quotes will have a bid and ask price (where the deal is willing to buy and sell) and trades will have a price and size of the reported transaction.
</p>
<p>Although real prices are often shown as fractions of a whole amount, eg. eurusd might be at 1.1904, the actual trades are dealt in whole cents or currencies so can be represented as integers.
</p>
<p>Let&rsquo;s start with a simple example of only times (t), bid (b), and ask (a).
</p>
<div class="example">
<pre class="example"> n:10
 T:^10:00+`t n?36e5  / sort randomly generated times
 B:100++\-1+n?3      / generate bids near 100, equivalent to: 100 + (+\((-1)+n?3))
 A:B+1+n?2           / generates asks 1 or 2 higher
 q:+`t`b`a!(T;B;A);q / build table t and then display
t            b   a  
------------ --- ---
10:01:48.464 100 102
10:23:12.033 100 102
10:30:00.432 101 102
10:34:00.383 101 103
10:34:36.839 101 102
10:42:59.230 100 102
10:46:50.478 100 102
10:52:42.189  99 100
10:55:52.208  99 101
10:59:06.262  98  99
</pre></div>

<p>Here you see that at 10:42:59.230 the prices update to 100 and 102.  The price one could sell is 100 and the price to buy is 102.  You might think that 100 seems a bit high so sell there.  Later at 10:59:06.262 you might have thought the prices look low and then buy at 99.  Here&rsquo;s the trade table for those two transactions.
</p>
<div class="example">
<pre class="example"> t:+`t`p!(10:43:00.230 10:59:07.262:;100 99);t
t            p  
------------ ---
10:43:00.230 100
10:59:07.262  99
</pre></div>

<p>You&rsquo;ll note that the times didn&rsquo;t line up, because it apparently took you a second to decide to trade.  Because of this delay, you&rsquo;ll often have to look back at the previous prices to join trade (t) and quote (q) data.
</p>
<p>Now that you&rsquo;ve learned enough finance to understand the data, let&rsquo;s scale up to larger problems to see the power of k9.  
</p>
</div>
<div class="section" id="Data-Manipulation">
<h3 class="section">19.2 Data Manipulation</h3>

<p>Let&rsquo;s use k9 to generate a set of random quotes for a particular day and symbol.
</p>
<div class="example">
<pre class="example"> qs:`date`sym`time`exch`bid`ask            / quote table schema
 nf:d+*|d:(|-d),d:683 954 997 1000;        / normal func
 D:#[;2021.03.17]                          / date
 S:#[;`eurusd]                             / symbol
 T:^?[;_8.64e7]@                           / time in number of milliseconds
 E:?[;&quot;ce&quot;]                                / exchange
 B:11904++\-3+nf bin/:?[;*|nf]@            / bid price, start at 11904
 P:?[;2,2,8#1]@                            / bid/ask spread
 Q:{+qs!((D;S;T;E)@'x),(*;+/)@\:(B;P)@'x}  / generator quote table
 q:Q@_1e8;10#q
date       sym    time exch bid   ask  
---------- ------ ---- ---- ----- -----
2021.03.17 eurusd    0 c    11904 11905
2021.03.17 eurusd    0 e    11904 11906
2021.03.17 eurusd    2 e    11902 11903
2021.03.17 eurusd    3 c    11902 11903
2021.03.17 eurusd    9 c    11904 11906
2021.03.17 eurusd    9 c    11904 11905
2021.03.17 eurusd   10 c    11904 11905
2021.03.17 eurusd   12 c    11904 11905
2021.03.17 eurusd   12 c    11904 11905
2021.03.17 eurusd   12 e    11904 11906
</pre></div>

<p>At this point let&rsquo;s run some basic statistics to see how quickly one can work with 100 million rows of data.  On a reletaviley recent consumer laptop the spread calculation (the longest calculation of the bunch) is done in 350ms.
</p>
<div class="example">
<pre class="example"> select max bid,min ask from q
bid|18449
ask|5972 

select mid:avg 0.5*bid+ask from q
[mid:14198.32]

select spread:avg ask-bid from q
[spread:1.200035]

select first bid, first ask from q
bid|11904
ask|11905

select last bid, last ask from q
bid|14906
ask|14907
</pre></div>

</div>
<div class="section" id="Understanding-Code-Examples">
<h3 class="section">19.3 Understanding Code Examples</h3>
<p>In the shakti mailing list there are a number of code examples that can be used to learn best practices.  In order to make sense of other people&rsquo;s codes, one needs to be able to efficiently understand  k9 language expressions.  Here is an example of how one goes about this process.
</p>
<div class="example">
<pre class="example">ss:{*{
      o:o@&amp;(-1+(#y)+*x@1)&lt;o:1_x@1;
      $[0&lt;#x@1;((x@0),*x@1;o);x]}[;y]/:(();&amp;(x@(!#x)+\:!#y)~\:y)
      }
</pre></div>

<p>This function finds a substring in a string.
</p>
<pre class="verbatim"> 000000000011111111112222222222333333
 012345678901234567890123456789012345
&quot;Find the +++ needle in + the ++ text&quot;
</pre>
<p>Here one would expect to find &ldquo;++&rdquo; at 9 and 29.
</p>
<div class="example">
<pre class="example">&nbsp;ss[&quot;Find the +++ needle in + the ++ text&quot;;&quot;++&quot;]
9 29
</pre></div>

<p>In order to determine how this function works let&rsquo;s strip out the details...
</p>
<div class="example">
<pre class="example">ss:{
    *{
      o:o@&amp;(-1+(#y)+*x@1)&lt;o:1_x@1; / set o 
      $[0&lt;#x@1;((x@0),*x@1;o);x]   / if x then y else z
      }
  [;y]/:(();&amp;(x@(!#x)+\:!#y)~\:y)    / use value for inner function
  }
 
</pre></div>

<p>Given that k9 evaluates right to left, let&rsquo;s start with the rightmost code fragment.
</p>
<div class="example">
<pre class="example">&nbsp;(();&amp;(x@(!#x)+\:!#y)~\:y)          / a list (null;value)
</pre></div>

<p>And now let&rsquo;s focus on the value in the list.
</p>
<div class="example">
<pre class="example">&nbsp;&amp;(x@(!#x)+\:!#y)~\:y
</pre></div>

<p>In order to easily check our understanding, we can wrap this in a function and call the function with the parameters shown above.  In order to step through, we can start with the inner parenthesis and build up the code until it is complete.
</p>
<div class="example">
<pre class="example">&nbsp;{!#x}[&quot;Find the +++ needle in + the ++ text&quot;;&quot;++&quot;]
{!#x}[&quot;Find the +++ needle in + the ++ text&quot;;&quot;++&quot;]
^
:rank
</pre></div>

<p>This won&rsquo;t work as one cannot call a function with two arguments and then use only one.  In order to get around this, we will insert code for the second argument but not use it.
</p>
<div class="example">
<pre class="example"> {y;#x}[&quot;Find the +++ needle in + the ++ text&quot;;&quot;++&quot;]
36
 {y;!#x}[&quot;Find the +++ needle in + the ++ text&quot;;&quot;++&quot;]
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 ..
</pre></div>

<p>As might have been guessed <code>#x</code> counts the number of charcters in the first argument and then <code>!#x</code> generates a list of integers from 0 to n-1.
</p>
<div class="example">
<pre class="example">&nbsp;{(!#x)+\:!#y}[&quot;Find the +++ needle in + the ++ text&quot;;&quot;++&quot;]  
 0  1
 1  2
 2  3
 3  4
 4  5
 5  6
 6  7
 7  8
 8  9
 9 10
10 11
11 12
12 13
13 14
14 15
15 16
16 17
17 18
18 19
19 20
20 21
..
</pre></div>

<p>Here the code takes each integer from the previous calculation and then adds an integer list as long as the second argument to each value.  In order to verify this,  you could write something similar and ensure the output what you predicted.
</p>
<div class="example">
<pre class="example">&nbsp;{(!x)+\:!y}[6;4]
0 1 2 3
1 2 3 4
2 3 4 5
3 4 5 6
4 5 6 7
5 6 7 8
</pre></div>

<p>Now using the matrix above the code indices as the first argument and pull substrings that match the length of the search string.
</p>
<div class="example">
<pre class="example">&nbsp;{x@(!#x)+\:!#y}[&quot;Find the +++ needle in + the ++ text&quot;;&quot;++&quot;]
Fi
in
nd
d 
 t
th
he
e 
 +
++
++
+ 
 n
ne
ee
ed
dl
le
e 
 i
in
..
</pre></div>

<p>At this point one can compare the search substring in this list of substrings to find a match.
</p>
<div class="example">
<pre class="example">&nbsp;{(x@(!#x)+\:!#y)~\:y}[&quot;Find the +++ needle in + the ++ text&quot;;&quot;++&quot;]
000000000110000000000000000001000000b
</pre></div>

<p>And then one can use the where function, <code>&amp;</code>, to determine the index of the matches.
</p>
<div class="example">
<pre class="example">&nbsp;{&amp;(x@(!#x)+\:!#y)~\:y}[&quot;Find the +++ needle in + the ++ text&quot;;&quot;++&quot;]
9 10 29
</pre></div>

<p>The rest of the &rsquo;ss&rsquo; function code is left as an exercise for the reader.  
</p>
<hr>
</div>
</div>
<div class="chapter" id="Benchmark">
<div class="header">
<p>
Next: <a href="#Conclusion" accesskey="n" rel="next">Conclusion</a>, Previous: <a href="#Examples" accesskey="p" rel="prev">Examples</a>, Up: <a href="#Top" accesskey="u" rel="up">k9: Manual</a> &nbsp; </p>
</div>
<span id="Benchmark-1"></span><h2 class="chapter">20 Benchmark</h2>
<p>Shakti is a fast data analysis language  and clear benchmarks illustrate this.  The Shakti website has a number of files for such purpose, b.k and taxi.k amongst others.  
</p>
<ul class="section-toc">
<li><a href="#b_002ek" accesskey="1">b.k</a></li>
<li><a href="#taxi" accesskey="2">taxi</a></li>
</ul>
<div class="section" id="b_002ek">
<h3 class="section">20.1 b.k</h3>

<pre class="verbatim">T:{09:30:00+_6.5*3600*(!x)%x}
P:{10+x?90};Z:{1000+x?9000};E:?[;&quot;ABCD&quot;]

/m:2;n:6
m:7000;n:5600000;
S:(-m)?`4;N:|1+_n*{x%+/x:exp 15*(!x)%x}m

t:S!{+`t`e`p`z!(T;E;P;Z)@'x}'N
q:S!{+`t`e`b!(T;E;P)@'x}'6*N

a:*A:100#S

\t  {select max p by e from x}'t A
\t  {select sum z by `o t from x}'t A
\t:10 {select last b from x}'q A
\t:10 select from t[a],`t^q a where p&lt;b
\

C:M:?[;&quot;ABCDEFGHIJ&quot;]
trade(sym time exchange price size cond)
quote(sym time exchange bid bz ask az mode)

                Q1      Q2      Q3      Q4  ETL   RAM   DSK
k                1       9       9       1                                            
postg        71000    1500    1900     INF  200   1.5   4.0
spark       340000    7400    8400     INF  160  50.0   2.4
mongo        89000    1700    5800     INF  900   9.0  10.0   

960 billion quotes (S has 170 billion. QQQ has 6 billion.)
 48 billion trades (S has 12 billion. QQQ has 80 million.)
</pre>
<ul class="section-toc">
<li><a href="#T" accesskey="1">T</a></li>
<li><a href="#P_002c-Z_002c-E" accesskey="2">P, Z, E</a></li>
<li><a href="#m_002c-n_002c-S_002c-N" accesskey="3">m, n, S, N</a></li>
<li><a href="#t" accesskey="4">t</a></li>
<li><a href="#q" accesskey="5">q</a></li>
<li><a href="#a_002c-A" accesskey="6">a, A</a></li>
<li><a href="#Max-price-by-exchange" accesskey="7">Max price by exchange</a></li>
<li><a href="#Compute-sum-of-trade-size-by-hour_002e" accesskey="8">Compute sum of trade size by hour.</a></li>
<li><a href="#Compute-last-bid-by-symbol" accesskey="9">Compute last bid by symbol</a></li>
<li><a href="#Find-trades-below-the-bid">Find trades below the bid</a></li>
</ul>
<div class="subsection" id="T">
<h4 class="subsection">20.1.1 T</h4>
<p>T is a function which generates a uniform list of times from 09:30 to 16:00.
</p>
<div class="example">
<pre class="example">&nbsp;T:{09:30:00+_6.5*3600*(!x)%x}
&nbsp;T[13]           / 13 times with equal timesteps over [start;end)
^09:30:00 10:00:00 10:30:00 11:00:00 11:30:00 .. 15:00:00 15:30:00
&nbsp;?1_-':T[10000]  / determine the unique timesteps
?00:00:02 00:00:03
</pre></div>

</div>
<div class="subsection" id="P_002c-Z_002c-E">
<h4 class="subsection">20.1.2 P, Z, E</h4>
<p>P is a function to generate values from 10 to 100 (price).  Z is a function to generate values from 100 to 1000 (size).  E is a function to generate values A, B, C, or D (exchange).
</p>
<div class="example">
<pre class="example">&nbsp;P[10]
78 37 56 85 40 68 88 50 41 78
&nbsp;Z[10]
4820 2926 1117 4700 9872 3274 6503 6123 9451 2234
&nbsp;E[10]
&quot;AADCBCCCBC&quot;
</pre></div>

</div>
<div class="subsection" id="m_002c-n_002c-S_002c-N">
<h4 class="subsection">20.1.3 m, n, S, N</h4>
<p>m is the number of symbols.  n is the number of trades.  S is a list of symbol names.  N is a list of  numbers in decreasing order which sum approximately to n.  
</p>
<div class="example">
<pre class="example">&nbsp;4#S
`EEFD`IOHJ`MEJO`DHNK
&nbsp;4#N
11988 11962 11936 11911
&nbsp;+/N
5604390
</pre></div>

</div>
<div class="subsection" id="t">
<h4 class="subsection">20.1.4 t</h4>
<p>t is an ntable of trades.  The fields are time (t), exchange (e), price (p), and size (z).  The number of trades is set by n.
</p>
<p>Pulling one random table from t and showing 10 random rows.  
</p>
<div class="example">
<pre class="example">&nbsp;10?*t@1?S
t        e p  z   
-------- - -- ----
14:37:53 D 73 4397
11:43:25 B 20 2070
10:21:18 A 53 6190
13:26:03 C 33 7446
14:07:06 B 13 2209
15:08:41 D 12 4779
14:27:37 A 11 6432
11:22:53 D 92 9965
11:12:37 A 14 5255
12:24:28 A 48 3634
</pre></div>

</div>
<div class="subsection" id="q">
<h4 class="subsection">20.1.5 q</h4>
<p>q is a ntable of quotes.  The fields are time (t), exchange (e), and bid (b).  The number of quotes is set to 6*n.
</p>
<div class="example">
<pre class="example">&nbsp;10?*q@1?S
t        e b 
-------- - --
11:31:12 A 80
14:08:40 C 63
14:05:07 D 12
11:31:43 A 56
12:44:19 A 45
10:13:21 A 71
15:19:08 A 74
13:42:20 D 43
11:31:41 D 66
14:41:38 A 63
</pre></div>

</div>
<div class="subsection" id="a_002c-A">
<h4 class="subsection">20.1.6 a, A</h4>
<p>a is the first symbol of S.  A consists of the first 100 symbols of S.
</p>
<div class="example">
<pre class="example">&nbsp;a
`PKEM
</pre></div>

</div>
<div class="subsection" id="Max-price-by-exchange">
<h4 class="subsection">20.1.7 Max price by exchange</h4>
<p>The query takes 100 tables from the trade ntable and computes the max price by exchange.
</p>
<div class="example">
<pre class="example">&nbsp;*{select max p by e from x}'t A
e|p 
-|--
A|99
B|99
C|99
D|99
&nbsp;\t  {select max p by e from x}'t A
22
</pre></div>

</div>
<div class="subsection" id="Compute-sum-of-trade-size-by-hour_002e">
<h4 class="subsection">20.1.8 Compute sum of trade size by hour.</h4>
<p>This query takes 100 tables from the trade ntable and computes the sum of trade size done by hour.
</p>
<div class="example">
<pre class="example">&nbsp;*{select sum z by `o t from x}'t A
t |z       
--|--------
09| 4885972
10|10178053
11|10255045
12|10243846
13|10071057
14|10203428
15|10176102
&nbsp;\t  {select sum z by `o t from x}'t A
27
</pre></div>

</div>
<div class="subsection" id="Compute-last-bid-by-symbol">
<h4 class="subsection">20.1.9 Compute last bid by symbol</h4>
<p>This query takes the 100 tables from the quote ntable and returns the last bid.
</p>
<div class="example">
<pre class="example">&nbsp;3?{select last b from x}'q A
b 
--
18
98
85

&nbsp;\t:10 {select last b from x}'q A
2
</pre></div>

</div>
<div class="subsection" id="Find-trades-below-the-bid">
<h4 class="subsection">20.1.10 Find trades below the bid</h4>
<p>This query operates on one symbol from the q and t ntables, i.e. a single quote and trade table.  The quote table is joined to the trade table giving the current bid on each trade.
</p>
<div class="example">
<pre class="example">&nbsp;4?select from t[a],`t^q a where p&lt;b
t        e p  z    b 
-------- - -- ---- --
13:54:35 B 94 1345 96
11:59:52 C 26 1917 89
10:00:44 C 40 9046 81
10:59:39 A 25 5591 72
&nbsp;\t:10 select from t[a],`t^q a where p&lt;b
3
</pre></div>

</div>
</div>
<div class="section" id="taxi">
<h3 class="section">20.2 taxi</h3>
<p>The taxi data analysis problem has become well known given the ease of acquiring the data and the size of it.  It&rsquo;s well written up  <a href="https://toddwschneider.com/posts/analyzing-1-1-billion-nyc-taxi-and-uber-trips-with-a-vengeance/">here</a> with a benchmark summary <a href="https://tech.marksblogg.com/benchmarks.html">here</a>.  Shakti has a benchmark script to generate simulated taxi data in order to check performance.
</p>
<div class="format">
<pre class="verbatim">/taxi 1.1billion https://tech.marksblogg.com/benchmarks.html
/type/pcount/distance/amount

g:{[[]t:x rand`y`g;p:x rand 9;d:x rand 100;a:x rand 100.]}
x:d!g':44000+&amp;#d:2009.01.01+!2500  /110 million example

ys:{`y[!x]sum/x} / year sum
\t sum{select[t]count from x}':x
\t ys@{select[p]count from x}':x
\t sum{select[p]sum a from x}':x
\t ys@{select[p,d]count from x}':x

\
x:g 10
select[t]count from x
select[p]count from x
select[p]sum a from x
select[p,d]count from x


Q1 select[t]count from x
Q2 select[p]avg a from x
Q3 select[d.y,p]count from x
Q4 select[d.y,p,d]count from x

          cpu  cost core/ram  elapsed         machines
k           4 .0004    4/16    1            1*i3.2xlarge(8v/32/$.62+$.93)
redshift  864 .0900  108/1464  8(1 2 2 3)   6*ds2.8xlarge(36v/244/$6.80)
db/spark 1260 .0900   42/336  30(2 4 4 20) 21*m5.xlarge(4v/16/$.20+$.30)
bigquery 1600 .3200  200/3200  8(2 2 1 3)

cost: k/redshift/databricks(1.5*EC2) bigquery(redshift) $5.00*TB  k($.05/TB)

csv
/vendor,pickup,dropoff,pcount,dist1,plong,plat,rate,flag,dlong,dlat,ptype,fare1,sur1,mta1,tip1,toll1,amount1
t:&quot;b  12            e&quot;  / type(2) passenger(8)
\t t:(`t`p`d`a;&quot;,&quot;;t)0:&quot;taxi.csv&quot;</pre></div>

<ul class="section-toc">
<li><a href="#g" accesskey="1">g</a></li>
<li><a href="#x" accesskey="2">x</a></li>
<li><a href="#g_t2009_002e01_002e04" accesskey="3">2009.01.04</a></li>
</ul>
<div class="subsection" id="g">
<h4 class="subsection">20.2.1 g</h4>
<p>Function to generate a table of random data to represent taxi company (<b>t</b> either yellow &lsquo;y or green &lsquo;g),  paid fare (<b>p</b> 0-9), distance travelled (<b>d</b> 0-99) and address (<b>a</b> 0-100.).
</p>
<div class="example">
<pre class="example"> g:{[[]t:x?`y`g;p:x?9;d:x?100;a:x?100.]}
 g 10
t p d  a       
- - -- --------
y 7 38 50.67771
g 5 34 38.51022
y 6 40 9.654263
y 6  5 98.91451
g 7 47 44.40432
g 0 64 66.07784
y 0 99 25.84292
y 5 46 46.87825
y 5 66 81.61647
g 0 10 7.946983
</pre></div>

</div>
<div class="subsection" id="x">
<h4 class="subsection">20.2.2 x</h4>
<p>x is an ntable containing 2500 tables, keyed on day.  Each individual table contains 44,000 rows therefore x has 110 million rows in total.
</p>
<div class="example">
<pre class="example"> x:d!g':44000+&amp;#d:2009.01.01+!2500  /110 million example
 x
2009.01.01|[[]t:`y`y`g`y`g`g`y`y`g`g`g`g`g`y`y`y`y`g`g`g..
2009.01.02|[[]t:`y`g`g`g`y`g`y`g`y`g`g`g`g`y`g`y`g`y`g`y..
2009.01.03|[[]t:`y`g`g`g`y`g`y`g`y`g`g`g`g`y`g`y`g`y`g`y..
2009.01.04|[[]t:`y`g`g`g`y`g`y`g`y`g`g`g`g`y`g`y`g`y`g`y..
..
</pre></div>

</div>
<div class="subsection" id="g_t2009_002e01_002e04">
<h4 class="subsection">20.2.3 2009.01.04</h4>
<p>Let&rsquo;s work with a single table to understand the queries and limit it to 5 rows.
</p>
<div class="example">
<pre class="example"> q:5#x 2009.01.04;q
t p d  a       
- - -- --------
y 3 41 54.5307 
g 6 70 70.4241 
g 1 63 81.46645
g 7 36 43.12615
y 1 43 23.50114
</pre></div>

<p>Now let&rsquo;s count the number of rows by field t.  Looking at the data above you should expect 2 yellow (y) taxi trips and 3 green (g) taxi trips.
</p>
<div class="example">
<pre class="example"> select[t]count from q
t|n
-|-
g|3
y|2
</pre></div>

<p>We can also sum the paid fare (p) by taxi company (t).
</p>
<div class="example">
<pre class="example"> select[t]sum p from q
t|p
-|--
g|14
y| 4
</pre></div>

<p>Now if we want to compute the same over all the data we need to run the kSQL query over each table.  We&rsquo;ll do this on parallel threads (<a href="#eachprior">eachprior</a>) to speed it up.
</p>
<div class="example">
<pre class="example"> {select[t]count from x}':x
2009.01.01|[[t:`g`y]n:21968 22032]
2009.01.02|[[t:`g`y]n:21962 22038]
2009.01.03|[[t:`g`y]n:21962 22038]
2009.01.04|[[t:`g`y]n:21962 22038]
</pre></div>

<p>and then sum over all days.
</p>
<div class="example">
<pre class="example"> sum{select[t]count from x}':x
t|n       
-|--------
g|55010927
y|54989073
</pre></div>

<p>Running the command with the timer will allow us to measure how long it takes to sum over the 110 million examples.
</p>
<div class="example">
<pre class="example"> \t sum{select[t]count from x}':x
1077
</pre></div>

<hr>
</div>
</div>
</div>
<div class="chapter" id="Conclusion">
<div class="header">
<p>
Previous: <a href="#Benchmark" accesskey="p" rel="prev">Benchmark</a>, Up: <a href="#Top" accesskey="u" rel="up">k9: Manual</a> &nbsp; </p>
</div>
<span id="Conclusion-1"></span><h2 class="chapter">21 Conclusion</h2>

<p>I expect you are pleasantly surprised by the speed of k9 and by the fact that it all fits in 134,152 bytes!  (For comparison the ls program weighs in at 51,888 bytes and can&rsquo;t even change directory.)
</p>
<p>If you&rsquo;re frustrated by the syntax or terse errors, then you&rsquo;re not alone.  Many have had the same problems, but persevered, and finally came away a power user able to squeeze information from data faster than previously imagined.
</p>
<p>Eventually, you&rsquo;ll realize that this manual isn&rsquo;t needed and it&rsquo;s all here...
</p>
<div class="format">
<pre class="verbatim">select count first last min max sum avg var dev .. by ..
in n_(rand) n@(multiply) n?(divide) n@n?(bar)

Verb     monad        Adverb            Type 
+ +                   ' each            char   &quot; ab&quot;          
- -                   / over            sym    ``ab
* *                   \ scan            bool   011b   
% div                                   int    2 3 4
! mod    where        System            float  2 3e4      
&amp; &amp;      flip         \l load          -fixed  2.0 3.4
| |      reverse      \t time          -locus  -74::40.7      
&lt; &lt;      asc          \v vars       z.d date   2001.02.03  
&gt; &gt;      desc         \w work       z.t time   12:34:56.789
= =      freq                       z.T datetime
~ ~      ~                                      
, ,      ,
# take   count        I/O               Class
_ drop   first        0' line           expr   :2+a
^ cut    sort         1' char/stdout    func   f[a] 2+a
@ @      type         2' data/stderr              
? find   unique      *3' set            list   (2;3.4)  
$ parse  str         *4' get            dict   {a:2 3}
. dict   value       *5' ffi            table  [a:2 3]</pre></div>


</div>
</div>


</body>
</html>