Kalkulon online help

Content

Data types
Variables
Operators
Casts
Build-in mathematical functions
Build-in list and string functions
Build-in functions for functional programming
Build-in system functions
Programming with Kalkulon

User defined functions
Control structures

Autoload
Command line options
Contact information

Data types

Numbers (Floating point and Integer)

All numbers are represented internally as double precision floats, e.g 1234, 2.5, 3.141e6. All operators and all build-in mathematical functions calculate with double precision. All integer operations (like bit-wise AND, OR, shifts, MODulo etc.) work on a 32-bit basis. If necessary float numbers are casted to either U32 or S32.

Strings

Strings are represented as characters in quotation marks, e.g. "Hello World!". Strings can be concatenated by the plus (+) operator and manipulated with build-in string functions. The following escape sequences are recognized: "\\" for backslash, "\"" for double quote, "\n" for newline, "\t" for tab.

Lists

Lists are containers for numbers, strings and lists of arbitrary size and dimension, e.g. {1,2,3}, {"abc",def"}, {3.141, "Pi", {99, 66, {33}, {}}}, {{1,1}, {1,2}, {2,1}, {2,2}}. {} is the empty list of size 0 (see Size()). Lists can be concatenated by the plus (+) operator and manipulated with build-in list functions. Single elements are addressed with the zero-based index operator ([]), e.g. {44, 55, 66}[1] == 55, {44, {55, 66}}[1,1] == {44, {55, 66}}[1][1] == 66.

Pure functions

Pure functions are user-defined functions without name in single quotes, e.g. '1/#'. The arguments of pure functions are named # or #1 for the first, #2 for the second, #3 for the third argument and so on. Pure functions can be handled like normal data types, e.g. passed as arguments to ordinary functions (for examples see Functional programming). To evaluate a pure function for a specific argument the resolve operator (@) has to be used.
Examples:
pf='1/#'

outl[1] = <pure function>

pf@(8)

outl[2] = 0.125

f(purefn, arg) = purefn@(arg)

function defined

f(pf, 8)

outl[3] = 0.125

f('10*#', 5)

outl[4] = 50

The type of an object can be obtained from Type(obj)

Go to top

Variables

Any object can be assigned to a valid C-like-variable, e.g. calc_result1 = 5*3, text = "Hello", list = {1, 2, 3}. All operators and functions used with variables have value semantics, e.g. does not change the content of the variable. The only exceptions are assignment operators (= += etc.) and pre/post increment and decrement (++ --). This is the only way to change the content of a variable. The index operator ([]) can be used in combination.
Examples: ctr=10

outl[0] = 10

++ctr

outl[1] = 11

a={{2,3},{4,5}}

outl[2] = {{2, 3}, {4, 5}}

a[1,1]+=10

outl[3] = 15

++a[1,1]

outl[4] = 16

outl[5] = {{2, 3}, {4, 16}}

reserved variables

In an interactive session the variables out and outl are reserved. The value of out is always the last result, outl[i] is the ith result.

Go to top

Operators

arithmetic	+ - * /
pre/post increment and decrement	++ --
MODulo	%
AND, OR, XOR, NOT (bit-wise)	& \| ^ ~
AND, OR, NOT (logical)	&& \|\| !
LEFT SHIFT, RIGHT SHIFT	<< >>
POWer	**
relational	== != > >= < <=
assignment	= += -= = /= %= &= \|= ^= <<= >>= *=
index operator	[ ]
global scope operator	::
pure function resolve operator	@
delimiter string, list, pure function	" " { } ' '
miscellaneous	( ) , ;
block comment	/* */
line comment	//

Go to top

Casts

unsigned 8 bit	: u8, u08, ub, byte, U8, U08, UB, BYTE
signed 8 bit	: s8, s08, sb, char, S8, S08, SB, CHAR
unsigned 16 bit	: u16, uw, word, U16, UW, WORD
signed 16 bit	: s16, sw, S16, SW
unsigned 32 bit	: u32, ul, U32, UL
signed 32 bit	: s32, sl, S32, SL
String	: string, STRING

Go to top

Build-in mathematical functions

abs(x)	returns the absolute value of its argument Example: abs(-4) out = 4
acos(x)	returns the arccosine of x in the range 0 to π radians. If x is less than –1 or greater than 1, acos returns an indefinite Example: acos(0) out = 1.57079632679
asin(x)	returns the arcsine of x in the range –π/2 to π/2 radians. If x is less than –1 or greater than 1, asin returns an indefinite Example: asin(1) out = 1.57079632679
atan(x)	returns the arctangent of x. atan returns a value in the range –π/2 to π/2 radians Example: atan(1) out = 0.785398163397
ceil(x)	returns a floating-point value representing the smallest integer that is greater than or equal to x Example: ceil(3.141) out = 4
cos(x)	returns the cosine Example: cos(3.141) out = -0.999999824381
cosh(x)	returns the hyperbolic cosine Example: cosh(1) out = 1.54308063482
exp(x)	returns the exponential value of x Example: exp(1) out = 2.71828182846
floor(x)	returns a floating-point value representing the largest integer that is less than or equal to x Example: floor(3.141) out = 3
fmod(x, y)	returns the floating-point remainder of x / y Example: fmod(9.8, 4.3) out = 1.2
fp(x)	returns the floating part of x Example: fp(456.234) out = 0.234
ip(x)	returns the integer part of x Example: ip(456.234) out = 456
ld(x)	returns the base-2 logarithm of x Example: ld(1024) out = 10
ln(x)	returns the natural logarithm of x (base e) Example: ln(2) out = 0.69314718056
log(x)	returns the base-10 logarithm of x. Example: log(1000000) out = 6
max(x, y)	returns the maximum of x and y Example: max(6, 9) out = 9
min(x, y)	returns the minimum of x and y Example: min(6, 9) out = 6
pow(x, y)	returns x raised to the power of y, identical to operator Example: pow(2, 0.5) out = 1.41421356237 20.5 out = 1.41421356237
rand()	returns a pseudo random number in the range 0 to 1. Use srand to seed the generator. Example: rand() out = 0.00125125888852
sign(x)	returns 1 for x>0, -1 for x<0, 0 for x==0 Example: sign(-9) out = -1
sin(x)	returns the sine Example: sin(1) out = 0.841470984808
sinh(x)	returns the hyperbolic sine Example: sinh(1) out = 1.17520119364
sqrt(x)	returns the square-root Example: sqrt(16) out = 4
srand()	seeds the pseudo random generator, see rand
tan(x)	returns the tangent Example: tan(1) out = 1.55740772465
tanh(x)	returns the hyperbolic tangent Example: tanh(1) out = 0.761594155956

Go to top

Build-in list and string functions

Back(list)
Back(string)

returns the last element of list or string
Example:
Back({1,2,3})

outl[0] = 3

Back("Hallo World")

outl[1] = "d"

Erase(list, pos)
Erase(string, pos)
Erase(list, beg, end)
Erase(string, beg, end)

i) erases element at index pos
ii) erases elements in range [beg, end)
Example:
Erase({1,2,3,4,5}, 2)

