6. Library Functions

6.1 Basic Constants and Predicates
6.2 Numbers
6.3 Characters
6.4 Strings
6.5 CONS Lists and Trees
6.6 Lists
6.7 Property and Key-Value Lists
6.8 Vectors
6.9 Hash Tables
6.10 Key Value Maps
6.11 Hash Sets
6.12 Iterators
6.13 Symbols
6.14 Context and Modules
6.15 Input and Output
6.16 Files
6.17 Dates and Times
6.18 XML Support
6.19 Miscellaneous

6.1 Basic Constants and Predicates

???: true

Not yet implemented.

???: false

Not yet implemented.

Method: OBJECT null? (x) : BOOLEAN

Return true if x is undefined (handled specially by all translators).

Method: SECOND-CLASS-OBJECT null? (x) : BOOLEAN

Return true if x is undefined (handled specially by all translators).

Method: NATIVE-VECTOR null? (x) : BOOLEAN

Return true if x is undefined (handled specially by all translators).

Method: STRING null? (x) : BOOLEAN

Return true if x is undefined (handled specially by all translators).

Method: MUTABLE-STRING null? (x) : BOOLEAN

Return true if x is undefined (handled specially by all translators).

Method: CHARACTER null? (x) : BOOLEAN

Return true if x is undefined (handled specially by all translators).

Method: CODE null? (x) : BOOLEAN

Return true if x is undefined (handled specially by all translators).

Method: INTEGER null? (x) : BOOLEAN

Return true if x is undefined (handled specially by all translators).

Method: FLOAT null? (x) : BOOLEAN

Return true if x is undefined (handled specially by all translators).

Method: OBJECT defined? (x) : BOOLEAN

Return true if x is defined (handled specially by all translators).

Method: SECOND-CLASS-OBJECT defined? (x) : BOOLEAN

Return true if x is defined (handled specially by all translators).

Method: NATIVE-VECTOR defined? (x) : BOOLEAN

Return true if x is defined (handled specially by all translators).

Method: STRING defined? (x) : BOOLEAN

Return true if x is defined (handled specially by all translators).

Method: MUTABLE-STRING defined? (x) : BOOLEAN

Return true if x is defined (handled specially by all translators).

Method: CHARACTER defined? (x) : BOOLEAN

Return true if x is defined (handled specially by all translators).

Method: CODE defined? (x) : BOOLEAN

Return true if x is defined (handled specially by all translators).

Method: INTEGER defined? (x) : BOOLEAN

Return true if x is defined (handled specially by all translators).

Method: FLOAT defined? (x) : BOOLEAN

Return true if x is defined (handled specially by all translators).

Function: eq? ((x UNKNOWN) (y UNKNOWN)) : BOOLEAN

Return true if x and y are literally the same object (or simple number). Analogue to the Common Lisp EQL and C++ and Java's ==.

Function: eql? ((x OBJECT) (y OBJECT)) : BOOLEAN

Return true if x and y are eq? or equivalent literals such as strings that also might be wrapped in non-identical wrappers. For the case where x or y are plain literals such as strings or integers, the STELLA translator substitutes the equality test appropriate for the particular target language and does not actually call this function. For cases where x or y are known to be of type STANDARD-OBJECT, the STELLA translator substitutes the faster eq? test inline.

Function: equal? ((x OBJECT) (y OBJECT)) : BOOLEAN

Return true if x and y are eql? or considered equal by a user-defined object-equal? method. This implements a fully extensible equality test similar to Java's equals method. Note that writers of custom object-equal? methods must also implement a corresponding equal-hash-code method.

Method: OBJECT object-equal? (x (y OBJECT)) : BOOLEAN

Return true if x and y are eq?.

Method: WRAPPER object-equal? (x (y OBJECT)) : BOOLEAN

Return true if x and y are literal wrappers whose literals are considered eql?.

6.2 Numbers

Constant: pi : FLOAT

A float approximation of the mathematical constant pi.

Function: + (&rest (arguments NUMBER)) : NUMBER

Return the sum of all arguments.

Function: - ((x NUMBER) &rest (arguments NUMBER)) : NUMBER

If only x was supplied return the result of 0 - x. Otherwise, return the result of (...((x - arg1) - arg2) - ... - argN).

Function: * (&rest (arguments NUMBER)) : NUMBER

Return the product of all arguments.

Function: / ((x NUMBER) &rest (arguments NUMBER)) : NUMBER

If only x was supplied return the result of 1 / x. Otherwise, return the result of (...((x / arg1) / arg2 ) / ... / argN).

Macro: 1+ ((expression OBJECT)) : OBJECT

Add 1 to expression and return the result.

Macro: 1- ((expression OBJECT)) : OBJECT

Subtract 1 from expression and return the result.

Macro: ++ ((place OBJECT) &body (increment CONS)) : OBJECT

Increment the value of place and return the result. place can be either a variable name or a slot reference. Increment by the optional increment (which can be a float) or 1 otherwise.

Macro: -- ((place OBJECT) &body (decrement CONS)) : OBJECT

Decrement the value of place and return the result. place can be either a variable name or a slot reference. Decrement by the optional decrement (which can be a float) or 1 otherwise.

Function: = ((x NUMBER) (y NUMBER)) : BOOLEAN

Return true if x and y are numbers of exactly the same magnitude.

Function: < ((x NUMBER) (y NUMBER)) : BOOLEAN

Return true if x is less than y.

Function: <= ((x NUMBER) (y NUMBER)) : BOOLEAN

Return true if x is less than or equal to y.

Function: >= ((x NUMBER) (y NUMBER)) : BOOLEAN

Return true if x is greater than or equal to y.

Function: > ((x NUMBER) (y NUMBER)) : BOOLEAN

Return true if x is greater than y.

???: zero?

Not yet implemented.

???: plus?

Not yet implemented.

???: even?

Not yet implemented.

???: odd?

Not yet implemented.

???: div

Not yet implemented.

???: rem

Not yet implemented.

???: mod

Not yet implemented.

Function: gcd ((x LONG-INTEGER) (y LONG-INTEGER)) : LONG-INTEGER

Return the greatest common divisor of x and y.

Function: ceiling ((n NUMBER)) : INTEGER

Return the smallest integer >= n.

Function: floor ((n NUMBER)) : INTEGER

Return the biggest integer <= n.

Function: round ((n NUMBER)) : INTEGER

Round n to the closest integer and return the result.

Method: INTEGER abs (x) : INTEGER

Return the absolute value of x.

Method: FLOAT abs (x) : FLOAT

Return the absolute value of x.

???: min

Not yet implemented.

???: max

Not yet implemented.

Function: sqrt ((n FLOAT)) : FLOAT

Return the square root of n.

Function: exp ((n FLOAT)) : FLOAT

Return the e to the power n.

Function: expt ((x FLOAT) (y FLOAT)) : FLOAT

Return x ^ y.

Function: log ((n FLOAT)) : FLOAT

Return the natural logarithm (base e) of n.

Function: log10 ((n FLOAT)) : FLOAT

Return the logarithm (base 10) of n.

Function: sin ((n FLOAT)) : FLOAT

Return the sine of n radians.

Function: cos ((n FLOAT)) : FLOAT

Return the cosine of n radians.

Function: tan ((n FLOAT)) : FLOAT

Return the tangent of n radians.

Function: asin ((n FLOAT)) : FLOAT

Return the arcsine of n in radians.

Function: acos ((n FLOAT)) : FLOAT

Return the arccosine of n in radians.

Function: atan ((n FLOAT)) : FLOAT

Return the arc tangent of n in radians.

Function: atan2 ((x FLOAT) (y FLOAT)) : FLOAT

Return the arc tangent of x / y in radians.

Function: random ((n INTEGER)) : INTEGER

Generate a random integer in the interval [0..n-1].

Function: integer-to-string ((i LONG-INTEGER)) : STRING

Convert i to its string representation and return the result. This is more efficient than using a string stream.

Function: string-to-integer ((string STRING)) : LONG-INTEGER

Convert a string representation of an integer into an integer.

Function: float-to-string ((f FLOAT)) : STRING

Convert f to its string representation and return the result. This is more efficient than using a string stream.

Function: string-to-float ((string STRING)) : FLOAT

Convert a string representation of a float into a float.

Function: format-float ((f FLOAT) (nDecimals INTEGER)) : STRING

Print f in fixed-point format with nDecimals behind the decimal point and return the result as a string.

Function: wrap-integer ((value INTEGER)) : INTEGER-WRAPPER

Return a literal object whose value is the INTEGER value.

Function: unwrap-integer ((wrapper INTEGER-WRAPPER)) : INTEGER

Unwrap wrapper and return the result. Return NULL if wrapper is NULL.

Function: wrap-float ((value FLOAT)) : FLOAT-WRAPPER

Return a literal object whose value is the FLOAT value.

Function: unwrap-float ((wrapper FLOAT-WRAPPER)) : FLOAT

Unwrap wrapper and return the result. Return NULL if wrapper is NULL.

6.3 Characters

Function: character-code ((ch CHARACTER)) : INTEGER

Return the 8-bit ASCII code of ch as an integer.

Function: code-character ((code INTEGER)) : CHARACTER

Return the character encoded by code (0 <= code <= 255).

Function: digit-character? ((ch CHARACTER)) : BOOLEAN

Return TRUE if ch represents a digit.

Function: letter-character? ((ch CHARACTER)) : BOOLEAN

Return TRUE if ch represents a letter.

Function: upper-case-character? ((ch CHARACTER)) : BOOLEAN

Return TRUE if ch represents an upper-case character.

Function: lower-case-character? ((ch CHARACTER)) : BOOLEAN

Return TRUE if ch represents a lower-case character.

Function: white-space-character? ((ch CHARACTER)) : BOOLEAN

Return TRUE if ch is a white space character.

Function: character-downcase ((ch CHARACTER)) : CHARACTER

If ch is lowercase, return its uppercase version, otherwise, return ch unmodified.

Function: character-upcase ((ch CHARACTER)) : CHARACTER

If ch is uppercase, return its lowercase version, otherwise, return ch unmodified. If only the first character of a sequence of characters is to be capitalized, character-capitalize should be used instead.

Function: character-capitalize ((ch CHARACTER)) : CHARACTER

Return the capitalized character for ch. This is generally the same as the uppercase character, except for obscure non-English characters in Java. It should be used if only the first character of a sequence of characters is to be capitalized.

Function: character-to-string ((c CHARACTER)) : STRING

Convert c into a one-element string and return the result.

Function: wrap-character ((value CHARACTER)) : CHARACTER-WRAPPER

Return a literal object whose value is the CHARACTER value.

Function: unwrap-character ((wrapper CHARACTER-WRAPPER)) : CHARACTER

Unwrap wrapper and return the result. Return NULL if wrapper is NULL.

6.4 Strings

Function: string-eql? ((x STRING) (y STRING)) : BOOLEAN

Return true if x and y are equal strings or are both undefined. This test is substituted automatically by the STELLA translator if eql? is applied to strings.

Function: string-equal? ((x STRING) (y STRING)) : BOOLEAN

Return true if x and y are equal strings ignoring character case or are both undefined.

Method: STRING empty? (x) : BOOLEAN

Return true if x is the empty string ""

Method: STRING non-empty? (x) : BOOLEAN

Return true if x is not the empty string ""

Function: string-compare ((x STRING) (y STRING) (case-sensitive? BOOLEAN)) : INTEGER

Compare x and y lexicographically, and return -1, 0, or 1, depending on whether x is less than, equal, or greater than y. If case-sensitive? is true, then case does matter for the comparison

Function: string< ((x STRING) (y STRING)) : BOOLEAN

Return true if x is lexicographically < y, considering case.

Function: string<= ((x STRING) (y STRING)) : BOOLEAN

Return true if x is lexicographically <= y, considering case.

Function: string>= ((x STRING) (y STRING)) : BOOLEAN

Return true if x is lexicographically >= y, considering case.

Function: string> ((x STRING) (y STRING)) : BOOLEAN

Return true if x is lexicographically > y, considering case.

Function: string-less? ((x STRING) (y STRING)) : BOOLEAN

Return true if x is lexicographically < y, ignoring case.

Function: string-less-equal? ((x STRING) (y STRING)) : BOOLEAN

Return true if x is lexicographically <= y, ignoring case.

Function: string-greater-equal? ((x STRING) (y STRING)) : BOOLEAN

Return true if x is lexicographically >= y, ignoring case.

Function: string-greater? ((x STRING) (y STRING)) : BOOLEAN

Return true if x is lexicographically > y, ignoring case.

Function: all-upper-case-string? ((s STRING)) : BOOLEAN

Return TRUE if all letters in s are upper case.

Function: all-lower-case-string? ((s STRING)) : BOOLEAN

Return TRUE if all letters in s are lower case.

Function: make-string ((size INTEGER) (initchar CHARACTER)) : STRING

Return a new string filled with size initchars.

Function: make-mutable-string ((size INTEGER) (initchar CHARACTER)) : MUTABLE-STRING

Return a new mutable string filled with size initchars.

Function: make-raw-mutable-string ((size INTEGER)) : MUTABLE-STRING

Return a new uninitialized mutable string of size.

Method: STRING first (self) : CHARACTER

Return the first character of self.

Method: MUTABLE-STRING first (self) : CHARACTER

Return the first character of self (settable via setf).

Method: STRING second (self) : CHARACTER

Return the second character of self.

Method: MUTABLE-STRING second (self) : CHARACTER

Return the second character of self (settable via setf).

