Z-Script Standard Library

Many functions with array arguments require that the arrays contain only numbers and be indexed sequentially by integer e.g.,

a = [1, 2, 3.5, 4.2, 5];

Math functions and most operators also require that the arrays contain only numbers (integer or real).

Array

Function Parameter Type Remark
array(size) integer Returns array with a hash table of the specified size. Use this function when an array is expected to hold a large number of items. The has table An array created with [..] is about the number of key-values in []; and it is not efficient to add large number of new items to such an array.
exist(arr, key) array, string/integer Returns true if the array has the key or false otherwise.
size(arr) array Returns the number of key-values in the array.
clear(arr[,...]) array Clears key-value pairs in the array.
keys(arr) array Returns a new array containing keys of the input array.
remove(arr, key[,...]) array, integer or string Removes the values with the keys from the array.

IO

open(filename, mode) string, string Opens the file and returns the handle as user object or null if failed. If filename is "stdout", "stderr", or "stdin", the file handle will be assigned to one of those standard C file handles and the mode argument has no effect. The most frequently used modes include "r", "w", and "a" for reading, writing, and appending text respectively; and "rb" and "wb" for binary reading and writing.
close(f) user Closes the file and flushes any pending contents to the file.
csv(a, b, ...) any Displays the string representations of objects with comma between them and a new-line character at the end.
eof(f) user Returns true if the current position of file pointer is at the end-of-file; returns false otherwise.
exist(fname) string Returns true if the named file exists or false otherwise.
flush(f) user Flushes output buffer of the file handle that is opened for text output.
format(fmt, v) string, number Returns a string of formated number. The fmt parameter is a C-format string. For exmaple, format( "%02d", 9) results in "09" and format("%5.2f", 1.99999) in "2.00".
input(msg) string Displays the message, waits for user input, and return the input as string. Your may use the function to write a simple user interface, e.g., year=integer(input("Year: ")); if (year > 2000) {...}; ...
read(f) user Reads a lines from the file and return a string. The length of a line in the file should be less then 8192.
read(f, ptr, nbyte) user, user, integer Reads nbyte of binary data from the file to the memory pointed to by ptr. Returns the actual bytes read.
read(f, type) user, string Reads and returns a binary number. The type parameter may be "char", "uchar", "short", "ushort", "int", "uint", "int64", "float", or "double".
write(f, obj) user, any Writes the string from of obj to the file.
write(f, ptr, nbyte) user, user, integer Writes to the file n-bytes of binary data pointed to by ptr.
write(f, num, type) user, number, string Writes a binary number. The number will be converted to integer or real according to the type parameter, which may be "char", "uchar", "short", "ushort", "int", "uint", "int64", "float", or "double".
print(a, b, ...) any The same as csv() but without the comma and new-line character.
revb(ptr, n, esize) user, integer, integer Reverses data bytes of the pointer. n is the number of data and esize is the datum size in byte. Use the function to deal with Big-endian/Little-endian problems.
bits2u(bits, dst, n, src, m) integer, user, integer, user, integer Unpacks bit-packed integer in src of m bytes to unsigned integer in dst of length n. The function requires m*8/bits >= n. It is common to pack large grid datasets in variable bits, e.g., ECMWF's data in GRIB format.
seek(f, offset, flag) user, integer, string Moves the file pointer by the offset according to the flag: "set" means offset from the start, "end" means from the end, and "cur" means from the current position.
seek(f, str) user, string Finds the string in the file handler and returns the file pointer position at the end of the string if successful; otherwise returns 0. As an example, your may use seek(f, "GRIB") to find the start fo the next record in a GRIB format file.
tell(f) file Returns the current position of the file as integer. This script use IO functions to get the file size:
f = open(fname, "rb");
seef(f, 0, "end");
fsize = tell(f);
tmpname() none Returns a temporal file name.

String