outl[0] = {1, 2, 4, 5}

Erase({1,2,3,4,5}, 2, 4)

outl[1] = {1, 2, 5}

Erase("Hallo World", 6)

outl[2] = "Hallo orld"

Erase("Hallo World", 6, 11)

outl[3] = "Hallo "

Eval(string)

evaluates expression from string
Example:
expr="3+4*sqrt(9)"

outl[1] = "3+4*sqrt(9)"

Eval(expr)

outl[2] = 15

Front(list)
Front(string)

returns the first element of list or string
Example:
Front({1,2,3})

outl[0] = 1

Front("Hallo World")

outl[1] = "H"

FullForm(obj)

returns full form of obj
Example:
pf='3+4*#'

outl[1] = <pure function>

FullForm(pf)

outl[2] = "<pure function 3 4 # * + END_1 >"

Insert(list, pos, elem)
Insert(list, pos, sublist)
Insert(string, pos, substring)

i) inserts element at index pos
ii) inserts sublist beginning at index pos
iii) inserts substring beginning at index pos
Example:
Insert({1,2,3,4,5}, 2, 33)

outl[0] = {1, 2, 33, 3, 4, 5}

Insert({1,2,3,4,5}, 2, {33, 44, 55})

outl[1] = {1, 2, 33, 44, 55, 3, 4, 5}