Method: STRING third (self) : CHARACTER

Return the third character of self.

Method: MUTABLE-STRING third (self) : CHARACTER

Return the third character of self (settable via setf).

Method: STRING fourth (self) : CHARACTER

Return the fourth character of self.

Method: MUTABLE-STRING fourth (self) : CHARACTER

Return the fourth character of self (settable via setf).

Method: STRING fifth (self) : CHARACTER

Return the fifth character of self.

Method: MUTABLE-STRING fifth (self) : CHARACTER

Return the fifth character of self (settable via setf).

Method: STRING nth (self (position INTEGER)) : CHARACTER

Return the character in self at position.

Method: MUTABLE-STRING nth (self (position INTEGER)) : CHARACTER

Return the character in self at position.

Method: STRING rest (self) : STRING

Not documented.

Method: STRING length (self) : INTEGER

Return the length of the string self.

Method: MUTABLE-STRING length (self) : INTEGER

Return the length of the string self.

Method: STRING member? (self (char CHARACTER)) : BOOLEAN

Not documented.

Method: STRING position (string (character CHARACTER) (start INTEGER)) : INTEGER

Return the position of character within string (counting from zero); or return NULL if character does not occur within string. If start was supplied as non-NULL, only consider the substring starting at start, however, the returned position will always be relative to the entire string.

Method: STRING last-position (string (character CHARACTER) (end INTEGER)) : INTEGER

Return the last position of character within string (counting from zero); or return NULL if character does not occur within string. If end was supplied as non-NULL, only consider the substring ending at end, however, the returned position will always be relative to the entire string.

Function: string-search ((string STRING) (substring STRING) (start INTEGER)) : INTEGER

Return start position of the left-most occurrence of substring in string, beginning from start. Return NULL if it is not a substring.

Method: STRING copy (string) : STRING

Return a copy of string.

Function: string-upcase ((string STRING)) : STRING

Return an upper-case copy of string.

Function: string-downcase ((string STRING)) : STRING

Return a lower-case copy of string.

Function: string-capitalize ((string STRING)) : STRING

Return a capitalized version of string.

Method: STRING concatenate (string1 (string2 STRING) &rest (otherStrings STRING)) : STRING

Return a new string representing the concatenation of string1, string2, and otherStrings. The two mandatory parameters allow us to optimize the common binary case by not relying on the somewhat less efficient variable arguments mechanism.

Method: STRING subsequence (string (start INTEGER) (end INTEGER)) : STRING

Return a substring of string beginning at position start and ending up to but not including position end, counting from zero. An end value of NULL stands for the rest of the string.

Method: STRING remove (string (char CHARACTER)) : STRING

Remove all occurences of char from string.

Method: STRING substitute (self (new-char CHARACTER) (old-char CHARACTER)) : STRING

Substitute all occurences of old-char with new-char in the string self.

Method: MUTABLE-STRING substitute (self (new-char CHARACTER) (old-char CHARACTER)) : MUTABLE-STRING

Substitute all occurences of old-char with new-char in the string self.

Function: replace-substrings ((string STRING) (new STRING) (old STRING)) : STRING

Replace all occurrences of old in string with new.

Function: instantiate-string-template ((template STRING) &rest (vars&values STRING)) : STRING

For each occurrence of a <var> string from vars&values in template replace it with its corresponding <value> string. Replacement is done in sequence which means (part of) a value might be replaced further with a later <var> and <value>.

Function: insert-string ((source STRING) (start INTEGER) (end INTEGER) (target MUTABLE-STRING) (target-index INTEGER) (case-conversion KEYWORD)) : INTEGER

Inserts characters from source begining at start and ending at end into target starting at target-index. If end is null, then the entire length of the string is used. The copy of characters is affected by the case-conversion keyword which should be one of :UPCASE :DOWNCASE :CAPITALIZE :PRESERVE.

The final value of target-index is returned.

Function: wrap-string ((value STRING)) : STRING-WRAPPER

Return a literal object whose value is the STRING value.

Function: wrap-mutable-string ((value MUTABLE-STRING)) : MUTABLE-STRING-WRAPPER

Return a literal object whose value is the MUTABLE-STRING value.

Function: unwrap-string ((wrapper STRING-WRAPPER)) : STRING

Unwrap wrapper and return the result. Return NULL if wrapper is NULL.

Function: unwrap-mutable-string ((wrapper MUTABLE-STRING-WRAPPER)) : MUTABLE-STRING

Unwrap wrapper and return the result. Return NULL if wrapper is NULL.

Function: string-to-mutable-string ((s STRING)) : MUTABLE-STRING

Copy s into a mutable string with the same content. In Lisp and C++ this simply copies s.

Function: mutable-string-to-string ((s MUTABLE-STRING)) : STRING

Convert s into a regular string with the same content. In Lisp and C++ this is a no-op.

Function: integer-to-string ((i LONG-INTEGER)) : STRING

Convert i to its string representation and return the result. This is more efficient than using a string stream.

Function: string-to-integer ((string STRING)) : LONG-INTEGER

Convert a string representation of an integer into an integer.

Function: float-to-string ((f FLOAT)) : STRING

Convert f to its string representation and return the result. This is more efficient than using a string stream.

Function: string-to-float ((string STRING)) : FLOAT

Convert a string representation of a float into a float.

Function: format-float ((f FLOAT) (nDecimals INTEGER)) : STRING

Print f in fixed-point format with nDecimals behind the decimal point and return the result as a string.

Function: character-to-string ((c CHARACTER)) : STRING

Convert c into a one-element string and return the result.

Function: stringify ((expression OBJECT)) : STRING

Print expression onto a string and return the result. Printing is done with *printReadably?* set to true and with *printPretty?* set to false.

Function: stringify-in-module ((tree OBJECT) (module MODULE)) : STRING

Stringify a parse tree relative to module, or *module* if no module is specified.

Function: unstringify ((string STRING)) : OBJECT

Read a STELLA expression from string and return the result. This is identical to read-s-expression-from-string.

Function: unstringify-in-module ((string STRING) (module MODULE)) : OBJECT

Unstringify relative to module, or *MODULE* if no module is specified.

6.5 CONS Lists and Trees

Class: CONS : STANDARD-OBJECT

Not documented.

Class Parameter: any-value : OBJECT

Not documented.

Slot: value : (LIKE (ANY-VALUE SELF))

Not documented.

Slot: rest : (CONS OF (LIKE (ANY-VALUE SELF)))

Not documented.

Variable: nil : CONS

Not documented.

Method: CONS empty? (self) : BOOLEAN

Return true iff self equals nil.

Method: CONS non-empty? (self) : BOOLEAN

Return true iff self is not equal to nil.

Function: nil? ((x OBJECT)) : BOOLEAN

Return true iff x equals nil.

Function: equal-cons-trees? ((tree1 OBJECT) (tree2 OBJECT)) : BOOLEAN

Return true iff the cons trees tree1 and tree2 are structurally equivalent. Uses an eql? test.

Method: CONS object-equal? (tree1 (tree2 OBJECT)) : BOOLEAN

Return true iff the cons trees tree1 and tree2 are structurally equivalent. Uses equal? to test equality of subtrees.

Method: CONS equal-hash-code (self) : INTEGER

Return an equal? hash code for self. Note that this is O(N) in the number of elements of self.

Function: cons ((value OBJECT) (rest CONS)) : CONS

Return a cons record that points to value and rest.

Method: CONS first (self) : (LIKE (ANY-VALUE SELF))

Return the first element of self. The first element of self can be set with setf. Note that (first NIL) = null.

Method: CONS second (self) : (LIKE (ANY-VALUE SELF))

Return the second element of self. The second element of self can be set with setf. Note that (second NIL) = null.

Method: CONS third (self) : (LIKE (ANY-VALUE SELF))

Return the third element of self. The third element of self can be set with setf. Note that (third NIL) = null.

Method: CONS fourth (self) : (LIKE (ANY-VALUE SELF))

Return the fourth element of self. The fourth element of self can be set with setf. Note that (fourth NIL) = null.

Method: CONS fifth (self) : (LIKE (ANY-VALUE SELF))

Return the fifth element of self. The fifth element of self can be set with setf. Note, that (fifth NIL) = null.

Method: CONS nth (self (position INTEGER)) : (LIKE (ANY-VALUE SELF))

Return the element of self at position. The nth element of self can be set with setf. Note, that (nth NIL <pos>) = null.

Method: CONS nth-rest (self (position INTEGER)) : (LIKE SELF)

Apply rest position times to self.

Method: CONS last (self) : (LIKE (ANY-VALUE SELF))

Return the last element of self.

Method: CONS but-last (self) : (ITERATOR OF (LIKE (ANY-VALUE SELF)))

Generate all but the last element of the cons list self.

Function: last-cons ((self CONS)) : (CONS OF (LIKE (ANY-VALUE SELF)))

Return the last cons of self.

Method: CONS length (self) : INTEGER

Return the length of the CONS list self.

Method: CONS member? (self (object OBJECT)) : BOOLEAN

Return true iff object is a member of the cons list self (uses an eql? test).

Method: CONS memb? (self (object OBJECT)) : BOOLEAN

Return true iff object is a member of the cons list self (uses an eq? test).

Method: CONS position (self (object OBJECT) (start INTEGER)) : INTEGER

Return the position of object within the cons-list self (counting from zero); or return null if object does not occur within self (uses an eql? test). If start was supplied as non-`null', only consider the sublist starting at start, however, the returned position will always be relative to the entire list.

Method: CONS last-position (self (object OBJECT) (end INTEGER)) : INTEGER

Return the position of object within the cons-list self (counting from zero); or return null if object does not occur within self (uses an eql? test). If start was supplied as non-`null', only consider the sublist ending at end, however, the returned position will always be relative to the entire list.

Method: CONS reverse (self) : (LIKE SELF)

Destructively reverse the members of the cons list self.

Method: CONS remove (self (value OBJECT)) : (LIKE SELF)

Destructively remove all entries in the cons list self that match value. Unless the remaining list is nil, insure that the cons that heads the list is unchanged.

Method: CONS remove-duplicates (self) : (LIKE SELF)

Destructively remove duplicates from self and return the result. Removes all but the first occurrence of items in the list. Preserves the original order of the remaining members. Runs in linear time.

Method: CONS remove-if (self (test? FUNCTION-CODE)) : (LIKE SELF)

Destructively removes all members of the cons list self for which test? evaluates to true. test takes a single argument of type OBJECT and returns true or false. Returns a cons list. In case the first element is removed, the return result should be assigned to a variable.

Method: CONS substitute (self (inValue OBJECT) (outValue OBJECT)) : CONS

Destructively replace each appearance of outValue by inValue in the cons list self.

Method: CONS concatenate (list1 (list2 CONS) &rest (otherLists CONS)) : CONS

Return a cons list consisting of the concatenation of list1, list2, and otherLists. The operation is destructive wrt all but the last list argument which is left intact. The two mandatory parameters allow us to optimize the common binary case by not relying on the somewhat less efficient variable arguments mechanism.

Function: append ((consList1 CONS) (consList2 CONS)) : CONS

Return a cons list representing the concatenation of consList1 and consList2. The concatenation is NOT destructive.

Method: CONS prepend (self (list1 CONS)) : CONS

Return a cons list consisting of the concatenation of list1 and self. A copy of list1 is prepended to self. This operation results in structure sharing of self; to avoid this, self should not be pointed to by anything other than the tail of the prepended copy.

Macro: pushq ((variable SYMBOL) (value OBJECT)) : OBJECT

Push value onto the cons list variable.

Macro: pushq-new ((variable SYMBOL) (value OBJECT)) : OBJECT

Push value onto the cons list variable, unless value is already a member of the list.

Macro: popq ((variable SYMBOL)) : OBJECT

Pops a value from the cons list variable.

Function: cons-list (&rest (values OBJECT)) : CONS

Return a cons list containing values, in order.

Function: list* (&rest (values OBJECT)) : CONS

Return a list of conses that make up the list values, terminated by the last value rather than by nil. Assumes that at least one value is passed in.

Function: copy-cons-list ((self CONS)) : (LIKE SELF)

Return a copy of the cons list self.

Function: copy-cons-tree ((self OBJECT)) : (LIKE SELF)

Return a copy of the cons tree self.

Function: substitute-cons-tree ((tree OBJECT) (newValue OBJECT) (oldValue OBJECT)) : OBJECT

Destructively replace each appearance of oldValue by newValue in the cons tree tree. Return the tree. Uses an eql? test.

Function: search-cons-tree? ((tree OBJECT) (value OBJECT)) : BOOLEAN

Return true iff the value value is embedded within the cons tree tree. Uses an eql? test.

Function: tree-size ((self OBJECT)) : INTEGER

Not documented.

Function: safe-tree-size ((tree CONS)) : INTEGER STRING

Not documented.

Function: cons-tree-nth ((tree CONS) &rest (index INTEGER)) : OBJECT

Access an arbitrary element of tree identified by a path specified as a list of index values. The first index specifies the index-th element of tree, the second index the index-th subelement of that element, etc. Example:

(cons-tree-nth (quote (a (b (c d e) f) g)) 1 1 2) => e

Function: cons-tree-nth-rest ((tree CONS) &rest (index INTEGER)) : CONS

Access an arbitrary sublist of tree identified by a path specified as a list of index values. The first index specifies the index-th element of tree, the second index the index-th subelement of that element, ..., the last index specifies the nth-rest of the previous element (different from cons-tree-nth). Example:

