- Introduction
- abs
- any
- back
- bal
- center
- char
- classof
- clear
- coact
- cocopy
- cofail
- collect
- copy
- cset
- delay
- delete
- detab
- display
- entab
- errorclear
- exit
- fatalerr
- find
- get
- iand
- icom
- image
- insert
- integer
- ior
- is
- ishift
- ixor
- key
- keyof
- keyval
- left
- list
- many
- map
- match
- max
- member
- min
- move
- numeric
- ord
- pop
- pos
- proc
- pull
- push
- put
- real
- repl
- reverse
- right
- runerr
- seq
- serial
- set
- sort
- sortf
- string
- syserr
- system
- tab
- table
- text
- trim
- type
- uchar
- ucs
- upto
- weakref
- weakrefval

This page lists Object Icon's builtin functions.

`abs (N) : N`

-- compute absolute value

Produces the absolute value of `N`

.

`any (c,s,i1,i2) : i3`

-- locate initial character

Succeeds and produces `i1 + 1`

if `s[i1]`

is in `c`

and `i2 > i1`

, but fails otherwise.

Defaults:

`s`

`&subject`

`i1`

`&pos`

if`s`

defaulted, otherwise`1`

`i2`

`0`

See also: `many()`

and `match()`

`back (x1) : x2`

-- reverse order generation

Generate the elements of `x1`

in reverse order.

`bal (c1,c2,c3,s,i1,i2) : i3,i4,...,in`

-- locate balanced characters

Generates the sequence of integer positions in `s`

preceding a character of `c1`

in `s[i1:i2]`

that is balanced with respect to the characters of `c2`

and `c3`

, but fails if there is no such position.

Defaults:

`c1`

`&cset`

`c2`

`'('`

`c3`

`')'`

`s`

`&subject`

`i1`

`&pos`

if`s`

defaulted, otherwise`1`

`i2`

`0`

See also: `find()`

and `upto()`

`center (s1,i,s2) : s3`

-- position string at center

Produces a string of size `i`

in which `s1`

is centered, with `s2`

used for padding at left and right as necessary.

Defaults:

`i`

`1`

`s2`

`" "`

(blank)

See also: `left()`

and `right()`

`char (i) : s`

-- produce character

Produces a string of length `1`

consisting of the character whose internal representation is `i`

. Fails if `i`

is not a valid character number.

See also: `ord()`

`classof (o) : cl`

-- return the class of object `o`

If `o`

is a class or an object, the corresponding class is returned. If `o`

is a record or a constructor, then the corresponding constructor is returned.

`clear (X) : X`

-- clear structure

Clears all the elements from `X`

which must be a set, list or table. Produces `X`

.

`coact (value,ce,activator) : x`

-- general co-expression transmission

This function is like the `@`

operator, but more flexible. It transmits `value`

to `ce`

, optionally setting `ce`

's activator. If `activator`

is `&null`

, then the activator of `ce`

is left unchanged.

Defaults:

`ce`

`&source`

`cocopy (ce) : ce`

-- refresh with copy

Return a refreshed copy of `ce`

, but with a copied set of local variables.

`cofail (ce,activator) : x`

-- transmit failure to co-expression

This function behaves like `coact`

, except that rather than transmitting a value, failure is transmitted instead.

Defaults:

`ce`

`&source`

`collect () : n`

-- perform garbage collection

`copy (x1) : x2`

-- copy value

Produces a copy of `x1`

if `x1`

is a structure; otherwise it produces `x1`

.

`cset (x)`

-- convert to cset

Produces a cset resulting from converting `x`

, but fails if the conversion is not possible.

`delay (i) : n`

-- delay execution

Delays execution `i`

milliseconds.

`delete (X,x) : X`

-- delete element

If `X`

is a set, deletes `x`

from `X`

. If `X`

is a table, deletes the element for key `x`

from `X`

. Produces `X`

.

See also: `insert()`

and `member()`

`detab (s1,i1,i2,...,in) : s2`

-- remove tabs

Produces a string based on `s1`

in which each tab character is replaced by one or more blanks. Tab stops are at `i1, i2, ..., in`

, with additional stops obtained by repeating the last interval.