Insert({1,2,3,4,5}, 2, {{33, 44, 55}})

outl[2] = {1, 2, {33, 44, 55}, 3, 4, 5}

Insert("Hallo World", 5, " big")

outl[3] = "Hallo big World"

PopBack(list)
PopBack(string)

removes last element
Example:
PopBack({1,2,3})

outl[0] = {1, 2}

PopBack("Hallo")

outl[1] = "Hall"

PopFront(list)
PopFront(string)

removes first element
Example:
PopFront({1,2,3})

outl[0] = {2, 3}

PopFront("Hallo")

outl[1] = "allo"

PushBack(list, elem)
PushBack(string, substring)

adds elem or substring to end of container
Example:
PushBack({1,2,3}, 4)

outl[0] = {1, 2, 3, 4}

PushBack({1,2,3}, {4,5,6})

outl[1] = {1, 2, 3, {4, 5, 6}}

PushBack("Hallo", " World")

outl[2] = "Hallo World"

PushFront(list, elem)
PushFront(string, substring)

adds elem or substring to begin of container
Example:
PushFront({1,2,3}, 4)

outl[0] = {4, 1, 2, 3}

PushFront({1,2,3}, {4,5,6})

outl[1] = {{4, 5, 6}, 1, 2, 3}

PushFront("Hallo", " World")

outl[2] = " WorldHallo"

Replace(list, pos, elem)
Replace(list, pos, sublist)
Replace(string, pos, substring)

replaces consecutive elements by elem, sublist or substring
Example:
Replace({1,2,3,4,5}, 2, 33)

outl[0] = {1, 2, 33, 4, 5}

Replace({1,2,3,4,5}, 2, {33,44})

outl[1] = {1, 2, 33, 44, 5}

Replace({1,2,3,4,5}, 2, {{33,44}})

outl[2] = {1, 2, {33, 44}, 4, 5}

Replace("Hallo World", 6, "Kalkulon")

outl[3] = "Hallo Kalkulon"

Size(obj)

returns number of elements of object obj
Example:
Size(3.141)

outl[0] = 1

Size("Hallo")

outl[1] = 5

Size({1,2,3,4})

outl[2] = 4

Size({1,2,3,{4,5}})

outl[3] = 4

Size({1,2,3,{4,5}}[3])

outl[4] = 2

Sprintf(format, num)
Sprintf(format, list)

returns formatted string. The following formats are allowed: %[flags][width][.precision]type, type is one of the standard types i, o, u, x, X, e, E, f, g, G, s or b for binary output (analogue to x).
Example:
Sprintf("binary 0b%016b", 0xab)

outl[0] = "binary 0b0000000010101011"

Sprintf("%s: %i, %f, %o", {"Result", 15.6, 15.6, 15.6})

outl[1] = "Result: 15, 15.600000, 17"

Sub(list, pos)
Sub(string, pos)
Sub(list, beg, end)
Sub(string, beg, end)

i) returns sub container from index pos to last element
ii) returns sub container in range [beg, end)Example:
Sub({1,2,3,4,5}, 2)

outl[0] = {3, 4, 5}

Sub({1,2,3,4,5}, 2, 4)