(cons-tree-nth-rest (quote (a (b (c d e) f) g)) 1 1 1) => (d e)

Function: match-cons-tree ((tree OBJECT) (pattern OBJECT) (bindings KEY-VALUE-LIST)) : KEY-VALUE-LIST

Match pattern against tree and return a list of variable bindings if they match, or NULL otherwise. bindings can be NULL or an initial list of bindings to consider. Pattern variables use KIF syntax, i.e., they need to start with a ? character. A single question mark is interpreted as the anonymous variable. Example:

(match-cons-tree (quote (a (b (a d) e) (a d) f g)) (quote (a (?x ?y ?) ?y ? g)) NULL) => |kv|(<?Y,(A D)> <?X,B>)

Variables can't be quoted but quoting can effectively be achieved by inserting to-be-quoted variables bound to themselves into bindings.

Function: cons-tree-match? ((tree OBJECT) (pattern OBJECT)) : BOOLEAN

Predicate version of match-cons-tree (which see).

Method: CONS consify (self) : (CONS OF (LIKE (ANY-VALUE SELF)))

Return self.

Method: CONS allocate-iterator (self) : (CONS-ITERATOR OF (LIKE (ANY-VALUE SELF)))

Not documented.

Method: CONS-ITERATOR next? (self) : BOOLEAN

Not documented.

Method: CONS sort (self (predicate FUNCTION-CODE)) : (CONS OF (LIKE (ANY-VALUE SELF)))

Perform a stable, destructive sort of self according to predicate, and return the result. If predicate has a < semantics, the result will be in ascending order. It is not guaranteed that self will point to the beginning of the sorted result. If predicate is null, a suitable < predicate is chosen depending on the first element of self, and it is assumed that all elements of self have the same type (supported element types are GENERALIZED-SYMBOL, STRING, INTEGER, and FLOAT).

Method: CONS sort-tuples (self (n INTEGER) (predicate FUNCTION-CODE)) : (CONS OF (LIKE (ANY-VALUE SELF)))

Just like sort but assumes each element of self is a tuple (a cons) whose n-th element (0-based) will be used for comparison.

Function: map-null-to-nil ((self CONS)) : (LIKE SELF)

Return nil iff self is null or self otherwise.

Special Variable: *printpretty?* : BOOLEAN

If true conses will be pretty printed.

Special Variable: *printreadably?* : BOOLEAN

If true conses will be printed as readable Stella code.

Special Variable: *printprettycode?* : BOOLEAN

When true pretty-print Stella and translated code. Since (Lisp) pretty-printing is somewhat slow, turning this off speeds up file translation, but it also makes translated output very unreadable.

6.5.1 CONS Lists as Sets

6.5.1 CONS Lists as Sets

Method: CONS subset? (self (otherList CONS)) : BOOLEAN

Return true if every element of self also occurs in otherList. Uses an eql? test and a simple quadratic-time algorithm. Note that this does not check whether self and otherList actually are sets.

Method: CONS equivalent-sets? (self (otherList CONS)) : BOOLEAN

Return true if every element of self occurs in otherList and vice versa. Uses an eql? test and a simple quadratic-time algorithm. Note that this does not check whether self and otherList actually are sets.

Method: CONS union (self (otherList CONS)) : CONS

Return the set union of self and otherList. Uses an eql? test and a simple quadratic-time algorithm. Note that the result is only guaranteed to be a set if both self and otherList are sets.

Method: CONS intersection (self (otherList CONS)) : CONS

Return the set intersection of self and otherList. Uses an eql? test and a simple quadratic-time algorithm. Note that the result is only guaranteed to be a set if both self and otherList are sets.

Method: CONS difference (self (otherList CONS)) : CONS

Return the set difference of self and otherList (i.e., all elements that are in self but not in otherSet). Uses an eql? test and a simple quadratic-time algorithm. Note that the result is only guaranteed to be a set if both self and otherList are sets.

Method: CONS subtract (self (otherList CONS)) : CONS

Return the set difference of self and otherList by destructively removing elements from self that also occur in otherList. Uses an eql? test and a simple quadratic-time algorithm. Note that the result is only guaranteed to be a set if self is a set.

6.6 Lists

Class: LIST : SEQUENCE

Not documented.

Class Parameter: any-value : OBJECT

Not documented.

Slot: the-cons-list : (CONS OF (LIKE (ANY-VALUE SELF)))

Not documented.

Variable: nil-list : LIST

Not documented.

Function: defined-list? ((self LIST)) : BOOLEAN

Return TRUE unless self is NULL or the NIL-LIST.

Function: null-list? ((self LIST)) : BOOLEAN

Return TRUE iff self is NULL or the NIL-LIST.

Method: LIST empty? (self) : BOOLEAN

Return TRUE if the list self has no members.

Method: LIST non-empty? (self) : BOOLEAN

Return TRUE if the list self has at least one member.

Method: LIST object-equal? (x (y OBJECT)) : BOOLEAN

Return TRUE iff the lists x and y are structurally equivalent. Uses equal? to test equality of elements.

Method: LIST equal-hash-code (self) : INTEGER

Return an equal? hash code for self. Note that this is O(N) in the number of elements of self.

Function: list (&rest (values OBJECT)) : LIST

Return a list containing values, in order.

Method: LIST first (self) : (LIKE (ANY-VALUE SELF))

Return the first item in the list self, or NULL if empty.

Method: LIST second (self) : (LIKE (ANY-VALUE SELF))

Return the second item in the list self, or NULL if empty.

Method: LIST third (self) : (LIKE (ANY-VALUE SELF))

Return the third item in the list self, or NULL if empty.

Method: LIST fourth (self) : (LIKE (ANY-VALUE SELF))

Return the fourth item in the list self, or NULL if empty.

Method: LIST fifth (self) : (LIKE (ANY-VALUE SELF))

Return the fifth item in the list self, or NULL if empty.

Method: LIST nth (self (position INTEGER)) : (LIKE (ANY-VALUE SELF))

Return the nth item in the list self, or NULL if empty.

Method: LIST rest (self) : (CONS OF (LIKE (ANY-VALUE SELF)))

Return a cons list of all but the first item in the list self.

Method: LIST last (self) : (LIKE (ANY-VALUE SELF))

Return the last element of self.

Method: LIST but-last (self) : (ITERATOR OF (LIKE (ANY-VALUE SELF)))

Generate all but the last element of the list self.

Method: LIST length (self) : INTEGER

Not documented.

Method: LIST member? (self (object OBJECT)) : BOOLEAN

Return TRUE iff object is a member of the list self (uses an eql? test).

Method: LIST memb? (self (object (LIKE (ANY-VALUE SELF)))) : BOOLEAN

Return TRUE iff object is a member of the cons list self (uses an eq? test).

Method: LIST position (self (object OBJECT) (start INTEGER)) : INTEGER

Return the position of object within the list self (counting from zero); or return NULL if object does not occur within self (uses an eql? test). If start was supplied as non-NULL, only consider the sublist starting at start, however, the returned position will always be relative to the entire list.

Method: LIST last-position (self (object OBJECT) (end INTEGER)) : INTEGER

Return the position of object within the list self (counting from zero); or return NULL if object does not occur within self (uses an eql? test). If end was supplied as non-NULL, only consider the sublist ending at end, however, the returned position will always be relative to the entire list.

Method: LIST insert (self (value (LIKE (ANY-VALUE SELF)))) :

Add value to the front of the list self.

Method: LIST push (self (value (LIKE (ANY-VALUE SELF)))) :

Add value to the front of the list self.

Method: LIST insert-new (self (value (LIKE (ANY-VALUE SELF)))) :

Add value to the front of the list self unless its already a member.

Method: LIST insert-last (self (value (LIKE (ANY-VALUE SELF)))) :

Insert value as the last entry in the list self.

Method: LIST reverse (self) : (LIKE SELF)

Reverse the members of self (in place).

Method: LIST remove (self (value (LIKE (ANY-VALUE SELF)))) : (LIKE SELF)

Destructively remove all entries in self that match value.

Method: LIST remove-duplicates (self) : (LIKE SELF)

Destructively remove duplicates from self and return the result. Preserves the original order of the remaining members.

Method: LIST remove-deleted-members (self) : (LIKE SELF)

Not documented.

Method: LIST remove-if (self (test? FUNCTION-CODE)) : (LIKE SELF)

Destructively remove all members of the list self for which test? evaluates to TRUE. test takes a single argument of type OBJECT and returns TRUE or FALSE. Returns self.

Method: LIST pop (self) : (LIKE (ANY-VALUE SELF))

Remove and return the first element in the list self. Return NULL if the list is empty.

Method: LIST substitute (self (inValue OBJECT) (outValue OBJECT)) : (LIKE SELF)

Destructively replace each appearance of outValue by inValue in the list self.

Method: LIST concatenate (list1 (list2 LIST) &rest (otherLists LIST)) : LIST

Copy list2 and all otherLists onto the end of list1. The operation is destructive wrt list1, but leaves all other lists intact. The two mandatory parameters allow us to optimize the common binary case by not relying on the somewhat less efficient variable arguments mechanism.

Method: LIST prepend (self (list2 LIST)) : (LIKE SELF)

Copy list2 onto the front of the list self. The operation is destructive wrt self, but leaves list2 intact.

Method: LIST copy (self) : (LIST OF (LIKE (ANY-VALUE SELF)))

Return a copy of the list self. The conses in the copy are freshly allocated.

Method: LIST clear (self) :

Make self an empty list.

Method: LIST consify (self) : (CONS OF (LIKE (ANY-VALUE SELF)))

Return a list of elements in self.

Method: LIST allocate-iterator (self) : (LIST-ITERATOR OF (LIKE (ANY-VALUE SELF)))

Not documented.

Method: LIST-ITERATOR next? (self) : BOOLEAN

Not documented.

Method: LIST sort (self (predicate FUNCTION-CODE)) : (LIST OF (LIKE (ANY-VALUE SELF)))

Perform a stable, destructive sort of self according to predicate, and return the result. If predicate has a < semantics, the result will be in ascending order. If predicate is NULL, a suitable < predicate is chosen depending on the first element of self, and it is assumed that all elements of self have the same type (supported element types are GENERALIZED-SYMBOL, STRING, INTEGER, and FLOAT).

Function: map-null-to-nil-list ((self LIST)) : LIST

Return NIL-LIST iff self is NULL or self otherwise.

6.6.1 Lists as Sets

6.6.1 Lists as Sets

Similar to CONS lists LIST's can also be treated as sets and support the set manipulations below. Note that LIST constructors do not check for proper set-hood and may have surprising results if a list contains duplicate elements.

Method: LIST subset? (self (otherList LIST)) : BOOLEAN

Return true if every element of self also occurs in otherList. Uses an eql? test and a simple quadratic-time algorithm. Note that this does not check whether self and otherList actually are sets.

Method: LIST equivalent-sets? (self (otherList LIST)) : BOOLEAN

Return true if every element of self occurs in otherList and vice versa. Uses an eql? test and a simple quadratic-time algorithm. Note that this does not check whether self and otherList actually are sets.

Method: LIST union (self (otherList LIST)) : LIST

Return the set union of self and otherList. Uses an eql? test and a simple quadratic-time algorithm. Note that the result is only guaranteed to be a set if both self and otherList are sets.

Method: LIST intersection (self (otherList LIST)) : LIST

Return the set intersection of self and otherList. Uses an eql? test and a simple quadratic-time algorithm. Note that the result is only guaranteed to be a set if both self and otherList are sets.

Method: LIST difference (self (otherList LIST)) : LIST

Return the set difference of self and otherList (i.e., all elements that are in self but not in otherSet). Uses an eql? test and a simple quadratic-time algorithm. Note that the result is only guaranteed to be a set if both self and otherList are sets.

Method: LIST subtract (self (otherList LIST)) : LIST

Return the set difference of self and otherList by destructively removing elements from self that also occur in otherList. Uses an eql? test and a simple quadratic-time algorithm. Note that the result is only guaranteed to be a set if self is a set.

SET is a subclass of LIST that overrides certain LIST operations to prevent duplicate elements. The following additional or modified operations are supported:

Class: SET : LIST, SET-MIXIN

Not documented.

Class Parameter: any-value : OBJECT

Not documented.

Method: SET insert (self (value (LIKE (ANY-VALUE SELF)))) :

Add value to the set self unless it is already a member.

Method: SET push (self (value (LIKE (ANY-VALUE SELF)))) :

Add value to the front of set self unless it is already a member.

Method: SET insert-last (self (value (LIKE (ANY-VALUE SELF)))) :

Add value to the end of set self unless it is already a member.

Method: SET substitute (self (new OBJECT) (old OBJECT)) : (LIKE SELF)

Destructively replace old with new in the set self unless new is already a member.

Method: SET concatenate (set1 (set2 LIST) &rest (otherSets LIST)) : SET

Union set2 and all otherSets onto the end of set1. The operation is destructive wrt set1, but leaves all other sets intact. The two mandatory parameters allow us to optimize the common binary case by not relying on the somewhat less efficient variable arguments mechanism.

Method: SET object-equal? (x (y OBJECT)) : BOOLEAN

Return TRUE iff x and y are SET's with equivalent members. Uses equal? to test equality of elements. This is more general than equivalent-sets?, since that only uses an eql? test.

Method: SET equal-hash-code (self) : INTEGER

Return an equal? hash code for self. Note that this is O(N) in the number of elements of self.

Function: set (&rest (values OBJECT)) : SET

Return a set containing values, in order.

6.7 Property and Key-Value Lists

