OADL Programming Reference Manual

Intrinsic Procedures and Methods

Intrinsic Procedures

An OADL intrinsic procedure is one which is built-in to the OADL machine. It is not possible to place the address of an intrinsic procedure in a variable. Additionally, the number of arguments to intrinsic procedures is generally checked at compile-time. All OADL intrinsic procedures except for typeof are found in the oadl namespace.

Procedure Argument Intrinsic Procedures

These intrinsics deal with procedure arguments:

arg(n): Returns the value of argument number n

nargs(): Returns the number of arguments passed to the current procedure.

argvec(): Returns a List containing all of the arguments to the current procedure.

Machine Execution Intrinsic Procedures

These intrinsics modify the execution of the OADL machine:

halt(): Immediately halts execution of the OADL virtual machine.

setjmp(buf): Sets the target for a later longjmp() non-local jump

longjmp(buf, val): Does a non-local jump to an enclosing procedure location where setjmp() was called

save(filename): Saves the complete OADL state to a file

restore(filename): Restores the complete OADL state from a file

restart(): Restarts the entire OADL machine

Memory Subsystem Intrinsic Procedures

These intrinsics manage various aspects of the dynamic memory subsystem:

gc(): Immediately performs a garbage collection cycle

protect(val): Returns a new read-only copy of a value

readonly(val)
readonly(obj, pub): Checks to see if a value is read-only

deleted(obj): Returns true if the given obj has been marked for deletion

perm(val): Creates a "permanent" copy of the given value

transient(val): Check whether the given value is located in the default, dynamic memory pool

Type Checking Intrinsic Procedures

These intrinsics return information about the types of their arguments:

typeof(val): Returns the type of a value; for example, Int, Null, Float, etc. Unlike all other intrinsic procedures, typeof() is found in the global namespace.

typecheck(typ, val): Checks to ensure that the type of val is derived from typ. If not, a TypeCheck exception is thrown. Returns true if the type matches.

is_a(obj,cls): Returns true if the class cls is a parent of the given object obj, and false otherwise. Same as the ?= comparison operator.

Input / Output Intrinsic Procedures

These procedures are all found in the global namespace. See the chapter on Input / Output for more information about them.

getchar()
getchar(file): Get a single character of input

print(fmtstring, arg, ...)
print(file, fmtstring, arg, ...): Print a formatted set of values

putchar(ch)
putchar(file, ch): Puts a single character to a file

ungetc(ch)
ungetc(file, ch): Returns a single character to a file's input buffer

read(fmtstring, typ, ...)
read(file, fmtstring, typ, ...)
read(string, fmtstring, typ, ...): Reads a formatted set of values

readstr()
readstr(file): Reads a string from a file

say(arg, arg, ...)
say(file, arg, arg, ...): Prints a list of values with default formatting rules

These procedures are found in namespace io.

io::putvar(arg, arg, ...)
io::putvar(file, arg, arg, ...): Prints a list of values including type and structure information

io::getvar()
io::getvar(file): Gets a single value from the given file (or io::Input) which must be formatted as io::putvar() does.

Other Intrinsic Procedures

There are a couple of other miscellaneous intrinsic procedures supported by OADL:

matchvec(): Returns a List of all of the match pattern substrings ?1, ?2, etc.

format(fmtstring, arg, ...): Create a string representation of the arg list given the format specifier fmtstring.

Standard Class Methods

Several methods are predefined for all OADL classes. They may be overridden by the OADL programmer. See the chapter on Classes for a detailed description of these methods:

obj.create(): Called when a new static or dynamic Object is created

obj.destroy(): Called if an object is to be destroyed during dynamic memory reclamation

obj.operator {}(args): Object completion operator

Intrinsic Methods

Intrinsic methods are provided by OADL to perform a broad range of operations. Note that, unlike programmer-defined methods, OADL intrinsic methods can operate on values with types other than Object.

Type Query Intrinsic Methods

arr.arrbase(): Returns the base type of arr (for example, Char, Int, etc.) or Array if arr is a heterogeneous List or Array.

val.isarray(): Returns true if val is an array of any kind (List, String, PackInt, etc.) and false otherwise.

val.ischar(): Returns true if val is a scalar character of any kind (Char or WideChar) and false otherwise.

val.isfloat(): Returns true if val is a floating point scalar of any kind (Half, Float, or Double) and false otherwise.