outl[1] = {3, 4}

Sub("Hallo World", 6)

outl[2] = "World"

Sub("Hallo World", 0, 5)

outl[3] = "Hallo"

Type(obj)

returns type of object:

Reserved	1
Number	2
String	3
List	4
Pure Function	5

Example:
Type(0xabcd)

outl[0] = 2

Type(3.141)

outl[1] = 2

Type("Hallo")

outl[2] = 3

Type({1,2,3})

outl[3] = 4

Type('1/#')

outl[4] = 5

Go to top

Build-in functions for functional programming

These functions make use of pure functions.

Fold(list, first, purefn)	returns purefn@(purefn@(purefn@(first, list[0]), list[1]), list[2])... (last element of FoldList, see also there) Example: Table(10, '#') // build table 1..10 outl[1] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10} Fold(outl[1], 0, '#1+#2') // add all elements outl[2] = 55 Fold(outl[1], 1, '#1*#2') // multiply all elements outl[3] = 3628800
FoldList(list, first, purefn)	returns {first, purefn@(first, list[0]), purefn@(purefn@(first, list[0]), list[1]), ...} Example: Table(10, '#') // build table 1..10 outl[1] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10} FoldList(outl[1], 0, '#1+#2') // add all elements outl[2] = {0, 1, 3, 6, 10, 15, 21, 28, 36, 45, 55} FoldList(outl[1], 1, '#1*#2') // multiply all elements outl[3] = {1, 1, 2, 6, 24, 120, 720, 5040, 40320, 362880, 3628800}
ForEach(list, purefn) ForEach(list1, list2, purefn)	i) returns for an unary pure function {purefn@(list[0]), purefn@(list[1]), ..., purefn@(list[size-1])} ii) returns for a binary pure function {purefn@(list1[0], list2[0]), purefn@(list1[1], list2[1])..., purefn@(list1[size-1], list2[size-1])} Example: Table(10, '#*2') // build list of squares outl[1] = {1, 4, 9, 16, 25, 36, 49, 64, 81, 100} ForEach(out, 'sqrt(#)') // calculate square root for each element outl[2] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10} ForEach(outl[1], outl[2], '#1#2') // calculate cubics outl[3] = {1, 8, 27, 64, 125, 216, 343, 512, 729, 1000}
Table(end, purefn) Table(start, end, purefn) Table(start, end, delta, purefn)	returns {purefn@(start+0delta), purefn@(start+1delta), ..., purefn@(end)} Example: Table(10,'10#') outl[1] = {10, 20, 30, 40, 50, 60, 70, 80, 90, 100} Table(10,20,'10#') outl[2] = {100, 110, 120, 130, 140, 150, 160, 170, 180, 190, 200} Table(1,0,0.2,'#') outl[3] = {1, 0.8, 0.6, 0.4, 0.2, 0}

Go to top

Build-in system functions

