#### ``` 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.

#### ``` angle = acos(x)```

Returns the arc cosine of x in the range 0 to pi.

#### ``` 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"]`

#### ``` float = asin(x)```

Returns the arc sine of x in the range -pi/2 to pi/2.

#### ``` value = assign(struct, key, value)```

Sets the element of struct identified by key to value, ignoring any super struct. Returns value.

#### ``` angle = atan(x)```

Returns the arc tangent of x in the range -pi/2 to pi/2.

#### ``` 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).

#### ``` x = cos(angle)```

Returns the cosine of angle (a float interpreted in radians).

#### ``` 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(), "", "!")

;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)
!

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();```

The functions parse and scope are described below.

#### ``` 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.

#### ``` int = eq(obj1, obj2)```

Returns 1 (one) if obj1 and obj2 are the same object, else 0 (zero).

#### ``` 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.

#### ``` float = exp(x)```

Returns the exponential function of x.

#### ``` 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.

If seps is not given the string " \t\n" is assumed.

#### ``` 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.

For example:

```forall (token in gettokens(currentfile()))
printf("<%s>", token)
;   This    is my line    of data.
printf("\n");```

when run will print:

`<This><is><my><line><of><data.>`

Whereas:

```forall (token in gettokens(currentfile(), ':', "*"))
printf("<%s>", token)
;:abc::def:ghi:*
printf("\n");```

when run will print:

`<><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.

#### ``` float = log(x)```

Returns the natural logarithm of x (a float).

#### ``` float = log10(x)```

Returns the log base 10 of x (a float).

#### ``` 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;

and if it is anything else, one 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.

For example:

```static x = 123;
parse("static x = 456;", scope());
printf("x = %d\n", x);```

When run will print:

`x = 456`

Whereas:

```static x = 123;
parse("static x = 456;");
printf("x = %d\n", x);```

When run will print:

`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"``` .

#### ``` float = pow(x, y)```

Returns x^y where both x and y are floats.

#### ``` 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.

#### ``` any = push(array, any)```

Appends any to array, increasing its length in the process. Returns any.

#### ``` 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.

#### ``` reclaim()```

Force a garbage collection to occur.

#### ``` 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.

#### ``` remove(string)```

Deletes the file whose name is given in string.

#### ``` 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"]`

#### ``` x = sin(angle)```

Returns the sine of angle (a float interpreted in radians).

#### ``` 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.

For example,

`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.

For example:

`sprintf("%08X <%4s> <%-4s>", 123, "ab", "cd")`

will produce the string:

`0000007B <  ab> <cd  >`

and

`sprintf("%0*X", 4, 123)`

will produce the string:

`007B`

#### ``` x = sqrt(float)```

Returns the square root of float.

#### ``` 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()`

returns a new empty 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).

#### ``` x = tan(angle)```

Returns the tangent of angle (a float interpreted in radians).

#### ``` 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.

year The int year.

wday The day since Sunday (0..6)

yday Days since 1st Jan.

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 = tochar(int)```

Returns a one character string made from the character code specified by int.

#### ``` int = toint(string)```

Returns the character code of the first character of string.

#### ``` 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.