Class: PROPERTY-LIST : DICTIONARY

Not documented.

Class Parameter: any-key : OBJECT

Not documented.

Class Parameter: any-value : OBJECT

Not documented.

Slot: the-plist : CONS

Not documented.

Method: PROPERTY-LIST empty? (self) : BOOLEAN

Not documented.

Method: PROPERTY-LIST non-empty? (self) : BOOLEAN

Not documented.

Method: PROPERTY-LIST object-equal? (x (y OBJECT)) : BOOLEAN

Return TRUE if x and y represent the same set of key/value pairs..

Method: PROPERTY-LIST equal-hash-code (self) : INTEGER

Return an equal? hash code for self. Note that this is O(N) in the number of entries of self.

Method: PROPERTY-LIST length (self) : INTEGER

Not documented.

Method: PROPERTY-LIST lookup (self (key (LIKE (ANY-KEY SELF)))) : (LIKE (ANY-VALUE SELF))

Not documented.

Method: PROPERTY-LIST insert-at (self (key (LIKE (ANY-KEY SELF))) (value (LIKE (ANY-VALUE SELF)))) :

Insert the entry <`key', value> into the property list self. If a previous entry existed with key key, that entry is replaced.

Method: PROPERTY-LIST remove-at (self (key (LIKE (ANY-KEY SELF)))) : OBJECT

Remove the entry that matches the key key. Return the value of the matching entry, or NULL if there is no matching entry. Assumes that at most one entry matches key.

Method: PROPERTY-LIST copy (self) : (LIKE SELF)

Return a copy of the list self. The conses in the copy are freshly allocated.

Method: PROPERTY-LIST clear (self) :

Make self an empty property list.

Method: PROPERTY-LIST allocate-iterator (self) : (PROPERTY-LIST-ITERATOR OF (LIKE (ANY-KEY SELF)) (LIKE (ANY-VALUE SELF)))

Not documented.

Method: PROPERTY-LIST-ITERATOR next? (self) : BOOLEAN

Not documented.

Class: KV-CONS : STANDARD-OBJECT

Not documented.

Class Parameter: any-key : OBJECT

Not documented.

Class Parameter: any-value : OBJECT

Not documented.

Slot: key : OBJECT

Not documented.

Slot: value : OBJECT

Not documented.

Slot: rest : KV-CONS

Not documented.

Function: kv-cons ((key OBJECT) (value OBJECT) (rest KV-CONS)) : KV-CONS

Create, fill-in, and return a new KV-CONS.

Function: copy-kv-cons-list ((kvconslist KV-CONS)) : KV-CONS

Return a copy of the cons list consList.

Class: KEY-VALUE-LIST : DICTIONARY

Not documented.

Class Parameter: any-key : OBJECT

Not documented.

Class Parameter: any-value : OBJECT

Not documented.

Slot: the-kv-list : KV-CONS

Not documented.

Method: KEY-VALUE-LIST empty? (self) : BOOLEAN

Not documented.

Method: KEY-VALUE-LIST non-empty? (self) : BOOLEAN

Not documented.

Method: KEY-VALUE-LIST object-equal? (x (y OBJECT)) : BOOLEAN

Return TRUE if x and y represent the same set of key/value pairs.

Method: KEY-VALUE-LIST equal-hash-code (self) : INTEGER

Return an equal? hash code for self. Note that this is O(N) in the number of entries of self.

Method: KEY-VALUE-LIST length (self) : INTEGER

Not documented.

Method: KEY-VALUE-LIST lookup (self (key (LIKE (ANY-KEY SELF)))) : (LIKE (ANY-VALUE SELF))

Not documented.

Method: KEY-VALUE-LIST reverse (self) : (LIKE SELF)

Destructively reverse the members of the list self.

Method: KEY-VALUE-LIST insert-at (self (key (LIKE (ANY-KEY SELF))) (value (LIKE (ANY-VALUE SELF)))) :

Insert the entry <`key', value> into the association self. If a previous entry existed with key key, that entry is replaced.

Method: KEY-VALUE-LIST remove-at (self (key (LIKE (ANY-KEY SELF)))) : OBJECT

Remove the entry that matches the key key. Return the value of the matching entry, or NULL if there is no matching entry. Assumes that at most one entry matches key.

Method: KEY-VALUE-LIST insert-entry (self (key (LIKE (ANY-KEY SELF))) (value (LIKE (ANY-VALUE SELF)))) :

Insert an entry <`key',value> to self unless an identical entry already exists. This can generate duplicate entries for key.

Method: KEY-VALUE-LIST remove-entry (self (key (LIKE (ANY-KEY SELF))) (value (LIKE (ANY-VALUE SELF)))) :

Remove the entry that matches <`key',value>. Assumes that more than one entry can match key.

Method: KEY-VALUE-LIST push (self (value KV-CONS)) :

Make value be the new first element of self. Note that the rest slot of value should be null, since it will be overwritten. This might duplicate an existing entry. If a previous entry existed with the same key as value, that entry is retained, but shadowed by this new entry.

Method: KEY-VALUE-LIST kv-push (self (key (LIKE (ANY-KEY SELF))) (value (LIKE (ANY-VALUE SELF)))) :

Add a new entry <`key', value> to the front of the association self. This might duplicate an existing entry. If a previous entry existed with key key, that entry is retained, but shadowed by this new entry.

Method: KEY-VALUE-LIST pop (self) : (LIKE (ANY-VALUE SELF))

Remove and return the value of the first element of the kv-list self. It does NOT return the KV-CONS object. Return null if the list is empty.

Method: KEY-VALUE-LIST copy (self) : (LIKE SELF)

Return a copy of the kv-list self. The kv-conses in the copy are freshly allocated.

Method: KEY-VALUE-LIST clear (self) :

Make self an empty dictionary.

Method: KEY-VALUE-LIST consify (self) : (CONS OF (LIKE (ANY-VALUE SELF)))

Return a list of key-value pairs in self.

Method: KEY-VALUE-LIST allocate-iterator (self) : (KV-LIST-ITERATOR OF (LIKE (ANY-KEY SELF)) (LIKE (ANY-VALUE SELF)))

Not documented.

Method: KV-LIST-ITERATOR next? (self) : BOOLEAN

Not documented.

6.8 Vectors

Class: VECTOR : SEQUENCE

Not documented.

Class Parameter: any-value : OBJECT

Not documented.

Slot: array-size : INTEGER

Not documented.

Slot: the-array : (NATIVE-VECTOR OF (LIKE (ANY-VALUE SELF)))

Not documented.

Class: EXTENSIBLE-VECTOR : VECTOR

Not documented.

Method: VECTOR empty? (self) : BOOLEAN

Return true if self has length 0.

Method: VECTOR non-empty? (self) : BOOLEAN

Return true if self has length > 0.

Method: VECTOR object-equal? (x (y OBJECT)) : BOOLEAN

Return TRUE iff the vectors x and y are structurally equivalent. Uses equal? to test equality of elements.

Method: VECTOR equal-hash-code (self) : INTEGER

Return an equal? hash code for self.

Function: vector (&rest (values OBJECT)) : VECTOR

Return a vector containing values, in order.

Method: VECTOR first (self) : (LIKE (ANY-VALUE SELF))

Not documented.

Method: VECTOR second (self) : (LIKE (ANY-VALUE SELF))

Not documented.

Method: VECTOR third (self) : (LIKE (ANY-VALUE SELF))

Not documented.

Method: VECTOR fourth (self) : (LIKE (ANY-VALUE SELF))

Not documented.

Method: VECTOR fifth (self) : (LIKE (ANY-VALUE SELF))

Not documented.

Method: VECTOR nth (self (position INTEGER)) : (LIKE (ANY-VALUE SELF))

Not documented.

Method: VECTOR last (self) : (LIKE (ANY-VALUE SELF))

Return the last item in the vector self.

Method: VECTOR but-last (self) : (ITERATOR OF (LIKE (ANY-VALUE SELF)))

Generate all but the last element of the vector self.

Method: VECTOR length (self) : INTEGER

Not documented.

Method: VECTOR member? (self (object OBJECT)) : BOOLEAN

Not documented.

Method: VECTOR position (self (object OBJECT) (start INTEGER)) : INTEGER

Return the position of object within the vector self (counting from zero); or return null if object does not occur within self (uses an eql? test). If start was supplied as non-`null', only consider the portion starting at start, however, the returned position will always be relative to the entire vector.

Method: VECTOR last-position (self (object OBJECT) (end INTEGER)) : INTEGER

