Functions are used to group frequently used statement sequences in order to avoid redundancy. These statement blocks may be parametrized by up to 255 (script) resp. 16 (native) arguments. Thus, functions support modularization of programs and furthermore help to split a problem into (possibly independent) sub problems (Divide and Conquer).
Basically, a distinction between user defined script functions and those being imported through the C/C++ plugin interface must be made. Plugin functions are limited to 16 arguments while script functions may take up to 255 arguments.
A special case of a function is a method which is a function attached to a class. Technically its the same as a function except a method can also "see" the current object ("this").
The return value of a user defined function is dynamic and may change according to the current parameter set. Each function may return one value at most. If multiple return values are required, a HashTable or Array object can be used.
Example:
function Deg2Rad(float _degrees) {
return _degrees*2PI/360.0;
}
print Deg2Rad(90);
Example:
function SplitFloat(float _f) {
float ffrac=frac(_f);
return [_f-ffrac, ffrac];
}
float f;
foreach f in SplitFloat(1.23)
print f;
In case the implementation does not immediately follow the declaration, the declaration will be called Forward Declaration. The argument list may not be repeated when a forward declarated function is implemented.
Forward declarations are especially useful for class methods to keep the class definition and implementation separated (class method are just functions which can also "see" the current object ("this")).
Please notice that forward declarations are not mandatory; they just may slightly increase execution speed since the function call can be resolved directly, i.e. without emitting an xref node and resolving that first (in case of class methods it does not make any difference).
Example:
function HTMLSpan(String _s, String _class); // "Forward Declaration"
print HTMLSpan("test", "myclass");
function HTMLSpan {
// Implementation, argument list is not repeated
return "<span class=\""+_class+"\">"+_s+"</span>";
}
Functions in other modules can be accessed by prepending the respective module name.
Example:MMyModule.MyFunction();
The return type of a function is not fixed but may depend on the current arguments.
Example:
HashTable values<=#["i"=42, "f"=3.14, "s"="hello, world."];
function vreturn(String _arg) {
if(values.exists(_arg))
return values[_arg];
else
return "err: no such element "+_arg+".";
}
Usually variables in tkscript functions are only created once; they live until the script is unloaded. In practice this means that regular variables are not unset when a function call returns.
Recursive algorithms require that the lifetime of the respective functions variables starts with the function call and ends when the function returns. This is what the local qualifier is used for.
Please notice that the local qualifier in JIT compiled statement blocks has a slightly different meaning, i.e. you cannot mix local JIT variables and local interpreted variables.
Example:
// ---- these two function basically do the same thing:
// typecast an integer to a String and return a volatile (i.e. deletable) object.
//
function ftest2(int k) {
String s=k;
return tcstring(s); // create a copy of "s"
}
function ftest(int k) {
local String s=k;
return deref s;
}
print ftest(2);
print ftest2(3);
Example:
// file: testrecursion.tks
// date: 05Mar2002, updated 21Apr2004
// author: Bastian Spiegel <bs@tkscript.de>
// rem : a recursive implementation of the fibonacci algorithm.
module Main;
function Fib(local int _i) {
if(_i==0)
return 0;
else
if(_i==1)
return 1;
else
return Fib(_i-1)+Fib(_i-2);
}
print "Fib(9)="+Fib(9);
The following functions are provided by the TKS core API:
int 2n (int) - return next in size power of 2
int|float abs (int|float)- return absolute (positive) value
float acos (float) - return arcus cosine
int argb (int, int, int, int) - return packed 32Bit color value
float asin (float) - return arcus sine
float ceil (float) - round up
float cos (int|float) - return cosine
float deg (float) - convert radian to degree
die (String) - output err. Message and abort the application
exit (int) - exit application and return errorcode to the invoking shell
float exp (float) - return e^a
float floor (float) - round down
float frac (float) - return decimal place
String getenv (String) - return value for environment variable
float ln (float) - return logarhythm naturalis
float mathAbsMaxf (float, float) - return the bigger of two absolute values
int mathAbsMaxi (int, int) - return the bigger of two absolute values
float mathAbsMinf (float, float) - return the smaller of two absolute values
int mathAbsMini (int, int) - return the smaller of two absolute values
float mathMaxf (float, float) - return the bigger of two values
int mathMaxi (int, int) - return the bigger of two values
float mathMinf (float, float) - return the smaller of two values
int mathMini (int, int) - return the smaller of two values
float mathPowerf (float, float) - return a raised to the power of b
int mathPoweri (int, int) - return a raised to the power of b
int milliSeconds() - return number of milliseconds since script engine initialization
print (String) - output String to STDOUT. append newline if necessary.
int psystem (String, int _t, String _buf) - execute system command and read/write from stdin/to stdout. _t must be 'r' or 'w'.
putenv (String, String) - set an environment variable
float rad (float) - convert degree to radian
int rgb (int, int, int) - return packed 32Bit color value (alpha=255)
int|float rnd, rand (int|float) - return random number in the given range
float round (float) - round up to next integer
float sin (int|float) - return sine
float sqrt (int|float) - return square root
srand (int) - random seed
stderr (String) - output String to STDERR
stdout (String) - output String to STDOUT
int system (String) - execute system command*
float tan (int|float) - return tangent
String tcchar (int) - convert integer to 1-char ASCII String
float tcfloat (int|float|String) - convert value to floating point representation
int tcint (int|float|String) - convert value to integer representation
Object tcobject (int|float|String) - convert value to Object representation.
create copy of object if it is read-only.
String tcstring (int|float|String) - convert value to String representation,
create copy of string if it is read only
trace (String) - output String to debug console (default is STDOUT). append newline if necessary.
int typeid (<expr>) - print type id (0,1,2,3,4) of expression
String typename (<expr>) - print type name of expression