size(s) string Returns the string length.
find(s, substr, start) string, string, integer Returns the index of the sub-string. If start < 0, finds the last substring. For exmaple, find("Are you OK?", "OK") results in 8.
replace(str, sub, rpl) string, string, string Returns a copy of str with substring sub replaced by rpl. For exmaple, replace("c:/mydir/my.txt", "c:", "d:") results in "d:/mydir/my.txt".
substr(s, start, n) string, integer, integer Returns the sub-string with n-number of characters from the start. If n <= 0, get the substring from the start to the end. For exmaple, substr("19990201", 4, 2) results in "02".
tolower(s) string Converts the string to lower case and returns a string.
toupper(s) string Converts the string to upper case and returns a string.
trim(s) string Removes leading and trailing spaces and returns a string. Returns null if the string contains only spaces.
string(x) any Converts object to string and returns the string.
base64(ptr, n) user, integer Encodes n-bytes binrary data pointed to by ptr to base64 string and returns the string. Use the function to pack binary data, e.g., image, in text for network data transfermation.
base64(ptr, n, s) user, integer, string Decodes base64 string to n-bytes binrary data pointed to by ptr and returns the actual converted bytes.
mbs2utf(s) string Returns a UTF-8 string converted from the multibyte string. The function is useful for XML applicaiotns.
utf2mbs(s) string Returns a multibyte string converted from the UTF-8 string.
integer(s) string/real Converts string or real to integer and returns a integer.
real(s) string/integer Converts string to real and returns returns a real.
onlyblanks(s) string Returns true if the string contains only space characters.
onlynumbers(s) string Returns true if the string contains only numbers, e.g. 12, 3.0, 0.1e-23.

OS

hide()   Hides the console window.
getenv(name) string Returns the named environmental variable as string or null. You may use the function to hide the DOS window.
load(fname[,...]) strings Loads dynamic link libraries first (fname should have a dll extension); or loads and executes Z-Script code in the file (fname should have a zs extension).
millisec() none Returns ticking count of the computer in milli-seconds.
now() none Returns an array containing ["year"], ["month"], ["day"], ["hour"], ["minute"], ["second"], ["time"]. The time is the total seconds reference to a given year and time.
sleep(s) integer Sleeps for s milliseconds.
timer(ms) integer Generate a TIMER event for window in every ms microseconds.
window(width, height, callback) integer, integer, string Creates window of given width and height. The callback function should handle events of the window, which will call the function with eight arguments: (1) window's handle (raw pointer), window message (string corresponding to message ID, i.e., "CREATE", "COMMAND", "SIZE", "PAINT", "KEYUP", "KEYDOW", "LBUTTONUP", "LBUTTONDOWN", "LBUTTONDBLCLK", "MOUSEMOVE", "RBUTTONUP", "RBUTTONDOWN", "RBUTTONDBLCLK", "SETCURSOR", and "TIMER" ), message WPARAM (integer), the low-word of WPARAM (integer), the high-word of WPARAM (integer), message LPARAM (integer), the low-word of LPARAM (integer), and the high-word of LPARAM (integer).
exec(cmd); string Executes a system command.
tmppath()   Returns the temporal path of OS as string.
mydir()   Returns the current directory as string.
setdir(dir) string Sets the current working directory to the specified directory.

Thread

thread(name) string Returns a thread that runs the named script function.
suspend(thr) user Suspends the thread.
resume(thr) user Resume the thread.

Type Checking

isnull(obj) any Checks if the object is null and returns true or false.
isinteger(obj) any Checks if the object is integer and returns true or false.
isreal(obj) any Checks if the object is real and returns true or false.
isnumber(obj) any Checks if the object is integer or real, and returns true or false.
isstring(obj) any Checks if the object is string and returns true or false.
isarray(obj) any Checks if the object is array and returns true or false.
isuser(obj) any Checks if the object is user type and returns true or false.
isclass(obj) any Checks if the object is class type and returns true or false.

others

assert(expr[,...]) any Checks the assert condition, throws exception if the predicate is false.
error(msg) string Displays the error message and then exits program.
exec(cmd) string Executes the command and returns the return-code of the command.
cal2jul(year, month, day,[hour, minute, second]) numbers Returns the Julian day number converted from the calendar date. The reference date is 1-Jan-1900.
jul2cal(jul) number Returns an array containing ["year"], ["month"], ["day"], ["hour"], ["minute"], and ["second"] converted from the Julian day number.
getarg(n) [number|string] Returns the nth command line argument or if n is string, returns the value for the key that has been passed to Z-Script as key=value.
func(name) string Returns a user object containing pointer to the named script function.
call(f[,...]) user Calls the function with optional numbers of paremeters. Use func(name) to get the pointer to the function.
eval(script[, trace]) string, boolean Evaluates script code in the string as if the code is loaded from a file. If trace= true, variables values will be displayed.
trace(show) boolean, user Shows variable values and waits for user's interaction (press ENTER key to continue) if show=true.

Math