Return the position of object within the vector self (counting from zero); or return null if object does not occur within self (uses an eql? test). If end was supplied as non-`null', only consider the portion ending at index end, however, the returned position will always be relative to the entire vector.

Method: VECTOR insert-at (self (offset INTEGER) (value (LIKE (ANY-VALUE SELF)))) :

Not documented.

Method: VECTOR copy (self) : (VECTOR OF (LIKE (ANY-VALUE SELF)))

Return a copy of the vector self.

Method: VECTOR clear (self) :

Not documented.

Function: resize-vector ((self VECTOR) (size INTEGER)) :

Change the size of self to size. If size is smaller than the current size of self the vector will be truncated. Otherwise, the internal array of self will be grown to size and unused elements will be initialized to NULL.

Method: VECTOR consify (self) : (CONS OF (LIKE (ANY-VALUE SELF)))

Return a list of elements in self.

Method: EXTENSIBLE-VECTOR insert-at (self (offset INTEGER) (value (LIKE (ANY-VALUE SELF)))) :

Not documented.

Method: VECTOR-SEQUENCE insert (self (value (LIKE (ANY-VALUE SELF)))) :

Append value to the END of the sequence self. Resize the array if necessary.

Method: VECTOR-SEQUENCE remove (self (value (LIKE (ANY-VALUE SELF)))) : VECTOR-SEQUENCE

Remove value from the sequence self, and left shift the values after it to close the gap.

Method: VECTOR-SEQUENCE length (self) : INTEGER

Not documented.

6.9 Hash Tables

Class: HASH-TABLE : ABSTRACT-HASH-TABLE

Not documented.

Class Parameter: any-key : OBJECT

Not documented.

Class Parameter: any-value : OBJECT

Not documented.

Class: STRING-HASH-TABLE : ABSTRACT-HASH-TABLE

Not documented.

Class Parameter: any-key : STRING

Not documented.

Class Parameter: any-value : OBJECT

Not documented.

Class: STRING-TO-INTEGER-HASH-TABLE : ABSTRACT-HASH-TABLE

Not documented.

Class Parameter: any-key : STRING

Not documented.

Class Parameter: any-value : INTEGER

Not documented.

Class: INTEGER-HASH-TABLE : ABSTRACT-HASH-TABLE

Not documented.

Class Parameter: any-key : INTEGER

Not documented.

Class Parameter: any-value : OBJECT

Not documented.

Class: FLOAT-HASH-TABLE : ABSTRACT-HASH-TABLE

Not documented.

Class Parameter: any-key : FLOAT

Not documented.

Class Parameter: any-value : OBJECT

Not documented.

Method: HASH-TABLE lookup (self (key (LIKE (ANY-KEY SELF)))) : (LIKE (ANY-VALUE SELF))

Not documented.

Method: HASH-TABLE insert-at (self (key (LIKE (ANY-KEY SELF))) (value (LIKE (ANY-VALUE SELF)))) :

Not documented.

Method: HASH-TABLE remove-at (self (key (LIKE (ANY-KEY SELF)))) :

Not documented.

Method: STRING-HASH-TABLE lookup (self (key STRING)) : (LIKE (ANY-VALUE SELF))

Not documented.

Method: STRING-HASH-TABLE insert-at (self (key STRING) (value OBJECT)) :

Not documented.

Method: STRING-HASH-TABLE remove-at (self (key STRING)) :

Not documented.

Method: STRING-TO-INTEGER-HASH-TABLE lookup (self (key STRING)) : INTEGER

Not documented.

Method: STRING-TO-INTEGER-HASH-TABLE insert-at (self (key STRING) (value INTEGER)) :

Not documented.

Method: INTEGER-HASH-TABLE lookup (self (key INTEGER)) : (LIKE (ANY-VALUE SELF))

Not documented.

Method: INTEGER-HASH-TABLE insert-at (self (key INTEGER) (value OBJECT)) :

Not documented.

Method: FLOAT-HASH-TABLE insert-at (self (key FLOAT) (value OBJECT)) :

Not documented.

STELLA provides its own implementation of hash tables for cases where language-native implementations are not available, or where additional features are needed.

Class: STELLA-HASH-TABLE : ABSTRACT-HASH-TABLE

Not documented.

Class Parameter: any-key : OBJECT

Not documented.

Class Parameter: any-value : OBJECT

Not documented.

Slot: the-table : (ARRAY SIZE () OF KV-CONS)

Not documented.

Slot: size : INTEGER

Not documented.

Slot: initial-size : INTEGER

If supplied, the initial hash table will be sized to hold at least that many elements.

Slot: free-elements : INTEGER

Not documented.

Slot: equal-test? : BOOLEAN

If true use equal? as the equality test and equal-hash-code as the hash function, otherwise, use eql? and hash-code (the default).

Method: STELLA-HASH-TABLE lookup (self (key (LIKE (ANY-KEY SELF)))) : (LIKE (ANY-VALUE SELF))

Lookup the entry identified by key in self and return its value, or NULL if no such entry exists. Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method: STELLA-HASH-TABLE insert-at (self (key (LIKE (ANY-KEY SELF))) (value (LIKE (ANY-VALUE SELF)))) :

Set the value of the entry identified by key in self to value or add a new entry if no entry with key exists yet. Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method: STELLA-HASH-TABLE remove-at (self (key (LIKE (ANY-KEY SELF)))) :

Remove the entry identified by key from self. Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method: STELLA-HASH-TABLE length (self) : INTEGER

Return the number of entries in self.

Method: STELLA-HASH-TABLE empty? (self) : BOOLEAN

Return TRUE if self has zero entries.

Method: STELLA-HASH-TABLE non-empty? (self) : BOOLEAN

Return TRUE if self has at least 1 entry.

Method: STELLA-HASH-TABLE copy (self) : (LIKE SELF)

Return a copy of the hash table self. The bucket table and buckets are freshly allocated, however, the keys and values of entries are not copied themselves (similar to what we do for lists, etc.).

Method: STELLA-HASH-TABLE clear (self) :

Remove all entries from self. This will result in a re-initialization of the table upon the first insertion into self.

Method: STELLA-HASH-TABLE consify (self) : (CONS OF CONS)

Collect all entries of self into a cons list of (<key> <value>) pairs and return the result.

Method: STELLA-HASH-TABLE object-equal? (x (y OBJECT)) : BOOLEAN

Return TRUE if x and y represent the same set of key/value pairs.

Method: STELLA-HASH-TABLE equal-hash-code (self) : INTEGER

Return an equal? hash code for self. Note that this is O(N) in the number of entries of self.

Method: STELLA-HASH-TABLE allocate-iterator (self) : (STELLA-HASH-TABLE-ITERATOR OF (LIKE (ANY-KEY SELF)) (LIKE (ANY-VALUE SELF)))

Allocate an iterator for self.

Hashing objects into STELLA hash tables is accomplished via hash-code and equal-hash-code methods. These methods are implemented for all built-in STELLA types but are user extensible for cases where special functionality on user-defined objects is needed. Defining new hash-code methods should only be necessary if new wrapper types are defined, since for all types descending from STANDARD-OBJECT the built-in method should be adequate.

Function: object-hash-code ((self OBJECT)) : INTEGER

Return a hash code for self (can be negative). Two objects that are eq? are guaranteed to generate the same hash code. Two objects that are not eq? do not necessarily generate different hash codes. Similar to hash-code but always hashes on the address of self even if it is a wrapper.

Method: OBJECT hash-code (self) : INTEGER

Return a hash code for self (can be negative). Two objects that are eql? are guaranteed to generate the same hash code. Two objects that are not eql? do not necessarily generate different hash codes.

Method: STANDARD-OBJECT hash-code (self) : INTEGER

Not documented.

Method: STRING-WRAPPER hash-code (self) : INTEGER

Not documented.

Method: INTEGER-WRAPPER hash-code (self) : INTEGER

Not documented.

Method: FLOAT-WRAPPER hash-code (self) : INTEGER

Not documented.

Method: CHARACTER-WRAPPER hash-code (self) : INTEGER

Not documented.

Method: BOOLEAN-WRAPPER hash-code (self) : INTEGER

Not documented.

Method: STRING hash-code (self) : INTEGER

Not documented.

Method: INTEGER hash-code (self) : INTEGER

Not documented.

Method: FLOAT hash-code (self) : INTEGER

Not documented.

Method: CHARACTER hash-code (self) : INTEGER

Not documented.

Method: OBJECT equal-hash-code (self) : INTEGER

Return a hash code for self (can be negative). Two objects that are equal? are guaranteed to generate the same hash code (provided, that writers of object-equal? methods also implemented the appropriate equal-hash-code method). Two objects that are not equal?do not necessarily generate different hash codes.

The following low-level utilities are available to implement specialized hashing schemes or for defining new versions of equal-hash-code.

Function: hashmod ((code INTEGER) (size INTEGER)) : INTEGER

Map the hash code code onto a bucket index for a hash table of size (i.e., onto the interval [0..size-1]. This is just like rem for positive hash codes but also works for negative hash codes by mapping those onto a positive number first. Note, that the sign conversion mapping is not equivalent to calling the abs function (it simply masks the sign bit for speed) and therefore really only makes sense for hash codes.

Function: rotate-hash-code ((arg INTEGER)) : INTEGER

Rotate arg to the right by 1 position. This means shift arg to the right by one and feed in args bit zero from the left. In Lisp the result will stay in positive FIXNUM range. In C++ and Java this might return a negative value which might be equal to NULL-INTEGER. Important: to make this inlinable, it must be called with an atom (i.e., constant or variable) as its argument. This function is primarily useful for hashing sequences of items where the hash code should take the sequential order of elements into account (e.g., lists).

6.10 Key Value Maps

KEY-VALUE-MAP is a full-featured dictionary class that supports eql? or extensible equal? equality tests, O(1) access operations even for large numbers of entries by using a hash table, light-weight KV-CONS representation for small tables and iteration even if the dictionary is represented by a hash table (note that in STELLA we cannot iterate over regular HASH-TABLE's, since native Lisp hash tables do not allow us to implement a hash table iterator). Since large KEY-VALUE-MAP's are implemented via STELLA-HASH-TABLE's, we can support iteration.

Class: KEY-VALUE-MAP : DICTIONARY

Full-featured dictionary class that supports eql? or equal? equality tests, O(1) access operations even for large numbers of entries by using a hash table, light-weight KV-CONS representation for small tables and iteration even if the dictionary is represented by a hash table.

Slot: the-map : OBJECT

Not documented.

Slot: equal-test? : BOOLEAN

If true use equal? as the equality test (and equal-hash-code as the hash function), otherwise, use eql? (and hash-code) (the default).

Slot: initial-size : INTEGER

If supplied, the initial table will be sized to hold at least that many elements.

Slot: crossover-point : INTEGER

Not documented.

Method: KEY-VALUE-MAP lookup (self (key (LIKE (ANY-KEY SELF)))) : (LIKE (ANY-VALUE SELF))

Lookup the entry identified by key in self and return its value, or NULL if no such entry exists. Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method: KEY-VALUE-MAP insert-at (self (key (LIKE (ANY-KEY SELF))) (value (LIKE (ANY-VALUE SELF)))) :

Set the value of the entry identified by key in self to value or add a new entry if no entry with key exists yet. Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method: KEY-VALUE-MAP remove-at (self (key (LIKE (ANY-KEY SELF)))) :

Remove the entry identified by key from self. Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method: KEY-VALUE-MAP length (self) : INTEGER

Return the number of entries in self.

Method: KEY-VALUE-MAP empty? (self) : BOOLEAN

Return TRUE if self has zero entries.

Method: KEY-VALUE-MAP non-empty? (self) : BOOLEAN

Return TRUE if self has at least 1 entry.

Method: KEY-VALUE-MAP copy (self) : (LIKE SELF)

Return a copy of the map self. All entries are freshly allocated, however, the keys and values of entries are not copied themselves (similar to what we do for lists, etc.).

Method: KEY-VALUE-MAP clear (self) :

Reset self to have zero entries.

Method: KEY-VALUE-MAP allocate-iterator (self) : (DICTIONARY-ITERATOR OF (LIKE (ANY-KEY SELF)) (LIKE (ANY-VALUE SELF)))

Allocate an iterator for self. The only modifying operations allowed during iteration are removal of the current element or changing its value. All other removal or insertion operations might lead to corruption or undefined results.

Method: KEY-VALUE-MAP consify (self) : CONS

Collect all entries of self into a cons list of (<key> <value>) pairs and return the result.

Method: KEY-VALUE-MAP object-equal? (x (y OBJECT)) : BOOLEAN

Return TRUE if x and y represent the same set of key/value pairs.

Method: KEY-VALUE-MAP equal-hash-code (self) : INTEGER

Return an equal? hash code for self. Note that this is O(N) in the number of entries of self.

6.11 Hash Sets

HASH-SET is a full-featured set class that supports eql? or extensible equal? equality tests, O(1) insert and member? operations, O(N) intersection etc. operations even for large numbers of entries by using a STELLA hash table, light-weight KV-CONS representation for small sets and iteration even if the set is represented by a hash table. The only minor drawback right now is that we waste one value slot per entry, since we piggy-back off KEY-VALUE-MAP's, however, that wastes at most 25% space.

Class: HASH-SET : KEY-VALUE-MAP, SET-MIXIN

Full-featured set class that supports eql? or equal? equality tests, O(1) insert and member? operations & O(N) intersection etc. operations even for large numbers of entries by using a hash table, light-weight KV-CONS representation for small sets and iteration even if the set is represented by a hash table. The only minor drawback right now is that this wastes a value slot per entry, since we piggy-back off KEY-VALUE-MAP's, however, that wastes at most 25% space.

Function: hash-set (&rest (values OBJECT)) : HASH-SET

Return an eql? HASH-SET containing values.

Method: HASH-SET member? (self (object OBJECT)) : BOOLEAN

Return TRUE iff object is a member of the set self. Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method: HASH-SET insert (self (value (LIKE (ANY-VALUE SELF)))) :

Add value to the set self unless it is already a member. Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method: HASH-SET remove (self (value (LIKE (ANY-VALUE SELF)))) : (LIKE SELF)

Destructively remove value from the set self if it is a member and return self. Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method: HASH-SET remove-if (self (test? FUNCTION-CODE)) : (LIKE SELF)

Destructively remove all elements of the set self for which test? evaluates to TRUE. test? takes a single argument of type OBJECT and returns TRUE or FALSE. Returns self.

Method: HASH-SET pop (self) : (LIKE (ANY-VALUE SELF))

Remove and return an arbitrary element of the set self. Return NULL if the set is empty. Performance note: for large sets implemented via hash tables it takes O(N) to empty out the set with repeated calls to pop, since the emptier the table gets, the longer it takes to find an element. Therefore, it is usually better to use iteration with embedded removals for such cases.

Method: HASH-SET substitute (self (new OBJECT) (old OBJECT)) : (LIKE SELF)

Destructively replace old with new in the set self unless new is already a member. Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method: HASH-SET copy (self) : (LIKE SELF)

Return a copy of the set self. All entries are freshly allocated, however, the values are not copied themselves (similar to what we do for lists, etc.).

Method: HASH-SET consify (self) : (CONS OF (LIKE (ANY-VALUE SELF)))

Collect all entries of self into a cons list and return the result.

Method: HASH-SET subset? (self (otherSet HASH-SET)) : BOOLEAN

Return true if every element of self also occurs in otherSet. Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method: HASH-SET equivalent-sets? (self (otherSet HASH-SET)) : BOOLEAN

Return true if every element of self occurs in otherSet and vice versa. Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method: HASH-SET intersection (self (otherSet HASH-SET)) : HASH-SET

Return the set intersection of self and otherSet as a new set. Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method: HASH-SET union (self (otherSet HASH-SET)) : HASH-SET

Return the set union of self and otherSet as a new set. Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method: HASH-SET difference (self (otherSet HASH-SET)) : HASH-SET

Return the set difference of self and otherSet as a new set (i.e., all elements that are in self but not in otherSet). Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method: HASH-SET subtract (self (otherSet HASH-SET)) : HASH-SET

Return the set difference of self and otherSet by destructively removing elements from self that also occur in otherSet. Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method: HASH-SET object-equal? (x (y OBJECT)) : BOOLEAN

Return TRUE iff sets x and y are HASH-SET's with equivalent members. Uses an eql? test by default or equal? if equal-test? of self is TRUE. This is equivalent to calling equivalent-sets?.

Method: HASH-SET equal-hash-code (self) : INTEGER

Return an equal? hash code for self. Note that this is O(N) in the number of elements of self.

6.12 Iterators

Method: ITERATOR empty? (self) : BOOLEAN

Return TRUE if the sequence represented by self has no elements. Side-effect free.

Method: ITERATOR member? (self (value OBJECT)) : BOOLEAN

Iterate over values of self, returning TRUE if one of them is eql to 'value.

Method: ABSTRACT-ITERATOR length (self) : INTEGER

Iterate over self, and count how many items there are. Bad idea if self iterates over an infinite collection, since in that case it will run forever.'

Method: ITERATOR pop (self) : (LIKE (ANY-VALUE SELF))

Return the first item of the sequence represented by self, or NULL if it is empty. Destructively uses up the first iteration element.

Method: ITERATOR advance (self (n INTEGER)) : (LIKE SELF)

Return self after skipping over the first n elements in the (remainder of the) iteration.

Method: ITERATOR concatenate (iterator1 (iterator2 ITERATOR) &rest (otherIterators ITERATOR)) : ALL-PURPOSE-ITERATOR

Return an iterator that first generates all values of iterator1, then those of iterator2, and then those of all otherIterators. The generated values can be filtered by supplying a filter function to the resulting iterator.

Method: ITERATOR consify (self) : (CONS OF (LIKE (ANY-VALUE SELF)))

Return a list of elements generated by self.

Method: ALL-PURPOSE-ITERATOR next? (self) : BOOLEAN

Apply the stored next? function to self.

6.13 Symbols

Function: lookup-symbol ((name STRING)) : SYMBOL

Return the first symbol with name visible from the current module.

Function: intern-symbol ((name STRING)) : SYMBOL

Return a newly-created or existing symbol with name name.

Function: unintern-symbol ((self SYMBOL)) :

Remove self from its home module and the symbol table.

Function: lookup-symbol-in-module ((name STRING) (module MODULE) (local? BOOLEAN)) : SYMBOL

Return the first symbol with name visible from module. If local? only consider symbols directly interned in module. If module is null, use *MODULE* instead.

Function: intern-symbol-in-module ((name STRING) (module MODULE) (local? BOOLEAN)) : SYMBOL

Look for a symbol named name in module (if local? do not consider inherited modules). If none exists, intern it locally in module. Return the existing or newly-created symbol.

Function: intern-derived-symbol ((baseSymbol GENERALIZED-SYMBOL) (newName STRING)) : SYMBOL

Return a newly-created or existing symbol with name newName which is interned in the same module as baseSymbol.

Function: visible-symbol? ((self SYMBOL)) : BOOLEAN

Return true if self is visible from the current module.

Function: lookup-visible-symbols-in-module ((name STRING) (module MODULE) (enforceShadowing? BOOLEAN)) : (CONS OF SYMBOL)

Return the list of symbols with name visible from module. More specific symbols (relative to the module precedence order defined by visible-modules) come earlier in the list. If module is null, start from *MODULE* instead. If enforceShadowing? is true, do not return any symbols that are shadowed due to some :SHADOW declaration.

Function: import-symbol ((symbol SYMBOL) (module MODULE)) : SYMBOL

Import symbol into module and return the imported symbol. Signal an error if a different symbol with the same name already exists locally in module. Any symbol with the same name visible in module by inheritance will be shadowed by the newly imported symbol.

Function: safe-import-symbol ((symbol SYMBOL) (module MODULE)) : SYMBOL

Safe version of import-symbol (which see). Only imports symbol if no symbol with that name is currently interned or visible in module. Returns symbol if it was imported or the conflicting symbol in module otherwise.

Function: lookup-surrogate ((name STRING)) : SURROGATE

Return the first surrogate with name visible from the current module.

Function: intern-surrogate ((name STRING)) : SURROGATE

Return a newly-created or existing surrogate with name name.

Function: unintern-surrogate ((self SURROGATE)) :

Remove self from its home module and the surrogate table.

Function: lookup-surrogate-in-module ((name STRING) (module MODULE) (local? BOOLEAN)) : SURROGATE

Return the first surrogate with name visible from module. If local? only consider surrogates directly interned in module. If module is null, use *MODULE* instead.

Function: intern-surrogate-in-module ((name STRING) (module MODULE) (local? BOOLEAN)) : SURROGATE

Look for a symbol named name in module (if local? do not consider inherited modules). If none exists, intern it locally in module. Return the existing or newly-created symbol.

Function: intern-derived-surrogate ((baseSymbol GENERALIZED-SYMBOL) (newName STRING)) : SURROGATE

Return a newly-created or existing surrogate with name newName which is interned in the same module as baseSymbol.

Function: visible-surrogate? ((self SURROGATE)) : BOOLEAN

Return true if self is visible from the current module.

Function: lookup-visible-surrogates-in-module ((name STRING) (module MODULE) (enforceShadowing? BOOLEAN)) : (CONS OF SURROGATE)

Return the list of surrogates with name visible from module. More specific surrogates (relative to the module precedence order defined by visible-modules) come earlier in the list. If module is null, start from *MODULE* instead. If enforceShadowing? is true, do not return any surrogates that are shadowed due to some :SHADOW declaration.

Function: import-surrogate ((surrogate SURROGATE) (module MODULE)) : SURROGATE

Import surrogate into module and return the imported surrogate. Signal an error if a different surrogate with the same name already exists locally in module. Any surrogate with the same name visible in module by inheritance will be shadowed by the newly imported surrogate.

Function: safe-import-surrogate ((surrogate SURROGATE) (module MODULE)) : SURROGATE

Safe version of import-surrogate (which see). Only imports surrogate if no surrogate with that name is currently interned or visible in module. Returns surrogate if it was imported or the conflicting surrogate in module otherwise.

Function: lookup-keyword ((name STRING)) : KEYWORD

Return the keyword with name if it exists.

Function: intern-keyword ((name STRING)) : KEYWORD

Return a newly-created or existing keyword with name name. Storage note: a COPY of name is stored in the keyword

Function: gensym ((prefix STRING)) : SYMBOL

Return a transient symbol with a name beginning with prefix and ending with a globally gensym'd integer.

Function: local-gensym ((prefix STRING)) : SYMBOL

Not documented.

Function: symbol-plist ((symbol SYMBOL)) : CONS

Return the property list of symbol. The symbol-plist of a symbol can be set with setf. IMPORTANT: Property list are modified destructively, hence, if you supply it as a whole make sure to always supply a modfiable copy, e.g., by using bquote.

Function: symbol-property ((symbol SYMBOL) (key STANDARD-OBJECT)) : OBJECT

Return the property of symbol whose key is eq? to key. Symbol properties can be set with setf.

Function: symbol-value ((symbol SYMBOL)) : OBJECT

Return the value of symbol. Note, that this value is not visible to code that references a variable with the same name as symbol. The symbol-value is simply a special property that can always be accessed in constant time. The symbol-value of a symbol can be changed with setf.

Function: symbolize ((surrogate SURROGATE)) : SYMBOL

Convert surrogate into a symbol with the same name and module.

6.14 Context and Modules

Function: get-stella-context ((pathName STRING) (error? BOOLEAN)) : CONTEXT

Return the context located at pathName, or null if no such context exists. If error? is true, throw an exception if no context is found, otherwise silently return null.

Function: clear-context ((self CONTEXT)) :

Destroy all objects belonging to self or any of its subcontexts.

Macro: within-context ((contextForm OBJECT) &body (body CONS)) : OBJECT

Execute body within the context resulting from contextForm.

Method: CONTEXT destroy-context (self) :

Make the translator happy.

Method: STRING destroy-context (self) :

Destroy the context self, and recursively destroy all contexts that inherit self.

Method: CONTEXT change-context (context) : CONTEXT

Change the current context to be the context context.

Method: STRING change-context (contextName) : CONTEXT

Change the current context to be the context named contextName.

N-Command: cc (&rest (name NAME)) : CONTEXT

Change the current context to the one named name. Return the value of the new current context. If no name is supplied, return the pre-existing value of the current context. cc is a no-op if the context reference cannot be successfully evaluated.

N-Command: defmodule ((name NAME) &rest (options OBJECT)) :

Define (or redefine) a module named name. The accepted syntax is:

(defmodule <module-name> [:documentation <docstring>] [:includes {<module-name> | (<module-name>*)}] [:uses {<module-name> | (<module-name>*)}] [:lisp-package <package-name-string>] [:java-package <package-specification-string>] [:cpp-namespace <namespace-name-string>] [:java-catchall-class [:api? {TRUE | FALSE}] [:case-sensitive? {TRUE | FALSE}] [:shadow (<symbol>*)] [:java-catchall-class <class-name-string>] [<other-options>*])

name can be a string or a symbol.

Modules include objects from other modules via two separate mechanisms: (1) they inherit from their parents specified via the :includes option and/or a fully qualified module name, and (2) they inherit from used modules specified via the :uses option. The main difference between the two mechanisms is that inheritance from parents is transitive, while uses-links are only followed one level deep. I.e., a module A that uses B will see all objects of B (and any of B's parents) but not see anything from modules used by B. Another difference is that only objects declared as public can be inherited via uses-links (this is not yet enforced). Note that - contrary to Lisp - there are separate name spaces for classes, functions, and variables. For example, a module could inherit the class CONS from the STELLA module, but shadow the function of the same name.

The above discussion of :includes and :uses semantics keyed on the inheritance/visibility of symbols. The PowerLoom system makes another very important distinction: If a module A is inherited directly or indirectly via :includes specification(s) by a submodule B, then all definitions and facts asserted in A are visible in B. This is not the cases for :uses; the :uses options does not impact inheritance of propositions at all.

The list of modules specified in the :includes option plus (if supplied) the parent in the path used for name become the new module's parents. If no :uses option was supplied, the new module will use the STELLA module by default, otherwise, it will use the set of specified modules.

If :case-sensitive? is supplied as TRUE, symbols in the module will be interned case-sensitively, otherwise (the default), they will be converted to uppercase before they get interned. That means that any reference from inside a case-sensitive module to a non-case-sensitive module will have to use uppercase names for symbols in the non-case-sensitive module. The standard system modules are all NOT case sensitive.

Modules can shadow definitions of functions and classes inherited from parents or used modules. Shadowing is done automatically, but generates a warning unless the shadowed type or function name is listed in the :shadow option of the module definition .

Examples:

(defmodule "PL-KERNEL/PL-USER" :uses ("LOGIC" "STELLA") :package "PL-USER") (defmodule PL-USER/GENEALOGY)

The remaining options are relevant only for modules that contain STELLA code. Modules used only to contain knowledge base definitions and assertions have no use for them:

The keywords :lisp-package, :java-package, and :cpp-package specify the name of a native package or name space in which symbols of the module should be allocated when they get translated into one of Lisp, Java, or C++. By default, Lisp symbols are allocated in the STELLA package, and C++ names are translated without any prefixes. The rules that the STELLA translator uses to attach translated Java objects to classes and packages are somewhat complex. Use :java-package option to specify a list of package names (separated by periods) that prefix the Java object in this module. Use :java-catchall-class to specify the name of the Java class to contain all global & special variables, parameter-less functions and functions defined on arguments that are not classes in the current module. The default value will be the name of the module.

When set to TRUE, the :api? option tells the PowerLoom User Manual generator that all functions defined in this module should be included in the API section. Additionally, the Java translator makes all API functions synchronized.

Function: get-stella-module ((pathName STRING) (error? BOOLEAN)) : MODULE

Return the module located at pathName, or null if no such module exists. The search looks at ancestors and top-most (cardinal) modules. If error? is true, throw an exception if no module is found.

Function: find-or-create-module ((pathname STRING)) : MODULE

Return a module located at pathname if one exists, otherwise create one

N-Command: clear-module (&rest (name NAME)) :

Destroy all objects belonging to module name or any of its children. If no name is supplied, the current module will be cleared after confirming with the user. Important modules such as STELLA are protected against accidental clearing.

Function: destroy-module ((self MODULE)) :

Destroy the module self, and recursively destroy all contexts that inherit self.

Method: MODULE destroy-context (self) :

Destroy the context self, and recursively destroy all contexts that inherit self.

Function: visible-modules ((from MODULE)) : (CONS OF MODULE)

Return a list of all modules visible from module from (or *module* if from is NULL. The generated modules are generated from most to least-specific and will start with the module from.

Macro: within-module ((moduleForm OBJECT) &body (body CONS)) : OBJECT

Execute body within the module resulting from moduleForm. *module* is an acceptable moduleForm. It will locally rebind *module* and *context* and shield the outer bindings from changes.

N-Command: in-module ((name NAME)) : MODULE

Change the current module to the module named name.

Method: MODULE change-module (module) : MODULE

Change the current module to be the module module.

Method: STRING change-module (moduleName) : MODULE

Change the current module to be the module named moduleName.

Function: create-world ((parentContext CONTEXT) (name STRING)) : WORLD

Create a new world below the world or module parentContext. Optionally, specify a name.

Function: push-world () : WORLD

Spawn a new world that is a child of the current context, and change the current context to the new world.

Function: pop-world () : CONTEXT

Destroy the current world and change the current context to be its parent. Return the current context. Nothing happens if there is no current world.

Method: WORLD destroy-context (self) :

Destroy the context self, and recursively destroy all contexts that inherit self.

Macro: within-world ((worldForm OBJECT) &body (body CONS)) : OBJECT

Execute body within the world resulting from worldForm.

6.15 Input and Output

Function: read-s-expression ((stream INPUT-STREAM)) : OBJECT BOOLEAN

Read one STELLA s-expression from stream and return the result. Return true as the second value on EOF.

Function: read-s-expression-from-string ((string STRING)) : OBJECT

Read one STELLA s-expression from string and return the result.

Function: read-line ((stream INPUT-STREAM)) : STRING

Read one line from stream and return the result. This differs from native-read-line in that it is not platform-dependent. It recognizes any of the three common line ending formats: CR, LF, CR-LF in any combination. It is not as fast as native-read-line, however.

Function: read-character ((inputStream INPUT-STREAM)) : CHARACTER BOOLEAN

Read one character from inputStream and return the result. Return true as the second value on EOF.

Function: unread-character ((ch CHARACTER) (inputStream INPUT-STREAM)) :

Unread ch from inputStream. Signal an error if ch was not the last character read.

Function: y-or-n? ((message STRING)) : BOOLEAN

Read a line of input from STANDARD-INPUT and return true if the input was y or false if the input was n. Loop until either y or n was entered. If message is non-`null' prompt with it before the input is read. See also special variable *USER-QUERY-ACTION*.