Default:

`i1`

`9`

See also: `entab()`

`display (i,c) : n`

-- display variables

Writes the image of the given co-expression and the values of the local variables in the current procedure call. If `i`

is given, the local variables in the `i`

preceding procedure calls are displayed as well. After all local variables are displayed, the values of global variables are displayed. Output is written to standard error.

Defaults:

`i`

`-1`

, meaning display all levels`c`

`¤t`

`entab (s1,i1,i2,...,in) : s2`

-- insert tabs

Produces a string based on `s1`

in which runs of blanks are replaced by tabs. Tab stops are at `i1, i2, ..., in`

, with additional stops obtained by repeating the last interval.

Default:

`i1`

`9`

See also: `detab()`

`errorclear () : n`

-- clear error indication

Clears the indications of the last error.

See also: `&error`

`exit (i)`

-- exit program

Terminates the program with exit status i.

Default:

`i`

normal exit (system dependent)

See also: `stop()`

`fatalerr (x1,x2)`

-- stop with fatal error

This is the same as `runerr`

, but disables error conversion first.

See also: `runerr()`

`find (s1,s2,i1,i2) : i3,i4,...,in`

-- find string

Generates the sequence of integer positions in `s2`

at which `s1`

occurs as a substring in `s2[i1:i2]`

, but fails if there is no such position.

Defaults:

`s2`

`&subject`

`i1`

`&pos`

if`s2`

defaulted, otherwise`1`

`i2`

`0`

See also: `bal(), match(), and upto()`

`get (L) : x`

-- get value from list

Produces the leftmost element of `L`

and removes it from `L`

, but fails if `L`

is empty; synonym for `pop(L)`

.

See also: `pop(), pull(), push(), and put()`

`iand (i1,i2,...,in) : i3`

-- compute bit-wise and

Produces the bitwise and of the given parameters.

See also: `icom(), ior(), ishift(), and ixor()`

`icom (i1) : i2`

-- compute bit-wise complement