val.isinteger(): Returns true if val is an integral scalar of any kind (Byte, Ubyte, Short, Ushort, Int, Uint, Long, or Ulong) and false otherwise.

val.isnumeric(): Returns true if val is a numeric scalar of any kind (Byte, Ubyte, Short, Ushort, Int, Uint, Long, Ulong, Half, Float, or Double) and false otherwise.

val.isstring(): Returns true if val is string of any kind (String or WideString) and false otherwise.

val.length(): Returns the number of elements along the first dimesion of an array, or the number of public properties of an object, or the number of currently defined key/value pairs in a dictionary.

typ.maxval(): Returns the maximum possible value of the given typ (Float, Int, etc.)

typ.minval(): Returns the minimum possible value of the given typ (Float, Int, etc.)

typ.packtype(): Returns the packed array type that corresponds to the scalar type typ (for example, Int.packtype() returns PackInt)

val0.promote(val1): Returns the entry in the type promotion table from the Expressions chapter that corresponds to val0 and val1. If val0 or val1 is an OADL Type they are used directly. If they are not an OADL TYpe, their base types are used as the indexes into the table.

val.rank(): Returns the rank of val - the number of dimensions of the given array. The rank of a scalar is 0.

val.shape(): Returns a PackInt array which is the multi-dimensional shape of val. The shape of a scalar is the empty packed integer array 0->iterate()

val.sizeof(): Returns the total number of elements of array or dictionary val. The sizeof a scalar is 1.

Dynamic Value Management Intrinsic Methods

val.copy(): Creates a copy of the given array, string, or object. The elements of an array are NOT recursively copied. This is identical in effect to the @ operator. The new copy is neither permanent nor read-only regardless of whether val is permanent or read-only.

val.deepcopy(): Creates a copy of the given array, string, or object. The elements of an array ARE recursively copied. This is identical in effect to the @@ operator. The new copy is neither permanent nor read-only regardless of whether val is permanent or read-only.

val.readonly()
obj.readonly(pub): The zero-argument form returns whether the given object or array value val is read-only. The one-argument form returns whether the public property pub of Object obj is read-only. A TypeCheck exception is thrown if val, obj, or pub is not of an appropriate type.

val.transient(): Returns true if the given val is located in dynamically maintained memory subject to garbage collection, and false otherwise. A TypeCheck exception is thrown if val is not of an appropriate type.

File Input / Output Intrinsic Methods

See the chapter on Input / Output for more information about these intrinsic methods.

file.binary(): Query whether a file was opened in binary-mode

file.clearerr(): Clear a file's error indicator

file.close()
file.close(disp): Close a file

file.feof(): Query a file's end-of-file indicator

file.ferror(): Query a file's error indicator

file.fflush(): Flush pending output

file.fseek(offs, whence): Change a file's read/write position

file.ftell(): Query a file's read/write position

file.getchar(): Read a single byte from a file

file.getswab(): Query a file's byte-swap indicator

file.getvar(): Reads a value from the given file formatted with type and structure information according to getvar()

file.ispipe(): Query whether a file is a pipe

file.print(fmtstr, arg, ...): Print formatted values

file.putchar(): Put a byte into a file

file.putvar(arg, ...): Puts variables into the given file formatted with type and structure information

file.read(typ, typ, ...)
file.read(fmtstr, typ, typ, ...)
string.read(fmtstr, typ, typ, ...): Read values from a file

file.readonly(): Query whether a file was opened read-only

file.readstr(): Read a string from a file

file.rewind(): Move a file's read/write position to the beginning

file.say(arg, arg, ...): Print values with default formats

file.setswab(bSwab): Set a file's byte-swap flag

file.ungetc(): Push back a byte to a file's input stream

file.write(val, val, ...): Write binary values to a file

Mathematical Intrinsic Methods

val.abs(): Computes the absolute value of val

val.clamp(lower, upper): Compares val to the given lower and upper bounds, clamping it to those bounds and returning the new value.

val.fix2flt(typ): Convert a value or array of values from 8- or 16-bit signed or unsigned integers to the specified floating point type

val.flt2fix(typ): The inverse of fix2flt(). Convert a value or array of values from floating point to a specified 8- or 16-bit signed or unsigned fixed-point number.

first.lerp(last, dist): Linearly interpolates or extrapolates from given first and last bounds.

val₀.max(val₁, val₂, ...): Computes the maximum of a set of values.

val₀.min(val₁, val₂, ...): Computes the minimum of a set of values.