Function: yes-or-no? ((message STRING)) : BOOLEAN

Read a line of input from STANDARD-INPUT and return true if the input was yes or false if the input was no. Loop until either yes or no was entered. If message is non-`null' prompt with it before the input is read. See also special variable *USER-QUERY-ACTION*.

Function: flush-output ((self OUTPUT-STREAM)) :

Flush all buffered output of self.

6.16 Files

Function: open-input-file ((fileName STRING) &rest (options KEYWORD)) : FILE-INPUT-STREAM

Open file fileName for input and return the resulting input stream. By default signal an error if the file does not exist. The only legal option so far is :IF-NOT-EXISTS (or :IF-NOT-EXISTS-ACTION) which specifies what to do in case the file does not exist. If its value is :ERROR then an error will be signaled. If it is :ABORT or :PROBE the opening operation will be aborted and NULL will be returned.

Function: open-output-file ((fileName STRING) &rest (options KEYWORD)) : FILE-OUTPUT-STREAM

Open file fileName for output and return the resulting output stream. By default the file will be created or overwritten if it already exists. If :IF-EXISTS (or :IF-EXISTS-ACTION) is one of the options its value specifies what to do in case the file already exists. If the value is :SUPERSEDE the pre-existing file will be overwritten. If the value is :APPEND the preexisting file will be appended to (if the file did not yet exist the file will simply be created). If the value is :ERROR then an error will be signaled. If it is :ABORT or :PROBE the opening operation will be aborted and NULL will be returned.

If :IF-NOT-EXISTS (or :IF-NOT-EXISTS-ACTION) is one of the options its value specifies what to do in case the file does not already exist. If the value is :CREATE, the file will simply be created. If the value is :ERROR then an error will be signaled. If it is :ABORT or :PROBE the opening operation will be aborted and NULL will be returned.

Function: close-stream ((self STREAM)) :

Close the stream self.

Function: close-all-files () :

Close all currently open file streams. Use for emergencies or for cleanup.

Macro: with-input-file ((binding CONS) &body (body CONS)) : OBJECT

Sets up an unwind-protected form which opens a file for input and closes it afterwards. The stream for reading is bound to the variable provided in the macro form. Syntax is (WITH-INPUT-FILE (var filename options*) body+) where options can be any that are legal for open-input-file (which see).

Macro: with-output-file ((binding CONS) &body (body CONS)) : OBJECT

Sets up an unwind-protected form which opens a file for output and closes it afterwards. The stream for writing is bound to the variable provided in the macro form. Syntax is (WITH-OUTPUT-FILE (var filename options*) body+) where options can be any that are legal for open-output-file (which see).

Function: probe-file? ((fileName FILE-NAME)) : BOOLEAN

Return true if file fileName exists. Note that this does not necessarily mean that the file can also be read.

Function: file-write-date ((fileName FILE-NAME)) : CALENDAR-DATE

Return the time at which file fileName was last modified or NULL if that cannot be determined.

Function: file-length ((fileName FILE-NAME)) : LONG-INTEGER

Return the length of file fileName in bytes or NULL if that cannot be determined. Note that this will currently overrun for files that are longer than what can be represented by a STELLA integer.

Function: copy-file ((fromFile FILE-NAME) (toFile FILE-NAME)) :

Copy file fromFile to file toFile, clobbering any data already in toFile.

Function: delete-file ((fileName FILE-NAME)) :

Delete the file fileName.

Function: directory-file-name ((directory FILE-NAME)) : FILE-NAME

Return directory as a file name, i.e., without a terminating directory separator.

Function: directory-parent-directory ((directory FILE-NAME) (level INTEGER)) : FILE-NAME

Return the level-th parent directory component of directory including the final directory separator, or the empty string if directory does not have that many parents.

Function: file-name-as-directory ((file FILE-NAME)) : FILE-NAME

Return file interpreted as a directory, i.e., with a terminating directory separator. If file is the empty string simply return the empty string, i.e., interpret it as the current directory instead of the root directory.

Function: file-name-directory ((file FILE-NAME)) : FILE-NAME

Return the directory component of file including the final directory separator or the empty string if file does not include a directory. Note that for purposes of this function, a logical host is considered part of the directory portion of file

Function: file-name-without-directory ((file FILE-NAME)) : FILE-NAME

Return the file name portion of file by removing any directory and logical host components.

Function: file-name-without-extension ((file FILE-NAME)) : FILE-NAME

Remove files extension (or type) if there is any and return the result.

Function: file-extension ((file FILE-NAME)) : STRING

Return files extension (or type) if it has any including the separator character.

Function: file-base-name ((file FILE-NAME)) : FILE-NAME

Remove files directory (including logical host) and extension components and return the result.

Function: absolute-pathname? ((pathname STRING)) : BOOLEAN

Not documented.

Function: logical-host? ((host STRING)) : BOOLEAN

Not documented.

Function: logical-pathname? ((pathname STRING)) : BOOLEAN

Not documented.

Function: translate-logical-pathname ((pathname STRING)) : STRING

Not documented.

Function: directory-separator () : CHARACTER

Not documented.

Function: directory-separator-string () : STRING

Not documented.

6.17 Dates and Times

Function: get-current-date-time () : INTEGER INTEGER INTEGER KEYWORD INTEGER INTEGER INTEGER INTEGER

Returns the current time in UTC as multiple values of year month day day-of-week hour minute second millisecond. Currently millisecond will always be zero (even in Java where it is technically available).

Function: get-local-time-zone () : FLOAT

Returns the current time zone offset from UTC as a float, considering the effects of daylight savings time.

Function: make-current-date-time () : CALENDAR-DATE

Create a calendar date with current time and date.

Function: make-date-time ((year INTEGER) (month INTEGER) (day INTEGER) (hour INTEGER) (minute INTEGER) (second INTEGER) (millis INTEGER) (timezone FLOAT)) : CALENDAR-DATE

Create a calendar date with the specified components. year must be the complete year (i.e., a year of 98 is 98 A.D in the 1st century). timezone is a real number in the range -12.0 to +14.0 where UTC is zone 0.0; The number is the number of hours to add to UTC to arrive at local time.

Function: parse-date-time ((date-time-string STRING) (start INTEGER) (end INTEGER) (error-on-mismatch? BOOLEAN)) : DECODED-DATE-TIME

Tries very hard to make sense out of the argument date-time-string and returns a time structure if successful. If not, it returns null. If error-on-mismatch? is true, parse-date-time will signal an error instead of returning null. Default values are 00:00:00 local time on the current date

Method: CALENDAR-DATE decode-calendar-date (date (timezone FLOAT)) : DECODED-DATE-TIME

Returns a decoded time object for date interpreted in timezone timezone is the number of hours added to UTC to get local time. It is in the range -12.0 to +14.0 where UTC is zone 0.0

Method: DECODED-DATE-TIME encode-calendar-date (time-structure) : CALENDAR-DATE

Returns a calendar date object for time-structure.

???: calendar-date-to-string

Not yet implemented.

Function: string-to-calendar-date ((input STRING)) : CALENDAR-DATE

Returns a calendar date object representing the date and time parsed from the input string. If no valid parse is found, null is returned.

???: relative-date-to-string

Not yet implemented.

Function: compute-calendar-date ((julian-day INTEGER)) : INTEGER INTEGER INTEGER KEYWORD

Returns the YEAR, MONTH, DAY, DAY-OF-WEEK on which the given julian-day begins at noon.

Function: compute-day-of-week ((yyyy INTEGER) (mm INTEGER) (dd INTEGER)) : KEYWORD

Returns the day of the week for yyyy-mm-dd.

Function: compute-day-of-week-julian ((julian-day INTEGER)) : KEYWORD

Returns the day of the week for julian-day

Function: compute-julian-day ((yyyy INTEGER) (mm INTEGER) (dd INTEGER)) : INTEGER

Returns the Julian day that starts at noon on yyyy-mm-dd. yyyy is the year. mm is the month. dd is the day of month. Negative years are B.C. Remember there is no year zero.

Function: compute-next-moon-phase ((n INTEGER) (phase KEYWORD)) : INTEGER FLOAT

Returns the Julian Day and fraction of day of the Nth occurence since January 1, 1900 of moon PHASE. PHASE is one of :NEW-MOON, :FIRST-QUARTER, :FULL-MOON, :LAST-QUARTER

Function: decode-time-in-millis ((time INTEGER)) : INTEGER INTEGER INTEGER INTEGER

Returns multiple values of hours, minutes, seconds, milliseconds for time specified in milliseconds.

Function: julian-day-to-modified-julian-day ((julian-day INTEGER)) : INTEGER

Returns the modified Julian day during which julian-daystarts at noon.

Function: modified-julian-day-to-julian-day ((modified-julian-day INTEGER)) : INTEGER

Returns the modified Julian day during which julian-daystarts at noon.

Function: time-add ((t1 DATE-TIME-OBJECT) (t2 DATE-TIME-OBJECT)) : DATE-TIME-OBJECT

Add t1 to t2. If one of t1 or t2 is a calendar date, then the result is a calendar date. If both t1 and t2 are relative dates, then the result is a relative date. t1 and t2 cannot both be calendar dates.

Function: time-divide ((t1 TIME-DURATION) (t2 OBJECT)) : OBJECT

Divides the relative date t1 by t2. t2 must be either a relative date or a wrapped number. If t2 is a relative date, then the return value will be a wrapped float. If t2 is a wrapped number, then the reutrn value will be a relative date.

Function: time-multiply ((t1 OBJECT) (t2 OBJECT)) : TIME-DURATION

Multiplies a relative date by a wrapped number. One of t1 or t2 must be a relative date and the other a wrapped number.

Function: time-subtract ((t1 DATE-TIME-OBJECT) (t2 DATE-TIME-OBJECT)) : DATE-TIME-OBJECT

Subtract t2 from t1. If t1 is a calendar date, then t2 can be either a calendar date (in which case the return value is a relative date) or it can be a relative date (in which case the return value is a calendar date). If t1 is a relative date, then t2 must also be a relative date and a relative date is returned.

Function: get-ticktock () : TICKTOCK

Return the current CPU time. If the current OS/Language combination does not support measuring of CPU time, return real time instead. Use ticktock-difference to measure the time difference between values returned by this function. This is an attempt to provide some platform independent support to measure (at least approximately) consumed CPU time.

Function: ticktock-difference ((t1 TICKTOCK) (t2 TICKTOCK)) : FLOAT

The difference in two TICKTOCK time values in seconds where t1 is the earlier time. The resolution is implementation dependent but will normally be some fractional value of a second.

Function: ticktock-resolution () : FLOAT

The minimum theoretically detectable resolution of the difference in two TICKTOCK time values in seconds. This resolution is implementation dependent. It may also not be realizable in practice, since the timing grain size may be larger than this resolution.

Function: sleep ((seconds FLOAT)) :

The program will sleep for the indicated number of seconds. Fractional values are allowed, but the results are implementation dependent: Common Lisp uses the fractions natively, Java with a resolution of 0.001, and C++ can only use integral values.

6.18 XML Support

Function: make-xml-element ((name STRING) (namespace-name STRING) (namespace STRING)) : XML-ELEMENT

Creates and interns an XML element object name using namespace-name to refer to namespace. If namespace is null, then the element will be interned in the null namespace. namespace must otherwise be a URI.

Function: make-xml-global-attribute ((name STRING) (namespace-name STRING) (namespace STRING)) : XML-GLOBAL-ATTRIBUTE

Creates and interns an XML global attribute object with name using namespace-name to refer to namespace. namespacemust be a URI.

Function: make-xml-local-attribute ((name STRING) (element XML-ELEMENT)) : XML-LOCAL-ATTRIBUTE

Make an XML-LOCAL-ATTRIBUTE named name associated with element

Function: get-xml-tag ((expression CONS)) : XML-ELEMENT

Return the XML tag object of an XML expression.

Function: get-xml-attributes ((expression CONS)) : CONS

Return the list of attributes of an XML expression (may be empty).

Function: get-xml-content ((expression CONS)) : CONS

Return the list of content elements of an XML expression (may be empty).

Function: get-xml-cdata-content ((form CONS)) : STRING

Return the CDATA content of a CDATA form. Does NOT make sure that form actually is a CDATA form, so bad things can happen if it is given wrong input.

Function: xml-declaration? ((item OBJECT)) : BOOLEAN

Return true if item is an XML declaration object

Function: xml-element? ((item OBJECT)) : BOOLEAN

Return true if item is an XML element object

Function: xml-attribute? ((item OBJECT)) : BOOLEAN

Return true if item is an XML attribute object

Function: xml-cdata? ((item OBJECT)) : BOOLEAN

Return true if item is an XML CDATA tag object

Function: xml-cdata-form? ((form OBJECT)) : BOOLEAN

Return true if form is a CONS headed by a CDATA tag

Method: XML-ELEMENT xml-element-match? (tag (name STRING) (namespace STRING)) : BOOLEAN

Returns true if tag is an XML element with the name name in namespace namespace. Note that namespace is the full URI, not an abbreviation. Also, namespace may be null, in which case tag must not have a namespace associated with it.

Method: XML-ATTRIBUTE xml-attribute-match? (attribute (name STRING) (namespace STRING)) : BOOLEAN

Return true if attribute is an XML attribute with name name in namespace namespace. Note that namespace is the full URI, not an abbreviation. Also, namespace may be null, in which case attribute must not have a namespace associated with it.

Method: XML-GLOBAL-ATTRIBUTE xml-attribute-match? (attribute (name STRING) (namespace STRING)) : BOOLEAN

Return true if attribute is a global XML attribute with name name in namespace namespace. Note that namespace is the full URI, not an abbreviation. Also, namespace may be null, in which case attribute must not have a namespace associated with it.

Method: XML-LOCAL-ATTRIBUTE xml-attribute-match? (attribute (name STRING) (namespace STRING)) : BOOLEAN

Return true if attribute is a local XML attribute with name name. Note that namespace must be null and that the attributes parent element element is not considered by the match. To take the parent element into account use xml-local-attribute-match?.

Function: xml-local-attribute-match? ((attribute XML-LOCAL-ATTRIBUTE) (name STRING) (element-name STRING) (element-namespace STRING)) : BOOLEAN

Return true if attribute is a local attribute with name and whose parent element matches element-name and element-namespace.

Function: xml-lookup-attribute ((attributes CONS) (name STRING) (namespace STRING)) : STRING

Find the XML attribute in attributes with name and namespace and return its value. Note that it is assumed that all attributes come from the same known tag, hence, the parent elements of any local attributes are not considered by the lookup.

Macro: xml-tag-case ((item OBJECT) &body (clauses CONS)) : OBJECT

A case form for matching item against XML element tags. Each element of clauses should be a clause with the form ("tagname" ...) or (("tagname" "namespace-uri") ...) The clause heads can optionally be symbols instead of strings. The key forms the parameters to the method xml-element-match?, with a missing namespace argument passed as NULL.

The namespace argument will be evaluated, so one can use bound variables in place of a fixed string. As a special case, if the namespace argument is :ANY, then the test will be done for a match on the tag name alone.

Function: read-xml-expression ((stream INPUT-STREAM) (start-tag OBJECT)) : OBJECT BOOLEAN

Read one balanced XML expression from stream and return its s-expression representation (see xml-token-list-to-s-expression). If startTagName is non-`null', skip all tags until a start tag matching start-tag is encountered. XML namespaces are ignored for outside of the start tag. Use s-expression representation to specify start-tag, e.g., (KIF (:version "1.0")). The tag can be an XML element object, a symbol, a string or a cons. If the tag is a cons the first element can also be (name namespace) pair.