cos(v) array, integer, real Returns real of cos(v). If the operand is array, operation is element-wise and the array must be indexed sequentially by integer and contain only numbers.
cosh(v) array, integer, real Returns real of cosh(v). See cos(v) requirement for array.
acos(v) array, integer, real Returns real of acos(v). See cos(v) requirement for array.
sin(v) array, integer, real Returns real of sin(v). See cos(v) requirement for array.
sinh(v) array, integer, real Returns real of sinh(v). See cos(v) requirement for array.
asin(v) array, integer, real Returns real of asin(v). See cos(v) requirement for array.
tan(v) array, integer, real Returns real of tan(v). See cos(v) requirement for array.
tanh(v) array, integer, real Returns real of tanh(v). See cos(v) requirement for array.
atan(v) array, integer, real Returns real of atan(v). See cos(v) requirement for array.
atan2(v1, v2) array, integer, real Returns real of atan2(v1, v2). See cos(v) requirement for array.
sqrt(v) array, integer, real Returns real of sqrt(v). (no check for v < 0) See cos(v) requirement for array.
exp(v) array, integer, real Returns real of exp(v). See cos(v) requirement for array.
log(v) array, integer, real Returns real of log(v). (no check for v <= 0) See cos(v) requirement for array.
log10(v) array, integer, real Returns real of log10(v). (no check for v <= 0) See cos(v) requirement for array.
ceil(v) array, integer, real Returns real of ceil(v). See cos(v) requirement for array.
floor(v) array, integer, real Returns real of floor(v). See cos(v) requirement for array.
abs(v) array, integer, real Returns real of abs(v). See cos(v) requirement for array.
pow(a, b) array, integer, real Returns real of pow(a, b). See cos(v) requirement for array.

Operator Precedence

Precedence Operators
0 ., ->
1 ++, --, !, ~, unary-
2 *, /, %
3 -, +
4 >>, <<
5 <, <=, >, >=
6 ==, !=
7 ^, &, |
8 &&, ||
9 =, -=, +=, *=, /=, %=, |=, &=, ^=, <<=, >>=,

Unary Operators

Operator Left Operand Right Operand Remark
~   array, integer Returns the bitwise compliment of the integer. If the operand is array, operation is element-wise and the array must be indexed sequentially by integer and contain only integers.
!   array, number Returns 1 if the number is 0; otherwise returns 0.If the operand is array, operation is element-wise and the array must be indexed sequentially by integer and contain only numbers.
-   array, number Returns the negative of the original. See !-operator requirement for array.
++ array, number   Increase the number by 1. See !-operator requirement for array.
-- array, number   Decrease the number by 1. See !-operator requirement for array.

Binary Operators

Operator Left Operand Right Operand Remark
+, -, *, /, % array, number array, number Returns a real if one of them is real; otherwise returns a integer. If the operand is array, the array must be a pure integer indexed array containing only numbers.
+ string string Appends the right to the left and returns a new string.
>> integer integer Bit shift of the left to the right by the right value.
<< integer integer Bit shift of the left to the left by the right value.
| integer integer Returns the bitwise-or of the two operands.
& integer integer Returns the bitwise-and of the two operands
^ integer integer Returns the bitwise-xor of the two operands.
+=, -=, *=, /=, %= array, number array, number The efficient version of +, -, *, /, and %.
<<=, >>=, |=, &=, ^= integer integer The efficient version of <<, >>, |, & and ^.
== any any Equal comparison. For numbers, returns 1 if the numbers are equal; otherwise returns 0. For string, comparison is character by character; and a zero-length string is treated as null. For array, comparison is element-wise. For user object, if its operator function is not set, companion is strict pointer comparison.
!= any any Refer to ==
>, >=, <. <= array, number, string array, number, string Refer to ==
&&, || any any Logical and/or operation. For number, non-zero is true; otherwise is false. For string and array, zero-length means false; otherwise means true. The null is false. A valid class or user object always means true.
= variable name any Assign the right to the left.

Array Access Operators

Operator Remark
array[key...] Returns the values for the keys, which may be integer or string.
array.key Returns the value for the key, which must be string.
user[key...] For a user object, calls user defined __get or __set primitive functions with the first argument being user, the second argument being the first index, and so on. For the __set function, the last argument is the object to be assigned to user

Class Access Operators

Operator Remark
new ClassName Returns a new object of the class.
o->var Returns lass variable.
o->func(...) Calls class function.

Special function call Operator

Operator Remark
caller:func(...) Caller func with the first argument being the caller. If the caller is a user object, a primitive function must be defined for that type of object with the type ID attached to func function name.