Produces the bitwise complement (1's complement) of `i1`

.

See also: `iand(), ior(), ishift(), and ixor()`

`image (x) : s`

-- produce string image

Produces a string image of `x`

.

`insert (X,x1,x2) : X`

-- insert element

If `X`

is a table, inserts the key `x1`

with value `x2`

into `X`

. If `X`

is a set, inserts `x1`

into `X`

. Produces `X`

.

Default:

`x2`

`&null`

See also: `delete() and member()`

`integer (x) : i`

-- convert to integer

Produces the integer resulting from converting `x`

, but fails if the conversion is not possible.

See also: `numeric() and real()`

`ior (i1,i2,...,in) : i3`

-- compute bit-wise inclusive or

Produces the bitwise inclusive or of the given parameters.

See also: `iand(), icom(), ishift(), and ixor()`

`is (o, cl) : cl`

-- test class of object

If `cl`

is a class, then succeed if and only if `o`

is an instance of class cl. If `cl`

is a constructor, then succeed if and only if `o`

is a record instance of `cl`

.

`ishift (i1,i2) : i3`

-- shift bits

Produces the result of shifting the bits in `i1`

by `i2`

positions. Positive values of `i2`

shift to the left, negative to the right. Vacated bit positions are zero-filled.

See also: `iand(), ior(), ior(), and ixor()`

`ixor (i1,i2,...,in) : i3`

-- compute bit-wise exclusive or

Produces the bitwise exclusive or of given parameters.

See also: `iand(), icom(), ior(), and ixor()`

`key (T) : x1,x2,...,xn`

-- generate keys from table

Generates the keys in table `T`

.

`keyof (x1,x2) : x3`

-- generate keys for a given value

Given a table or list `x1`

and a value `x2`

, generate the keys `x3`

such that `x1[x3] === x2`

`keyval (T) : x`

-- generate keys and values.

Generate alternate keys and their corresponding values (as variables) from table `T`

`left (s1,i,s2) : s3`

-- position string at left

Produces a string of size `i`

in which `s1`

is positioned at the left, with `s2`

used for padding on the right as necessary.

Defaults:

`i`

`1`

`s2`

`" "`

(blank)

See also: `center() and right()`

`list (i,x) : L`

-- create list

Produces a list of size `i`

in which each value is `x`

.

Defaults:

`i`

`0`

`x`

`&null`

`many (c,s,i1,i2) : i3`

-- locate many characters

Succeeds and produces the position in `s`

after the longest initial sequence of characters in `c`

in `s[i1:i2]`

. It fails if `s[i1]`

is not in `c`

.

Defaults:

`s`

`&subject`

`i1`

`&pos`

if`s`

defaulted, otherwise`1`

`i2`

`0`

See also: `any() and match()`

`map (s1,s2,s3) : s4`

-- map characters

Produces a string of size `*s1`

obtained by mapping characters of `s1`

that occur in `s2`

into corresponding characters in s3.

Defaults:

`s2`

`string(&ucase)`

`s3`

`string(&lcase)`

`match (s1,s2,i1,i2) : i3`

-- match initial string

Produces `i1 + *s1`

if `s1 == s2[i1+:*s1]`

, but fails otherwise.

Defaults:

`s2`

`&subject`

`i1`

`&pos`

if`s2`

defaulted, otherwise`1`

`i2`

`0`

See also: `=s, any(), and many()`

`max (N1, N2) : N3`

-- maximum

Return the maximum of `N1`

, `N2`

`member (X,x) : x`

-- test for membership If X is a set, succeeds if x is a member of X, but fails otherwise. If X is a table, succeeds if x is a key of an element in X, but fails otherwise. Produces x if it succeeds.

See also: delete() and insert()

`min (N1, N2) : N3`

-- minimum

Return the minimum of `N1`

, `N2`

`move (i) : s`

-- move scanning position

Produces `&subject[&pos:&pos + i]`

and assigns `i + &pos`

to `&pos`

, but fails if i is out of range; reverses assignment to `&pos`

if resumed.

See also: `tab()`

`numeric (x) : N`

-- convert to numeric

Produces an integer or real number resulting from converting `x`

, but fails if the conversion is not possible.

See also: `integer() and real()`

`ord (x,i1,i2) : i3`

-- generate code points

Generate the code points in a cset, ucs or string for the range of entries `i1:i2`

Defaults:

`i1`

`1`

`i2`

`0`

`pop (L) : x`

-- pop from list Produces the leftmost element of `L`

and removes it from `L`

, but fails if `L`

is empty; synonym for `get(L)`

.

See also: `get(), pull(), push(), and put()`

`pos (i1) : i2`

-- test scanning position

Produces `&pos`

if `&pos`

= `i1`

, but fails otherwise.

See also: `&pos`

and `&subject`

`proc (x,i,c) : p`

-- convert to procedure

Produces a procedure corresponding to the value of `x`

, but fails if `x`

does not correspond to a procedure. Firstly the global variables of the program `c`

are searched. If a match is found then it is returned if it is a procedure, otherwise the call fails. If no global match is found, then an operator of arity `i`

is searched for and returned if found. Failing that, built-in functions and keyword functions are searched. If no match is found there either, the call fails.

Default:

`i`

`1`

`c`

`&main`

`pull (L) : x`

-- pull from list

Produces the rightmost element of `L`

and removes it from `L`

, but fails if `L`

is empty.

See also: `get(), pop(), push(), and put()`

`push (L,x) : L`

-- push onto list

Pushes `x`

onto the left end of `L`

.

See also: `get(), pop(), pull(), and put()`

`put (L,x) : L`

-- put onto list

Put `x`

onto the right end of `L`

.

See also: `get(), pop(), pull(), and push()`

`real (x) : r`

-- convert to real

Produces a real number resulting from type conversion of `x`

, but fails if the conversion is not possible.

See also: `integer() and numeric()`

`repl (s1,i) : s2`

-- replicate string

Produces a string consisting of `i`

concatenations of `s1`

.

`reverse (s1) : s2`

-- reverse string

Produces a string consisting of the reversal of `s`

.

`right (s1,i,s2) : s3`

-- position string at right

Produces a string of size `i`

in which `s1`

is positioned at the right, with `s2`

used for padding on the left as necessary.

Defaults:

`i`

`1`

`s2`

`" "`

(blank)

See also: `center() and left()`

`runerr (x1,x2)`

-- terminate with run-time error

Terminates program execution with error `x1`

and offending value `x2`

. `x1`

may be an integer, being a standard error number, or a string, being a custom error message.

`seq (i1,i2) : i3,i4,...`

-- generate sequence of integers

Generates an endless sequence of integers starting at `i1`

with increments of `i2`

.

Defaults:

`i1`

`1`

`i2`

`1`

See also: `i1 to i2 by i3`

`serial (x) : i`

-- produce serial number Produces the serial number of `x`

if it is a type that has one but fails otherwise.

`set (x1,x2,...,xn) : S`

-- create set

Produces a set whose members are the values `x1`

,`x2`

,...,`xn`

`sort (X,i) : L`

-- sort structure

Produces a list containing values from `X`

. If `X`

is a list, record, or set, `sort(X,i)`

produces the values of `X`

in sorted order. If `X`

is a table, `sort(X,i)`

produces a list obtained by sorting the elements of `X`

, depending on the value of `i`

. For `i`

= `1`

or `2`

, the list elements are two-element lists of key/value pairs. For `i`

= `3`

or `4`

, the list elements are alternating keys and values. Sorting is by keys for `i`

odd, by value for `i`

even.

Default:

`i`

`1`

See also: `sortf()`

`sortf (X,i) : L`

-- sort list or set by field

Produces a sorted list of the values in `X`

. Sorting is primarily by type and in most respects is the same as with `sort(X,i)`

. However, among lists and among records, two structures are ordered by comparing their ith fields. `i`

can be negative but not zero. Two structures having the equal `i`

th fields are ordered as they would be in regular sorting, but structures lacking an ith field appear before structures having them.

Default:

`i`

`1`

See also: `sort()`

`string (x) : s`

-- convert to string Produces a string resulting from converting x, but fails if the conversion is not possible.

`syserr (s)`

-- stop execution, indicating an internal error

`system (s) : i`

-- call system function

Calls the C library function `system()`

to execute `s`

and produces the resulting integer exit status.

`tab (i) : s`

-- set scanning position Produces `&subject[&pos:i]`

and assigns i to `&pos`

, but fails if i is out of range. It reverses assignment to `&pos`

if resumed.

See also: move()

`table (x,k1,v1,k2,v2,...,kn,vn) : T`

-- create table

Produces a table with a default value `x`

, and initial mappings `k1->v1`

, `k2->v2`

, etc.

Default:

- x
`&null`

`text (x1) : x2`

-- convert to string or ucs type

If `x1`

is a string or ucs, it is just returned. If `x1`

is a cset then it is converted to a string if its highest char is < 256; otherwise it is converted to a ucs. For any other type, normal string conversion is attempted.

`trim (s1,c) : s2`

-- trim string Produces a string consisting of the characters of s1 up to the trailing characters contained in c.

Default:

- c ' ' (blank)

`type (x) : s`

-- produce type name

Produces a string corresponding to the type of `x`

.

`uchar (i) : u`

-- ucs char

Produce a ucs consisting of character `i`

. Fails if `i`

is not a valid unicode codepoint.

`ucs (x) : u`

-- convert to ucs

Convert `x`

to a ucs (unicode character string)

`upto (c,s,i1,i2) : i3,i4,...,in`

-- locate characters

Generates the sequence of integer positions in `s`

preceding a character of `c`

in `s[i1:i2]`

. It fails if there is no such position.

Defaults:

`s`

`&subject`

`i1`

`&pos`

if`s`

defaulted, otherwise`1`

`i2`

`0`

See also: `bal() and find()`

`weakref (x) : w`

-- create a weak reference

Creates a `weakref`

to `x`

. This means that the reference to `x`

inside the `weakref`

will not prevent `x`

being garbage collected. `x`

must be a list, set, table, record, methp, object or coexpression. Any other type causes `weakref`

to fail.

`weakrefval (w) : x`

-- get weak reference value

Given a weak reference, return the value inside it. If a garbage collection has taken place and the value has been collected (because this was the last reference), then `weakrefval`

fails.