Return true as the second value on EOF.

CHANGE WARNING: It is anticipated that this function will change to a) Properly take XML namespaces into account and b) require XML element objects instead of strings as the second argument. This change will not be backwards-compatible.

Function: xml-expressions ((stream INPUT-STREAM) (regionTag OBJECT)) : XML-EXPRESSION-ITERATOR

Return an XML-expression-iterator (which see) reading from stream. regionTag can be used to define delimited regions from which expressions should be considered. Use s-expression representation to specify regionTag, e.g., (KIF (:version "1.0")). The tag can be an XML element object, a symbol, a string or a cons. If the tag is a cons the first element can also be (name namespace) pair.

Function: print-xml-expression ((stream OUTPUT-STREAM) (xml-expression CONS) (indent INTEGER)) :

Prints xml-expression on stream. Indentation begins with the value of indent. If this is the null integer, no indentation is performed. Otherwise it should normally be specified as 0 (zero) for top-level calls.

It is assumed that the xml-expression is a well-formed CONS-list representation of an XML form. It expects a form like that form returned by read-XML-expression.

Also handles a list of xml forms such as that returned by XML-expressions. In that case, each of the forms is indented by indent spaces.

Function: reset-xml-hash-tables () :

Resets Hashtables used for interning XML elements and global attribute objects. This will allow garbage collection of no-longer used objects, but will also mean that newly parsed xml elements and global attributes will not be eq? to already existing ones with the same name.