val₀.satadd(val₁, lower, upper): Computes val₀ plus val₁ and clamps the result to the given lower and upper bounds.

val₀.satsub(val₁, lower, upper): Computes val₀ minus val₁ and clamps the result to the given lower and upper bounds.

val.signum(): Computes the signum of val, which is defined as -1 if val is less than minus zero, 1 if val is greater than zero, or 0 if val is equal to zero.

Array Manipulation Intrinsic Methods

Many of these methods were inspired by the programming language APL, which is an innovative interactive language developed in the 1960s to perform many array calculations and general-purpose computing tasks. There are a few conventions that should be noted:

A vec is either a scalar or a single-dimensional array of any type (List, String, PackInt, etc.).
An op is an operator, method, or procedure. An op may be specified with the operator op syntax (for arithmetic operators), the ` op syntax (for operators or public indexes), or with the public::pub syntax (for public indexes). Procedures can be passed without special syntax.
Finally, an axis is an index into the shape of an array, indicating a dimension to which an operation should apply. A negative axis specification is equivalent to arr.rank() + axis, so axis number -1 is the last axis, axis number -2 is the next-to-last axis, and so on. Typically, if no axis is specified, the last axis of an array is used.

Unlike APL, English names of the various array operations are used for the array intrinsic methods.

arr.accum(op)
arr.accum(op, axis): Accumulate results of an operation across an axis.

arr0.arrcmp(arr1): Lexicographically compares two arrays or strings, returning -1, 0, or 1

a.concat(b, c, ...): Concatenates several values, returning a new array or string. Exactly the same as the ## operator.

val₀.decode(val₁): Convert non-uniform number bases, evaluate polynomials.

arr.disclose(): Remove a level of nesting from an enclosure.

arr.drop(num)
arr.drop(num, axis): Returns the suffix of an array.

val.enclose()
val.enclose(axis): Enclose a value to make a scalar.

base.encode(val): Compute the representation of val in the radix system defined by base.

arr.flatten(): Completely flattens an array, including any nested elements

vec.increment(shp): Increment a multi-dimensional index

arr₀.inner(op₀, op₁, arr₁): Compute the inner product of two arrays

arr₀.intersect(arr₁): Compute the set intersection of two arrays

shp.iterate(): Create an array of sequential integers starting from zero

arr₀.laminate(arr₁)
arr₀.laminate(arr₁, axis): Concatente two arrays about an alternate axis

val.member(arr): Tests if elements are members of a set

arr.nreduce(n, op)
arr.nreduce(n, op, axis): Compute windowed reduction along an axis

arr₀.outer(op, arr₁): Compute a generalized outer product

arr.pack(): Create a packed copy of a heterogenous array

arr.position(items): Find location of items in array arr

arr.ravel()
arr.ravel(axis): Flatten or combine dimensions of an array

arr.reduce(op)
arr.reduce(op, axis): Reduce an array along an axis using an operator

arr.replicate(key)
arr.replicate(key, axis): Replicate elements of an array along an axis

val.reshape(d₀, d₁, ...)
val.reshape(shp): Change the shape of an array

arr.reverse()
arr.reverse(axis): Reverse an array along an axis

arr.rotate(num)
arr.rotate(num, axis): Rotate elements of an array along an axis

arr.setsubr(beg₀, end₀, beg₁, end₁, ..., val ): Equivalent to arr[beg₀:end₀, beg₁:end₁, ...] = val

arr.sort()
arr.sort(cmp): Returns a sorted copy of arr according to the optional cmp proc or operator. If cmp is not specified, operator < is assumed.

arr.stride(): Returns the number of elements between each dimension of an array.

arr.subr(beg₀, end₀, beg₁, end₁, ... ): Equivalent to arr[beg₀:end₀, beg₁:end₁, ...].

arr.take(num)
arr.take(num, axis): Shorten or extend arr along one or more axes.

arr.transpose()
arr.transpose(permutation): Permute the axes of an array

arr₁.union(arr₂): Returns the union of elements in two arrays

vec.unique(): Returns a vector containing the unique elements of an array

arr.unpack(): Create a new unpacked copy of the given array, resulting in either a List (for single-dimensional arrays) or an Array (for multi-dimensional arrays).

val.width(): Returns the number of elements along the last dimesion of an array

arr₁.without(arr₂): Returns elements of arr₁ that are not present in arr₂

Back to Procedures

Continue to External Procedures

Return to Introduction