Beep(freq, dur)	plays system beep with frequency freq and duration dur in ms returns 0 if successful, -1 otherwise
ClearAll()	clears user-defined functions, variables, outl and out, do not call from user-defined function, only call from interactive session returns nothing
Error(string)	throws user-defined error Example: f(x)=(if(x%2; Error("odd number"); res=x/2),res); function defined f(10) outl[1] = 5 f(13) f@1::error: 'user defined' odd number
Exec(app) Exec(app, param)	starts external application app returns 0 if successful Example: Exec("uedit32.exe", "autoload.k") outl[0] = 0
GetTicks()	returns system timer in ms
LinePos(file, pos)	returns {line, column} of total offset pos in file , useful to open Kalkulon scripts at error position Example: define in autoload.k: edit(file,pos) = (file=file+".k", lp=LinePos(file, pos), Exec("uedit32", file+"/"+(string)lp[0]+"/"+(string)lp[1]) ); Load("error.k") outl[0] = 0 g(1) g@1::f@1::error: 'undefined symbol' "a" at pos 37 edit("error", 37) outl[1] = 0
Load(file)	loads Kalkulon script Example: define in autoload.k: load(file)=Load(file+".k"); define in func.k: ::PI=2acos(0); sin_deg(deg)=sin(deg/180PI); load("func") outl[0] = 0 sin_deg(30) outl[1] = 0.5
Print(obj)	prints object without linefeed Example: see PrintLn()
PrintLn() PrintLn(obj)	i) prints linefeed ii) prints object with linefeed Example: for(i=1; i<=5; i++; Print( (string)i + "2 ="), PrintLn(i2)) 12 =1 22 =4 32 =9 42 =16 5**2 =25
ReadBinData(file) ReadBinData(file, beg, end)	reads binary file and returns a list of bytes Example: WriteBinData("testbin", {1,2,3,4,5,6,7,8,9,10}) outl[1] = 0 now testbin contains 10 bytes with the values 1...10: ReadBinData("testbin") outl[2] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10} ReadBinData("testbin",3,6) outl[3] = {4, 5, 6}
ReadData(file)	reads text file and returns a list of lines (strings), to convert back to Kalkulon data types use Eval(expr) Example: WriteData("testdata", Table(10, '1/#')) outl[1] = 0 ReadData("testdata") outl[2] = {"1", "0.5", "0.333333333333", "0.25", "0.2", "0.166666666667", "0.142857142857", "0.125", "0.111111111111", "0.1"} ForEach(out, '1/Eval(#)') outl[3] = {1, 2, 3, 4, 5, 5.99999999999, 7.00000000001, 8, 9.00000000001, 10}
SetNumFormat(formatstring) SetBinFormat() SetHexFormat() SetSciFormat() SetStdFormat()	these functions set the output format for numbers (e.g. string representation), for formatstring see Sprintf returns previous value Example: a={sqrt(2),0xabcd,0b1100} outl[1] = {1.41421356237, 43981, 12} old=SetHexFormat() outl[2] = "%.12g" a outl[3] = {0x1, 0xabcd, 0xc} SetBinFormat() outl[4] = "0x%x" a outl[5] = {0b1, 0b1010101111001101, 0b1100} SetSciFormat() outl[6] = "0b%b" a outl[7] = {1.414213562373e+000, 4.398100000000e+004, 1.200000000000e+001} SetNumFormat("%g= 0x%x") outl[8] = "%.12e" a outl[9] = {1.41421= 0x1, 43981= 0xabcd, 12= 0xc} SetNumFormat(old) outl[10] = "%g= 0x%x" a outl[11] = {1.41421356237, 43981, 12}
SetRecursionLimit(limit)	sets new limit for recursion depth; be very careful setting this value, it is the limit for the recursion depth of internal eval() calls. For a given stack size defined at compile time this value must be small enough that no stack overflow can occur; the limit can be tested with "recursion_limit.k" script from the examples directory returns previous value Example: old=SetRecursionLimit(10) outl[1] = 150 bomb(x)=bomb(x) function defined bomb(0) bomb@1::...error: 'RECURSION LIMIT REACHED' in function "bomb" at pos 9 SetRecursionLimit(old) outl[2] = 10
Version()	returns version string
WriteBinData(file, list)	writes list of bytes to binary file returns 0 if successful Example: (see ReadBinData(file))
WriteData(file, list)	writes text file, one element of list per line (see also ReadData(file)) returns 0 if successful Example: WriteData("testdata", Table(10, '1/#')) outl[1] = 0 File testdata: 1 0.5 0.333333333333 0.25 0.2 0.166666666667 0.142857142857 0.125 0.111111111111 0.1

Go to top

Programming with Kalkulon

Programs in Kalkulon are just a set of user defined functions and variable definitions. Place the definitions in one or more files (recommended extension ".k") and load them with Load("name"). Now you can call the defined functions from the GUI. Expressions in Kalkulon have to be separated by the comma operator "," inside a function definition or statement. The semicolon ";" can be used as separator on global scope also.

