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.
find(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[, flag]) string, string, boolean 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. If flag=true, it returns null when failed. A opened file will be automatically closed when the return variable is out of scope or set to another object.
csv(a, b, ...) any Displays the string representations of objects with comma between them and a new-line character at the end.
curdir([dir]) string Returns the current directory as string or set the working directory to dir if the optional parameter is set.
eof(f) user Returns true if the current position of file pointer is at the end-of-file; returns false otherwise.
flush(f) user Flushes output buffer of the file handle that is opened for text output.
ftime(fname[, utc]) string, boolean Returns the file timestamp as array. Set utc=true to get the timestamp as Universal Time Coordinate.
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) {...}; ...
isfile(fname) string Returns true if the named file exists or false otherwise.
isdir(dir) string Returns true if dir is a directory or false otherwise.
mkdir(dir) string Makes a new directory.
rmdir(dir) string Removes the directory.
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".
scandir(callback, dir) string, string Scans the directory dir for files and sub-directories. The callback must be the name of a callback function, which get two parameters with the first being the path name and the second the file name.
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, src, m, dst, n) 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);
tmpnam() 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.
format(fmt, item[,...]) string, number or string Returns a string of formated items. The fmt parameter is a C-format string. For exmaple, format( "%02d", 9) results in "09", format("%5.2f", 1.99999) in "2.00", and format("%d-%02d-%02d %02d:%02d", 2000, 1, 1, 12, 30) results in 2000-01-01 12:00.
replace(str, sub, rpl) string, string, string Returns a copy of str with substring sub replaced by rpl. Returns str if sub is not found.
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.
tokenize(str[, del, trim]) string, string, boolean Breaks the string into an array of tokens. Space characters are assumed to be the delimiter if del is not specified. If optional trim parameter may be used to remove space characters on both sides of a token 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.
string(x) any Converts object to string and returns the string.
numbers(s) string Returns true if the string contains only numbers, e.g. 12, 3.0, 0.1e-23.

OS

download(url, fname); strings Download the URL file and save it to fname. Note that your system must have internet explorer installed to use the function.
exec(cmd[, wait]); string, boolean Executes a system command or a program and returns the exit status of the command or program.
fullscreen()   Resize the window created by the window() function to full screen.
getenv(name) string Returns the named environmental variable as string or null. You may use the function to hide the DOS window.
hide()   Hides the console window.
load(fname[,...]) strings Loads dynamic link libraries (DLL).
message(text); string Shows the text in a Windows message box.
millisec() none Returns ticking count of the computer in milli-seconds.
now([utc]) boolean Returns the current time as an array. Set utc=true to get the time as Universal Time Coordinate.
resize(width, height) integers Resize the window created by the window() function.
setenv(name, value) string, string Sets environmental variable.
sendkey(key[,hwnd]) string, user Sends a key-stroke to the foreground window. A key should be a single character or one of these key-names: "Shift", "Ctrl", "Alt" ,"Esc", "Back", "Tab", "Enter", "Space", "PgUp", "PgDn", "End", "Home", "Insert", "delete", "Left", "Up", "Right", "Down", "PrScr", "Scroll", "Pause", "F1", "F2", "F3", "F4", "F5", "F6", "F7", "F8", "F9", "F10", "F11", "F12", "Num", and "Caps". If not one of those, characters in the key string will be send to the window one by one. If the optional variable containing handle to a window is given, the window will be set as the foreground window to get the key stroke.
shellexec(flag, prog[, arg]); boolean, string, string Use the shell execution of Windows to run a program with optional argument and return the process handle of the application. If flag=true, the application window will be shown; otherwise, hidden.
sleep(s) integer Sleeps for s milliseconds.
tmpdir()   Returns the temporal path of OS as string.
terminate(handle) user Brutally terminates the process created by shellexec() function.
timer(ms) integer Starts (ms > 0) or stops (ms = 0) of the window created by the window() function. The window's callback function will receive the "TIMER" message in every ms milliseconds.
title(text); string Set the title bar text of the window created by window() function.
window(width, height, callback[, title]) integer, integer, string, 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).
window();   Finds all visible windows and display their registered name and title-bar text.
window(name); string Finds the window with the specified registration name and returns the handle. If failed, finds the window whose title bar text includes the name.

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.

Miscellaneous

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.
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
global:   any Access global variable.
new   Class name Returns a new object of the class.
!   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 any 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.

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.func(...) Calls primitive function registered for the user object or calls script function defined for a class.
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

Deprecated Operators

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.
o->var Returns lass variable.
o->func(...) Calls class function.