Introduction

This page lists Object Icon’s builtin functions.

abs

abs (N) : N – compute absolute value

Produces the absolute value of N.

any

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

back (x1,i) : x2 – reverse order generation

Generate the elements of x1 in reverse order, beginning with the element immediately before position i (the first element generated will be x1[i-1]). x1 may be a list, cset, ucs, record or string.

See also: forward()

Defaults:

• i 0

bal

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

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

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

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

clear (X) : X – clear structure

Clears all the elements from X which must be a set, list or table. Produces X.

coact

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

cocopy (ce) : ce – refresh with copy

Return a refreshed copy of ce, but with a copied set of local variables.

cofail

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

collect () : n – perform garbage collection

copy

copy (x1) : x2 – copy value

Produces a copy of x1 if x1 is a structure; otherwise it produces x1.

cset

cset (x) – convert to cset

Produces a cset resulting from converting x, but fails if the conversion is not possible.

delay

delay (i) : n – delay execution

Delays execution i milliseconds.

delete

delete (X,x) : X – delete element

If X is a set, deletes x from X, failing if x is not currently a member. If X is a table, deletes the element for key x from X, failing if x is not a key. If X is a list, delete the xth element of the list, failing if the index is out of range.

On success, produces X.

See also: insert() and member()

detab

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

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 &current

echo

echo (x) : x – generate x repeatedly without dereferencing

Since x isn’t dereferenced, this function can be used, with the help of a co-expression, to “store” a variable. For example :-

   s := "The quick brown fox"
   e := create echo(s[4])
   @e := "*"    # s is now "The*quick brown fox"
   @e := "#"    # s is now "The#quick brown fox"
   ... etc

Note that in the above, the expression s[4] is only evaluated once, but the variable it produces is used several times.

entab

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

errorclear () : n – clear error indication

Clears the indications of the last error.

See also: &error

exit

exit (i) – exit program

Terminates the program with exit status i.

Default:

• i normal exit (system dependent)

See also: stop()

fatalerr

fatalerr (x1,x2) – stop with fatal error

This is the same as runerr, but disables error handling by &handler first.

See also: runerr()

find

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

forward

forward (x1,i) : x2 – forward order generation

Generate the elements of x1, beginning with the element immediately after position i (the first element generated will be x1[i]) x1 may be a list, cset, ucs, record or string.

See also: back()

Defaults:

• i 1

get

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

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

icom (i1) : i2 – compute bit-wise complement

Produces the bitwise complement (1’s complement) of i1.

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

image

image (x) : s – produce string image

Produces a string image of x.

insert

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. These cases always succeed.

If X is a list, insert the value x2 into position x1. Fails if x1 is out of range, with the exception that x1 may be zero, or equal to *X + 1, in which case the behaviour is equivalent to put(X,x2`).

On success, produces X.

Default:

• x2 &null

See also: delete() and member()

integer

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

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

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

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

ixor (i1,i2,...,in) : i3 – compute bit-wise exclusive or

Produces the bitwise exclusive or of the given parameters.

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

key

key (T) : x1,x2,...,xn – generate keys from table

Generates the keys in table T.

keyof

keyof (x1,x2) : x3 – generate keys for a given value

Given a table, record or list x1 and a value x2, generate the keys x3 such that x1[x3] === x2

keyval

keyval (T) : x – generate keys and values.

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

left

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

list (i,x) : L – create list

Produces a list of size i in which each value is x.

Defaults:

• i 0
• x &null

many

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

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

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

max (N1, N2, ...) : N3 – maximum

Return the maximum of N1, N2, etc.

member

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(), insert(), and keyof(). The latter provides an easy way to test for membership of a list.

min

min (N1, N2, ...) : N3 – minimum

Return the minimum of N1, N2, etc.

move

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

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

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

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

pos (i1) : i2 – test scanning position

Produces &pos if &pos = i1, but fails otherwise.

See also: &pos and &subject

proc

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

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

push (L,x) : L – push onto list

Pushes x onto the left end of L.

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

put

put (L,x) : L – put onto list

Put x onto the right end of L.

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

real

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

repl (s1,i) : s2 – replicate string

Produces a string consisting of i concatenations of s1.

reverse

reverse (s1) : s2 – reverse string

Produces a string consisting of the reversal of s.

right

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

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

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

serial (x) : i – produce serial number

Produces the serial number of x if it is a type that has one but fails otherwise.

set

set (x1,x2,...,xn) : S – create set

Produces a set whose members are the values x1,x2,…,xn

sort

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

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 ith 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

string (x) : s – convert to string

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

syserr

syserr (s) – stop execution, indicating an internal error

system

system (s) : i – call system function

Calls the C library function system() to execute s and produces the resulting integer exit status.

tab

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

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

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

trim (s1,c,i) : s2 – trim string

Produces a string consisting of the characters of s1 with leading and/or trailing characters contained in c removed according to the third parameter, i, as follows :-

• if i >= 0 then leading characters are removed (“left trimming”);
• if i <= 0 then trailing characters are removed (“right trimming”).

Thus, if i = 0 (the default), both left and right trimming takes place.

Defaults:

• c ’ ’ (blank)
• i 0

type

type (x) : s – produce type name

Produces a string corresponding to the type of x.

uchar

uchar (i) : u – ucs char

Produce a ucs consisting of character i. Fails if i is not a valid unicode codepoint.

ucs

ucs (x) : u – convert to ucs

Convert x to a ucs (unicode character string)

upto

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

variable

variable (x) : x – test for variable

If x is a variable, then it is returned (without being dereferenced), otherwise this function fails.

vimage

vimage (v) : s – produce variable string image

Given a variable v, return an identifying image. If v is an identifier or a keyword that is a variable, the name of the identifier or keyword is produced. If v is a record field reference, the record name and field name are produced with a separating period. If v is a string, the name of the string and the subscript range are shown. If v is a subscripted list or table, the type name followed by the subscripting expression is produced.

weakref

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

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.