6.19 Miscellaneous

This is a catch-all section for functions and methods that haven't been categorized yet into any of the previous sections. They are in random order and many of them will never be part of the official STELLA interface. So beware!

Function: operating-system () : KEYWORD

Not documented.

Method: DIMENSIONAL-ARRAY-MIXIN 1d-aref (self (i INTEGER)) : (LIKE (ANY-VALUE SELF))

Return the element of self at position [i].

Method: DIMENSIONAL-ARRAY-MIXIN 1d-aref-address (self (i INTEGER)) : INTEGER

Return the 1D address of the element at position [i]. This is useful for fast element-wise iteration that doesn't need arithmetic.

Method: DIMENSIONAL-ARRAY-MIXIN 1d-aref-setter (self (value (LIKE (ANY-VALUE SELF))) (i INTEGER)) : (LIKE (ANY-VALUE SELF))

Set the element of self at position [i] to value and return the result.

Method: 2-DIMENSIONAL-ARRAY-MIXIN 2d-aref (self (i INTEGER) (j INTEGER)) : (LIKE (ANY-VALUE SELF))

Return the element of self at position [i, j].

Method: 2-DIMENSIONAL-ARRAY-MIXIN 2d-aref-address (self (i INTEGER) (j INTEGER)) : INTEGER

Return the 1D address of the element at position [i, j]. This is useful for fast element-wise iteration that doesn't need arithmetic.

Method: 2-DIMENSIONAL-ARRAY-MIXIN 2d-aref-setter (self (value (LIKE (ANY-VALUE SELF))) (i INTEGER) (j INTEGER)) : (LIKE (ANY-VALUE SELF))

Set the element of self at position [i, j] to value and return the result.

Method: LONG-INTEGER abs (x) : LONG-INTEGER

Return the absolute value of x.

Function: activate-demon ((demon DEMON)) :

Install demon in the location(s) specified by its internal structure.

Method: POLYMORPHIC-RELATION active? (self) : BOOLEAN

True if self or a superslot of self is marked active.

Function: add-configuration-property ((property STRING) (value OBJECT) (configuration CONFIGURATION-TABLE)) : OBJECT

Add value to property in configuration and return it. If a previous value exists add value to the end (listify the old value if it is not yet a list). Otherwise, create a new list containing value. Use the global system configuration table if configuration is NULL.

Function: add-hook ((hookList HOOK-LIST) (hookFunction SYMBOL)) :

Insert the function named hookFunction into hookList.

N-Command: add-trace (&rest (keywords GENERALIZED-SYMBOL)) : LIST

Enable trace messages identified by any of the listed keywords. After calling (add-trace <keyword>) code guarded by (trace-if <keyword> ...) will be executed when it is encountered.

Function: advance-past-whitespace ((source STRING) (start INTEGER)) : INTEGER

Returns the first index into source, starting from start, of the first character that is not white space.

Function: all-classes ((module MODULE) (local? BOOLEAN)) : (ITERATOR OF CLASS)

Iterate over all classes visible from module. If local?, return only classes interned in module. If module is null, return all classes interned everywhere.

Function: all-contexts () : (ITERATOR OF CONTEXT)

Return an iterator that generates all contexts.

Macro: all-defined? (&body (forms CONS)) : OBJECT

Evaluate each of the forms in forms, and return TRUE if none of them are NULL.

Function: all-functions ((module MODULE) (local? BOOLEAN)) : (ITERATOR OF FUNCTION)

Iterate over all functions visible from module. If local?, return only functions bound to symbols interned in module. If module is null, return all functions defined everywhere.

Function: all-included-modules ((self MODULE)) : (ITERATOR OF MODULE)

Generate a sequence of all modules included by self, inclusive, starting from the highest ancestor and working down to self (which is last).

Function: all-methods ((module MODULE) (local? BOOLEAN)) : (ITERATOR OF METHOD-SLOT)

Iterate over all methods visible from module. If local?, return only methods interned in module. If module is null, return all methods interned everywhere.

Function: all-modules () : (ITERATOR OF MODULE)

Return an iterator that generates all modules.

Function: all-public-functions ((module MODULE) (local? BOOLEAN)) : (ITERATOR OF FUNCTION)

Iterate over all functions visible from module. If local?, return only functions bound to symbols interned in module. If module is null, return all functions defined everywhere.

Function: all-public-methods ((module MODULE) (local? BOOLEAN)) : (ITERATOR OF METHOD-SLOT)

Iterate over all public methods visible from module. If local?, return only methods interned in module. If module is null, return all methods interned everywhere.

Function: all-required-systems ((system-name STRING)) : (CONS OF STRING-WRAPPER)

Returns a CONS of all of the systems required by system-name

Function: all-slots ((module MODULE) (local? BOOLEAN)) : (ITERATOR OF SLOT)

Iterate over all slots visible from module. If local?, return only methods interned in module. If module is null, return all methods interned everywhere.

Function: all-subcontexts ((context CONTEXT) (traversal KEYWORD)) : (ALL-PURPOSE-ITERATOR OF CONTEXT)

Return an iterator that generates all subcontexts of self (not including self) in the order specified by traversal (one of :preorder, :inorder, :postorder or :topdown).

Function: all-surrogates ((module MODULE) (local? BOOLEAN)) : (ITERATOR OF SURROGATE)

Iterate over all surrogates visible from module. If local?, return only surrogates interned in module. If module is null, return all surrogates interned everywhere.

Function: all-symbols ((module MODULE) (local? BOOLEAN)) : (ITERATOR OF SYMBOL)

Iterate over all symbols visible from module. If local?, return only symbols interned in module. If module is null, return all symbols interned everywhere.

Function: all-variables ((module MODULE) (local? BOOLEAN)) : (ITERATOR OF GLOBAL-VARIABLE)

Iterate over all variables visible from module. If local?, return only variables bound to symbols interned in module. If module is null, return all variables defined everywhere.

Method: ABSTRACT-ITERATOR allocate-iterator (self) : (LIKE SELF)

Iterator objects return themselves when asked for an iterator (they occupy the same position as a collection within a foreach statement).

Method: MEMOIZABLE-ITERATOR allocate-iterator (self) : (ITERATOR OF (LIKE (ANY-VALUE SELF)))

Alias for clone-memoized-iterator.

Method: STORAGE-SLOT allocation (self) : KEYWORD

Return the most specific :allocation facet, or :instance if all inherited values are NULL.

Function: apply ((code FUNCTION-CODE) (arguments (CONS OF OBJECT))) : OBJECT

Apply code to arguments, returning a value of type OBJECT.

Function: apply-boolean-method ((code METHOD-CODE) (arguments (CONS OF OBJECT))) : BOOLEAN

Apply code to arguments, returning a value of type BOOLEAN.

Function: apply-float-method ((code METHOD-CODE) (arguments (CONS OF OBJECT))) : FLOAT

Apply code to arguments, returning a value of type FLOAT.

Function: apply-integer-method ((code METHOD-CODE) (arguments (CONS OF OBJECT))) : INTEGER

Apply code to arguments, returning a value of type INTEGER.

Function: apply-long-integer-method ((code METHOD-CODE) (arguments (CONS OF OBJECT))) : LONG-INTEGER

Apply code to arguments, returning a value of type LONG-INTEGER.

Function: apply-method ((code METHOD-CODE) (arguments (CONS OF OBJECT))) : OBJECT

Apply code to arguments, returning a value of type OBJECT.

Function: apply-string-method ((code METHOD-CODE) (arguments (CONS OF OBJECT))) : STRING

Apply code to arguments, returning a value of type STRING.

Function: base60-to-float ((l (CONS OF NUMBER-WRAPPER))) : FLOAT

Converts (x y z) into a float. The return value is x + y/60 + z/3600. This can be used to convert from Degree-Minute-Second to decimal degrees or from Hour-Minute-Second format to decimal hours.

Function: break-program ((message STRING)) :

Interrupt the program and print message. Continue after confirmation with the user.

Command: bump-log-indent () :

Increase the indentation level for subsequent log messages.

Function: byte-array-read-sequence ((buffer TOKENIZER-BYTE-ARRAY) (stream INPUT-STREAM) (start INTEGER) (end INTEGER)) : INTEGER

Read from stream filling buffer between start and end (depending on how many characters are available). Return the actual end pointer to the input read into buffer. EOF is indicated by the return value being equal to start.

Function: byte-array-write-sequence ((buffer TOKENIZER-BYTE-ARRAY) (stream NATIVE-OUTPUT-STREAM) (start INTEGER) (end INTEGER)) :

Write from buffer to stream, using data in the buffer starting at position start stopping just before end.

Method: CALENDAR-DATE calendar-date-to-date-string (date (timezone FLOAT) (numeric-month? BOOLEAN)) : STRING

Returns the date part of the string representation of date adjusted for timezone. Format is YYYY-MMM-DD, where MMM is a three letter English abbreviation of the month if numeric-month? is false and a two digit numeric value if numeric-month? is true. The value false is recommended.

Method: CALENDAR-DATE calendar-date-to-iso8601-string (date (timezone FLOAT) (include-timezone? BOOLEAN)) : STRING

Returns an ISO-8601 string representation of date adjusted for timezone. The Format is YYYY-MM-DDThh:mm:ss z:zz. The timezone as an offset hh:mm is included if include-timezone? is true.

Recommended values for the flag is true.

Method: CALENDAR-DATE calendar-date-to-string (date (timezone FLOAT) (numeric-month? BOOLEAN) (include-timezone? BOOLEAN)) : STRING

Returns a string representation of date adjusted for timezone. The Format is YYYY-MMM-DD hh:mm:ss z.z, where MMM is a three letter English abbreviation of the month if numeric-month? is false and a two digit numeric value if numeric-month? is true. The timezone as a float offset z.z is included if include-timezone? is true.

Recommended values for the flags are false and true respectively.

Method: CALENDAR-DATE calendar-date-to-time-string (date (timezone FLOAT) (include-timezone? BOOLEAN) (include-millis? BOOLEAN) (pad-hours? BOOLEAN)) : STRING

Returns the time part of the string representation of date adjusted for timezone. The timezone is included in the string if include-timezone? is true. The value true is recommended. Milliseconds will be included if include-millis? is true. Hours will be zero-padded to length 2 if pad-hours? is true.

Command: call-clear-module (&rest (name NAME)) :

Destroy all objects belonging to module name or any of its children. If no name is supplied, the current module will be cleared after confirming with the user. Important modules such as STELLA are protected against accidental clearing.

Function: cast ((value OBJECT) (type TYPE)) : OBJECT

Perform a run-time type check, and then return value.

N-Command: ccc (&rest (name NAME)) : CONTEXT

Change the current context to the one named name. Return the value of the new current context. If no name is supplied, return the pre-existing value of the current context. cc is a no-op if the context reference cannot be successfully evaluated. In CommonLisp, if the new context is case sensitive, then change the readtable case to :INVERT, otherwise to :UPCASE.