float|int = abs(float|int)
Returns the absolute value of its argument. The result is an int if the argument is an int, a float if it is a float.
mem = alloc(nwords [, wordz])
Returns a new mem object referring to nwords (an int) of newly allocated and cleared memory. Each word is either 1, 2, or 4 bytes as specified by wordz (an int, default 1). Indexing of mem objects performs the obvious operations, and thus pointers work too.
array = array(any...)
Returns an array formed from all the arguments. For example:
array()
will return a new empty array; and
array(1, 2, "a string")
will return a new array with three elements, 1, 2, and "the string".
This is the run-time equivalent of the array literal. Thus the following two expressions are equivalent:
$array(1, 2, "a string")
[array 1, 2, "a string"]
value = assign(struct, key, value)
Sets the element of struct identified by key to value, ignoring any super struct. Returns value.
angle = atan2(y, x)
Returns the angle from the origin to the rectangular coordinates x, y (floats ) in the range -pi to pi.
return = call(func, args)
Calls the function func with arguments taken from the array args. Returns the return value of the function.
This is often used to pass on an unknown argument list. For example:
static db() { auto vargs; if (debug) return call(printf, vargs); }
new = copy(old)
Returns a copy of old. If old is an intrinsically atomic type such as an int or string, the new will be the same object as the old. But if old is an array, set, or struct, a copy will be returned. The copy will be a new non-atomic object (even if old was atomic) which will contain exactly the same objects as old and will be equal to it (that is ==). If old is a struct with a super struct, new will have the same super (exactly the same super, not a copy of it).
file = currentfile()
Returns the file associated with the innermost parsing context, or NULL if there is no module being parsed.
This function can be used to include data in a program source file which is out-of-band with respect to the normal parse stream. But to do this it is necessary to know up to what character in the file in question the parser has consumed.
In general: after having parsed any simple statement the parser will have consumed up to and including the terminating semicolon, and no more. Also, after having parsed a compound statement the parser will have consumed up to and including the terminating close brace and no more. For example:
static help = gettokens(currentfile(), "", "!")[0] ;This is the text of the help message. It follows exactly after the ; because that is exactly up to where the parser will have consumed. We are using the gettokens() function (as described below) to read the text. ! static otherVariable = "etc...";
This function can also be used to parse the rest of a module within an error catcher. For example:
try parse(currentfile(), scope()) onerror printf("That didn't work, but never mind.\n"); static this = that; etc();
del(struct, key)
Deletes the element of struct identified by key. Any super structs are ignored. Returns NULL. For example:
static s = [struct a = 1, b = 2, c = 3]; static v, k; forall (v, k in s) printf("%s=%d\n", k, v); del(s, "b"); printf("\n"); forall (v, k in s) printf("%s=%d\n", k, v);
When run would produce (possibly in some other order):
a=1 c=3 b=2 a=1 c=3
int = eof([file])
Returns non-zero if end of file has been read on file . If file is not given the current value of stdin in the current scope is used.
eventloop()
Enters an internal event loop and never returns (but can be broken out of with an error). The exact nature of the event loop is system specific. Some dynamically loaded modules require an event loop for their operation.
exit([string|int|NULL])
Causes the interpreter to finish execution and exit. If no parameter, the empty string or NULL is passed the exit status is zero. If an integer is passed that is the exit status. If a non-empty string is passed then that string is printed to the interpreter's standard error output and an exit status of one used. This is implementation dependent and may be replaced by a more general exception mechanism. Avoid.
array = explode(string)
Returns an array containing each of the integer character codes of the characters in string.
fail(string)
Causes an error to be raised with the message string associated with it. See the section of error handling in the try statement above. For example:
if (qf > 255) fail(sprintf("Q factor %d is too large", qf));
value = fetch(struct, key)
Returns the value from struct associated with key, ignoring any super structs. Returns NULL is key is not an element of struct.
value = float(x)
Returns a floating point interpretation of x, or 0.0 if no reasonable interpretation exists. x should be an int, a float, or a string, else 0.0 will be returned.
file = fopen(name [, mode])
Opens the named file for reading or writing according to
mode
and returns a file object that may be used to perform I/O on the file.
Mode
is the same as in C and is passed directly to the C library
fopen
function. If mode is not specified
"r"
is assumed.
fprintf(file, fmt, args...)
Formats a string based on fmt and args as per sprintf (below) and outputs the result to file. See sprintf. Changes to ICI's printf have made fprintf redundant and it may be removed in future versions of the interpreter. Avoid.
string = getchar([file])
Reads a single character from file and returns it as a string. Returns NULL upon end of file. If file is not given the current value of stdin in the current scope is used.
string = getfile([file])
Reads all remaining data from file and returns it as a string. Returns an empty string upon end of file. If file is not given the current value of stdin in the current scope is used.
string = getline([file])
Reads a line of text from file and returns it as a string. Any end-of-line marker is removed. Returns NULL upon end of file. If file is not given the current value of stdin in the current scope is used.
string = gettoken([file [, seps]])
Read a token (that is, a string) from file.
Seps must be a string. It is interpreted as a set of characters which do not from part of the token. Any leading sequence of these characters is first skipped. Then a sequence of characters not in seps is gathered until end of file or a character from seps is found. This terminating character is not consumed. The gathered string is returned, or NULL if end of file was encountered before any token was gathered.
If file is not given the current value of stdin in the current scope is used.
array = gettokens([file [, seps [, terms]]])
Read tokens (that is, strings) from file. The tokens are character sequences separated by seps and terminated by terms. Returns an array of strings, NULL on end of file.
If seps is a string, it is interpreted as a set of characters, any sequence of which will separate one token from the next. In this case leading and trailing separators in the input stream are discarded.
If seps is an integer it is interpreted as a character code. Tokens are taken to be sequences of characters separated by exactly one of that character.
Terms must be a string. It is interpreted as a set of characters, any one of which will terminate the gathering of tokens. The character which terminated the gathering will be consumed.
If file is not given the current value of stdin in the current scope will be used.
If seps is not given the string " \t" is assumed.
If terms is not given the string "\n" is assumed.
forall (token in gettokens(currentfile())) printf("<%s>", token) ; This is my line of data. printf("\n");
<This><is><my><line><of><data.>
forall (token in gettokens(currentfile(), ':', "*")) printf("<%s>", token) ;:abc::def:ghi:* printf("\n");
<><abc><><def><ghi><>
string = gsub(string, string|regexp, string)
gsub performs text substitution using regular expressions. It takes the first parameter, matches it against the second parameter and then replaces the matched portion of the string with the third parameter. If the second parameter is a string it is converted to a regular expression as if the regexp function had been called. Gsub does the replacement multiple times to replace all occurrances of the pattern. It returns the new string formed by the replacement. If there is no match this is original string. The replacement string may contain the special sequence "\&" which is replaced by the string that matched the regular expression. Parenthesized portions of the regular expression may be matched by using \ n where n is a decimal digit.
string = implode(array)
Returns a string formed from the concatenation of elements of array. Integers in the array will be interpreted as character codes; strings in the array will be included in the concatenation directly. Other types are ignored.
struct = include(string [, scope])
Parses the code contained in the file named by the string into the scope. If scope is not passed the current scope is used. Include always returns the scope into which the code was parsed. The file is opened by calling the current definition of the ICI fopen() function so path searching can be implemented by overriding that function.
value = int(any)
Returns an integer interpretation of x, or 0 if no reasonable interpretation exists. x should be an int, a float, or a string, else 0 will be returned.
subpart = interval(str_or_array, start [, length])
Returns a sub-interval of str_or_array, which may be either a string or an array.
If start (an integer) is positive the sub-interval starts at that offset (offset 0 is the first element). If start is negative the sub-interval starts that many elements from the end of the string (offset -1 is the last element, -2 the second last etc).
If length is absent, all the elements from the start are included in the interval. Otherwise that many elements are included (or till the end, whichever is smaller).
For example, the last character in a string can be accessed with:
last = interval(str, -1);
And the first three elements of an array with:
first3 = interval(ary, 0, 3);
isatom(any)
Return 1 (one) if any is an atomic (read-only) object, else 0 (zero). Note that integers, floats and strings are always atomic.
array = keys(struct)
Returns an array of all the keys from struct. The order is not predictable, but is repeatable if no elements are added or deleted from the struct between calls and is the same order as taken by a forall loop.
mem = mem(start, nwords [, wordz])
Returns a memory object which refers to a particular area of memory in the ICI interpreter's address space. Note that this is a highly dangerous operation. Many implementations will not include this function or restrict its use. It is designed for diagnostics, embedded systems and controllers. See the alloc function above.
file = mopen(mem [, mode])
Returns a file, which when read will fetch successive bytes from the given memory object. The memory object must have an access size of one (see
alloc
and
mem
above). The file is read-only and the mode, if passed, must be one of
"r"
or
"rb"
.
int = nels(any)
Returns the number of elements in any. The exact meaning depends on the type of any. If any is an:
array the length of the array is returned; if it is a
struct the number of key/value pairs is returned; if it is a
set the number of elements is returned; if it is a
string the number of characters is returned; and if it is a
mem the number of words (either 1, 2 or 4 byte quantities) is returned;
number = num(x)
If x is an int or float, it is returned directly. If x is a string it will be converted to an int or float depending on its appearance; applying octal and hex interpretations according to the normal ICI source parsing conventions. (That is, if it starts with a 0x it will be interpreted as a hex number, else if it starts with a 0 it will be interpreted as an octal number, else it will be interpreted as a decimal number.)
If x can not be interpreted as a number the error %s is not a number is generated.
scope = parse(source [, scope])
Parses source in a new variable scope, or, if scope (a struct) is supplied, in that scope. Source may either be a file or a string, and in either case it is the source of text for the parse. If the parse is successful, the variables scope structure of the sub-module is returned. If an explicit scope was supplied this will be that structure.
If scope is not supplied a new struct is created for the auto variables. This structure in turn is given a new structure as its super struct for the static variables. Finally, this structure's super is set to the current static variables. Thus the static variables of the current module form the externs of the sub-module.
If scope is supplied it is used directly as the scope for the sub-module. Thus the base structure will be the struct for autos, its super will be the struct for statics etc.
static x = 123; parse("static x = 456;", scope()); printf("x = %d\n", x);
x = 456
static x = 123; parse("static x = 456;"); printf("x = %d\n", x);
x = 123
Note that while the following will work:
parse(fopen("my-module.ici"));
It is preferable in a large program to use:
parse(file = fopen("my-module.ici")); close(file);
In the first case the file will eventually be closed by garbage collection, but exactly when this will happen is unpredictable. The underlying system may only allow a limited number of simultaneous open files. Thus if the program continues to open files in this fashion a system limit may be reached before the unused files are garbage collected.
any = pop(array)
Returns the last element of array and reduces the length of array by one. If the array was empty to start with, NULL is returned.
file = popen(string, [flags])
Executes a new process, specified as a shell command line as for the
system
function, and returns a file that either reads or writes to the standard input or output of the process according to
mode
. If mode is
"r"
the reading from the file reads from the standard output of the process. If mode is
"w"
writing to the file writes to the standard input of the process. If mode is not speicified it defaults to
"r"
.
printf([file,] fmt, args...)
Formats a string based on fmt and args as per sprintf (below) and outputs the result to the file or to the current value of the stdout variable in the current scope if the first parameter is not a file. The current stdout must be a file. See sprintf.
put(string [, file])
Outputs string to file . If file is not passed the current value of stdout in the current scope is used.
int = rand([seed])
Returns an pseudo random integer in the range 0..0x7FFF. If seed (an int) is supplied the random number generator is first seeded with that number. The sequence is predictable based on a given seed.
re = regexp(string [, int])
Returns a compiled regular expression derived from string This is the method of generating regular expressions at run-time, as opposed to the direct lexical form. For example, the following three expressions are similar:
str ~ #*\.c# str ~ regexp("*\\.c"); str ~ $regexp("*\\.c");
except that the middle form computes the regular expression each time it is executed. Note that when a regular expression includes a # character the regexp function must be used, as the direct lexical form has no method of escaping a #.
The optional second parameter is a bit-set that controls various aspects of the compiled regular expression's behaviour. This value is passed directly to the PCRE package's regular expression compilation function. Presently no symbolic names are defined for the possible values and interested parties are directed to the PCRE documention included with the ICI source code.
Note that regular expressions are intrinsically atomic. Also note that non-equal strings may sometimes compile to the same regular expression.
re = regexpi(string [, int])
Returns a compiled regular expression derived from string that is case-insensitive. I.e., the regexp will match a string regardless of the case of alphabetic characters. Literal regular expressions to perform case-insensitive matching may be constructed using the special PCRE notation for such purposes, see See The settings of PCRE_CASELESS, PCRE_MULTILINE, PCRE_DOTALL, and PCRE_EXTENDED can be changed from within the pattern by a sequence of Perl option letters enclosed between "(?" and ")". The option letters are.
current = scope([replacement])
Returns the current scope structure. This is a struct whose base element holds the auto variables, the super of that hold the statics, the super of that holds the externs etc. Note that this is a real reference to the current scope structure. Changing, adding and deleting elements of these structures will affect the values and presence of variables in the current scope.
If a replacement is given, that struct replaces the current scope structure, with the obvious implications. This should clearly be used with caution. Replacing the current scope with a structure which has no reference to the standard functions also has the obvious effect.
int = seek(file, int, int)
Set the input/output position for a file and returns the new I/O position or -1 if an error ocurred. The arguments are the same as for the C library's fseek function. If the file object does not support setting the I/O position or the seek operation fails an error is raised.
set = set(any...)
Returns a set formed from all the arguments. For example:
set()
will return a new empty set; and
set(1, 2, "a string")
will return a new set with three elements, 1, 2, and "the string".
This is the run-time equivalent of the set literal. Thus the following two expressions are equivalent:
$set(1, 2, "a string")
[set 1, 2, "a string"]
file = sopen(string [, mode])
Returns a file, which when read will fetch successive characters from the given string. The file is read-only and the mode, if passed, must be one of
"r"
or
"rb"
.
Files are, in general, system dependent. This is the only standard routine which opens a file. But on systems that support byte stream files, the function fopen will be set to the most appropriate method of opening a file for general use. The interpretation of mode is largely system dependent, but the strings "r", "w", and "rw" should be used for read, write, and read-write file access respectively.
sort(array, func)
Sort the content of the array using the heap sort algorithm with func as the comparison function. The comparison function is called with two elements of the array as parameters, a and b . If a is equal to b the function should return zero. If a is less than b , -1, and if a is greater than b , 1.
static cmp(a, b)
{
if (a == b)
return 0;
if (a < b)
return -1;
return 1;
}
static a = array(1, 3, 2);
sort(a, cmp);
string = sprintf(fmt, args...)
Return a formatted string based on fmt (a string) and args. Most of the usual % format escapes of ANSI C printf are supported. In particular; the integer format letters diouxXc are supported, but if a float is provided it will be converted to an int. The floating point format letters feEgG are supported, but if the argument is an int it will be converted to a float. The string format letter, s is supported and requires a string. Finally the % format to get a single % works.
The flags, precision, and field width options are supported. The indirect field width and precision options with * also work and the corresponding argument must be an int.
sprintf("%08X <%4s> <%-4s>", 123, "ab", "cd")
0000007B < ab> <cd >
sprintf("%0*X", 4, 123)
007B
string = string(any)
Returns a short textual representation of any. If any is an int or float it is converted as if by a %d or %g format. If it is a string it is returned directly. Any other type will returns its type name surrounded by angle brackets, as in <struct>.
struct = struct([super,] key, value...)
Returns a new structure. This is the run-time equivalent of the struct literal. If there are an odd number of arguments the first is used as the super of the new struct; it must be a struct. The remaining pairs of arguments are treated as key and value pairs to initialise the structure with; they may be of any type. For example:
struct()
struct(anotherStruct)
returns a new empty struct which has anotherStruct as its super;
struct("a", 1, "b", 2)
returns a new struct which has two entries a and b with the values 1 and 2; and
struct(anotherStruct, "a", 1, "b", 2)
returns a new struct which has two entries a and b with the values 1 and 2 and a super of anotherStruct.
Note that the super of the new struct is set after the assignments of the new elements have been made. Thus the initial elements given as arguments will not affect values in any super struct.
The following two expressions are equivalent:
$struct(anotherStruct, "a", 1, "b", 2)
[struct:anotherStruct, a = 1, b = 2]
string = sub(string, string|regexp, string)
Sub performs text substitution using regular expressions. It takes the first parameter, matches it against the second parameter and then replaces the matched portion of the string with the third parameter. If the second parameter is a string it is converted to a regular expression as if the regexp function had been called. Sub does the replacement once (unlike gsub). It returns the new string formed by the replacement. If there is no match this is original string. The replacement string may contain the special sequence "\&" which is replaced by the string that matched the regular expression. Parenthesized portions of the regular expression may be matched by using \ n where n is a decimal digit.
current = super(struct [, replacement])
Returns the current super struct of struct, and, if replacement is supplied, sets it to a new value. If replacement is NULL any current super struct reference is cleared (that is, after this struct will have no super).
foat = now()
Returns the current time expressed as a signed float time in seconds since 0:00, 1st Jan 2000 UTC.
float|struct = calendar(struct|float)
Converts between calendar time and arithmetic time. An arithmetic time is expressed as a signed float time in seconds since 0:00, 1st Jan 2000 UTC. The calendar time is expressed as a structure with fields revealing the local (including current daylight saving adjustment) calendar date and time. Fields in the calendar structure are:
second The float number of seconds after the minute.
minute The int number of minutes after the hour.
hour The int number of hours since midnight.
day The day of the month (1..31).
month The int month number, Jan is 0.
wday The day since Sunday (0..6)
When converting from a local calendar time to an arithmetic time, the fields sec, min, hour, mday, mon, year are used. They need not be restricted to their nomal ranges.
string = typeof(any)
Returns the type name (a string) of any. See the section on types above for the possible type names.
array = vstack()
Returns a representation of the call stack of the current program at the time of the call. It can be used to perform stack tracebacks and related debugging operations. The result is an array of structures, each of which is a variable scope (see scope ) structure of succesively deeper nestings of the current function nesting.
event = waitfor(event...)
Blocks (waits) until an event indicated by any of its arguments occurs, then returns that argument. The interpretation of an event depends on the nature of each argument. A file argument is triggered when input is available on the file. A float argument waits for that many seconds to expire, an int for that many millisecond (they then return 0, not the argument given). Other interpretations are implementation dependent. Where several events occur simultaneously, the first as listed in the arguments will be returned.
Note that in some implementations some file types may always appear ready for input, despite the fact that they are not.