Example:

content of file myfak.k:

fak(n) =
    (
        result=1,                       // define and initialize local variable 'result'
        while(n; result=result*n, n=n-1), // syntax of while: while(condition; body)
        result                            // return value
     );

GUI:

Load("myfak.k")

outl[0] = 0

fak(10)

outl[1] = 3628800

Have a look at the example scripts provided with Kalkulon!

Go to top

User defined functions

Syntax: funcname(arglist) = definition;

definition := expression ordefinition := (expression_list)
expression_list := expression, ..., expression

The return value of an expression list is the return value of the last expression.

Examples:

Simple formulas:

f() = 3; f(a) = 5*a; f(a,b) = a+b;

function defined

f()-f(10,4);

outl[0] = -11

f(8)

outl[1] = 40

Formulas with global/local variables:

define global PI:
PI=2*acos(0);

outl[0] = 3.14159265359

sin_deg(deg)=sin(deg/180*PI);

function defined

sin_deg(30)

outl[1] = 0.5

define global and local PI:
PI=5

outl[0] = 5

sin_deg(deg)=(PI=2*acos(0), sin(deg/180*PI));

function defined

sin_deg(30)

outl[1] = 0.5

outl[2] = 5

To modify a global from inside a function the scope operator :: has to be used, e.g.
factor = 5

outl[0] = 5

f(n)=(::factor=3, n*factor);

function defined

f(10)

outl[1] = 30

factor

outl[2] = 3

To use both local and global factor use the scope operator ::, e.g.
factor = 5

outl[0] = 5

f(n)=(factor=3, n*factor*::factor);

function defined

f(4)

outl[1] = 60

Go to top

Control structures

if(condition; body) or if(condition; then_body; else_body)
while(condition; body)
do(body; condition)
for(init; condition; iterate; body)

All control structures can also be used inside of expressions, e.g. have a return value. The return value of while, do, for is the return value of the last body evaluation, see the following examples. Instead of writing loops by hand it is often more convenient to use functional programming.

Examples:

Some ways to write a factorial function

// iterative (for n>=1)
fak1(n) = (result=1, while(n; result=result*n--));
fak2(n) = (result=1, do(result=result*n; --n));
fak3(n) = for(result=1, i=1; i<=n; i++; result=result*i);
// recursive (for n>=0)
fak4(n) = if(n<=1; 1; n*fak4(n-1));
// functional (n>=1)
fak5(n) = Fold(Table(n, '#'), 1, '#1*#2');
Go to top

Autoload

Kalkulon tries to load autoload.k at start from the current working directory. You can put your definitions here or use Load to load additional files.

Go to top

Command line options

There are two versions of Kalkulon: the GUI version Kalkulon.exe and the console version kkc.exe (especially for scripting).

options for kalkulon.exe

kalkulon.exe

starts interactive GUI

options for kkc.exe

kkc	starts interactive console
kkc /? or -h	shows help screen
kkc /e:"<expr>"	evaluates <expr>, e.g. kkc /e:"3+4"
kkc <file> [<ARGV[1]> ... <ARGV[n]>]	runs Kalkulon script <file> Example: define in argv.k: size=Size(ARGV), for(i=0; i<size; i=i+1; PrintLn(Sprintf("ARGV[%i] = %s",{i,ARGV[i]})) ), Print("Eval(ARGV[2]) = "), PrintLn(Eval(ARGV[2])); and run: kkc argv.k 66 8/9 {22,33} Hello output: ARGV[0] = argv.k ARGV[1] = 66 ARGV[2] = 8/9 ARGV[3] = {22,33} ARGV[4] = Hello Eval(ARGV[2]) = 0.888888888889

Go to top

If you have questions, suggestions or bug reports, please contact me!