roo!™
Built-in classes

Hop into the future !

1 Built-in classes

There are numerous roo!™ built-in classes. These classes are implemented within the roo!™ interpreter, in a native programming language. Thus, the use of these classes provides improved performance for common programming constructs.

roo!™ programs that you develop can extend built-in classes. The randomSequence.roo example program shows how built-in classes can be extended. The randomSequence.roo program extends a vector explicitly, because class initialization parameters differ in structure from those that are used by a vector. When the class initialization parameters are the same as the built-in class, the explicitly keyword is unnecessary.

Descriptions are provided for the initialize method of each class. The initialize method is usually invoked during class construction. The class construction parameters are passed to the initialize method. The initialize method is only invoked directly by an explicitly derived class. The randomSequence example program explicitly invokes the initialize method of the vector class.

1.1 Built-in class index

The following built-in classes are provided.

1.2 Built-in class hierarchy

The following table uses indentation to indicate built-in class derivation structure. Methods in a base class can be used in a derived class.

1.3 Aggregate built-in classes

Numerous classes are aggregates that store an arbitrary number of other items. Each item is a Rexx value or an instance of another object.

A common set of methods are used within these classes. The methods, that are available for each aggregate class, are listed in their class description.

Observe: aggregate references often involve index values. The Rexx language consistently indexes arguments and string positions with an origin of 1. Consequently, within aggregate methods an index value of 1 references the first item stored in the aggregate. The index must be in the range 1 through size(), inclusive.

Warning: an objection condition is raised when an index is specified that is not within the aggregate's bounds.

1.3.1 Aggregate methods

(1) lines can be separated by an isolated carriage return ('0d'x), an isolated line feed ('0a'x), or a combination of these in either order.

Observe: the various methods that start with 'add', as well as the copyAggregate and removeAll methods, return a string which is a reference to the current instance. This allows the result of the operation to be processed directly as follows:

1.4 BitVector -- extends Object

The BitVector class is excellent for storing a a condensed vector of boolean values of a fixed sizes. The extent can not exceed 4096 bits. The default extent is 128 bits. The active extent can be revised to a more convenient size by using the resize method. When more bits are required, you can make a vector of bitvectors. A substring of bits can be extracted by the getMultiple and getMultipleBytes methods. Similarly, a substring can be assigned by the setMultiple and setMultipleBytes methods. Bits can be accessed with square brackets. You can also process the bits with the LOOP .. OVER instruction.

Bits are indexed using the normal Rexx method. An index of 1 references the first bit location.

Hint: generally you will use a bit vector that is shorter than 4096 bits. In this case, don't forget to use the resize method, otherwise you will get surprises when the toString method is invoked.

1.4.1 BitVector methods

1.4.2 BitVector example usage

The following shows various BitVector method uses. The quoted value in parentheses following the say keyword is the value of the expression to the right of the quoted value.

1.5 CharacterVector -- character values

The CharacterVector class is a vector of single byte values. A reduced set of the vector class methods are supported -- getAt, removeAt, removeAll, setAt, and size.

1.5.1 CharacterVector class methods, additional

1.6 Clipboard -- extends Object

The Clipboard class is used to get text from the system clipboard, or to replace the clipboard text.

Note: some system environments do not have clipboards, so the use of this class may introduce portability difficulties.

1.6.1 Clipboard class methods

1.7 Comparator -- extends Object, non-instantiable

Some built-in classes use an optional comparator object to compare two items. A comparator object extends class comparator and must implement the isLess method as described below. When the comparator object is absent the Rexx less-than ( < ) operator is used instead. The Rexx less-than operator performs a numeric comparison when both items are numeric, otherwise a fixed case string comparison is performed.

This is an abstract description of the interfaces of an actual comparator class instance.

1.7.1 Comparator class method

Note: if either item (or both) being compared is a class instance, then it is up to the isLess method to convert the item to a comparable value. For example, the toString method of the item could be invoked to obtain a comparison value.

1.8 Console -- extends Emitter

The console class is used to read and write characters or strings from or to the console.

1.8.1 Console class method

1.9 ContextVector -- extends Vector, unmodifiable

The ContextVector class is used to analyze active method and procedure invocations. Each line contains the name of an active method or procedure, the associated source line, and a comma separated list of call arguments.

When method contexts are listed method names are preceded by the class name and a caret.

1.9.1 ContextVector class methods

Example of use:

1.10 DriveContext (aka Disk, DiskContext, Drive) -- extends Stack

The DriveContext class establishes a drive as the current disk drive. When activated a DriveContext is similar to invoking a command that changes the active disk; i.e. A:

Observe: the drive context that was in effect prior to DriveContext instance creation is always restored, when the instance is removed.

1.10.1 DriveContext class methods

A drive context has the same methods as a drive object.

Note: an irksome message box may be displayed when media is absent from a drive that supports mountable media -- i.e. floppy disks, CD-ROMs, etc. This message appears when either the exists, or toDetailedString methods are invoked.

1.11 Emitter -- extends Object, non-instantiable

The emitter class is used to write characters or strings to an arbitrary output stream. All emitter class derivatives should implement the methods listed below. This allows alternate emitters to be passed as parameters to procedures and methods. An example of a program that uses alternate emitters is qt.rooProgram.

1.11.1 Emitter class method

1.12 Exception -- extends Object, non-instantiable

Exception information that can be referenced by catch condition handlers

1.12.1 Object class methods

1.13 ExternalClass -- extends Object

An ExternalClass is a built-in class that invokes methods in an external program. In Windows system environments the program is a dynamic link library (DLL). An optional call back capability is also supported.

1.13.1 ExternalClass class methods

Note: the externalProgramName is automatically unloaded when all ExternalClass instance usages become inactive. The optional 'terminate' method of the external program is performed before unloading the program.

Note: the external program can call back to methods in a class that extends an ExternalClass instance. The WinList.rooProgram example, and WinList.roo class, illustrate the usage of ExternalClass with a program named WinList.dll.

The following diagram illustrates the components that are used in the WINLIST example.

The external module can optionally provide an entry point named 'SetCallback'. When this entry is present, its is invoked during instance initiation, with an instanceContextLocator argument. This allows the external module to callback to the roo!™ context. If the SetCallback entry is not defined, the external module will not be able to invoke a callback in the roo!™ context.

1.14 File

The File class is used to obtain information about a specific file

1.14.1 File class methods

For some of the following methods the example file name is:

1.15 FolderContext (aka Directory, DirectoryContext, Folder) -- extends Stack

The FolderContext class establishes a folder as the current folder for subsequent file. system activity. When activated a FolderContext is similar to invoking a CHDIR command.

Observe: the folder context that was in effect prior to FolderContext instance creation is always restored, when the instance is removed.

1.15.1 FolderContext class methods

1.16 InLineFile -- extends Vector

The InLineFile class is a line-oriented encapsulation of Rexx input/output stream capabilities. When the class is initialized all lines are loaded, and the file is closed. Subsequently, the InLineFile instance can be accessed by any of the Vector class methods, that do not alter line contents.

Observe: a NOTREADY condition is signalled, if enabled, when an attempt is made to read more than the number of available lines.

1.16.1 InLineFile class methods, additional

Hint: the file is closed when all instances are no longer active. Often you can accomplish this by dropping the variable that has the file instance value. For example:

1.17 InOutLineFile -- extends List

The InOutLineFile class is a line-oriented encapsulation of Rexx input/output stream capabilities. The class is intended to revise an existing file. When the class is initialized all lines are loaded. Subsequently, the InOutLineFile instance can be accessed by any of the List class methods. When all instance uses are inactive lines are flushed to the external file associated with the stream, and the stream is closed.

The InOutLineFile class is intended for general file alterations; i.e. deletions and insertions. The related InLineFile and OutLineFile are more appropriate for sequential file access.

Separate line positions are maintained for reading and writing.

Observe: a NOTREADY condition is signalled, if enabled, when an attempt is made to read more than the number of available lines.

1.17.1 InOutLineFile class methods, additional

Hint: the file is closed when all instances are no longer active. Often you can accomplish this by dropping the variable that has the file instance value. For example:

1.18 InStream -- extends Object

The outstream class is used to read characters or strings from the default input stream (standard input).

1.18.1 InStream class method

1.19 List -- extends Aggregate

The List class is excellent for storing an arbitrary collection of heterogeneous objects. The performance of getAt and setAt requests is worse than the corresponding vector class. Performance is better than the corresponding vector class when items are inserted or removed at the front or the middle of the list.

1.19.1 Methods:

The list class supports all aggregate class methods.

1.20 Map -- extends Object

The Map class is excellent for storing a keyed collection of heterogeneous items. Each item that is associated with a key can be a Rexx value or an instance reference. An optional comparator instance can be assigned to establish a custom ordering of items. When a comparator instance has not been assigned standard, non-strict, Rexx comparisons are used to establish the ordering. Thus, numeric values are in numeric order. String values are in collating order. When class instance values are encountered, their associated value is the result of their 'ToString' method. When the associated class lineage does not have a 'ToString' method, an implicit value is used which is the class name followed by the relative instance index -- i.e. SOMECLASS #3.

1.20.1 Methods:

  •  Math^various mathematic functions (sine, cosine, etc) and constants (π, e, Φ, γ)

    1.21 Math

    The Math class provides various mathematic functions (sine, cosine, etc) and constants (π, e, Φ, γ)

    Note: the arguments for the trigonometric methods, and associated results, are measured in radians, not degrees!

    Warning: if an argument is outside the domain of a function the string 'undefined' is returned.

    Note: additional mathematic functions -- Gamma(X), lnGamma(X), sinh, cosh, sinh-1, etc. -- can be found in the MathX.roo example program.

    1.21.1 Object class methods

    Here is an example that shows how to compute the sine of π/4 (45°)

    Even better, the following example shows how to compute the value of π to 1000 decimal places.

    In 1706, a mathematician named John Machin discovered that:

      π / 4 = 4 * arctan( 1/5 ) - arctan( 1 / 239 )

    You can click here to discover how Machin derived this incredible formula:

    1.22 Object -- non-instantiable

    All classes are implicitly derived from the Object class.

    1.22.1 Object class methods

    1.23 OrderedVector -- extends Aggregate

    The OrderedVector class is a vector, with the distinction that all items are ordered. Multiple items can have the same value. An optional comparator instance can be assigned to establish a custom ordering of items. When a comparator instance has not been assigned standard, non-strict, Rexx comparisons are used to establish the ordering. Thus, numeric values are in numeric order. String values are in collating order. When class instance values are encountered, their associated value is the result of their 'ToString' method. When the associated class lineage does not have a 'ToString' method, an implicit value is used which is the class name followed by the relative instance index -- i.e. SOMECLASS #3.

    1.23.1 OrderedVector class methods

    Observe: the union, intersection, difference, and nonIntersection methods are unavailable for an OrderedVector. These capabilities can be used by adding a orderedVector aggregate to a set instance, as shown in the first line in the example below.

    Here is an example that shows the creation of an OrderedVector, which is immediately converted to a set. Then, various set computations are performed.

    Here is an example that shows how the lines of a file can be sorted by an OrderedVector.

    The first line above prepares an ordered vector. The second line reads inFileName, and adds the lines to the ordered vector. The final line adds the lines, which are now sorted, to the output file outFileName. The lines are written when the scope of the output LineFile instance concludes.

    The above example could be programmed in one instruction as follows

    Here is an example that shows how the lines of a file can be sorted in reverse collating order.

    Here is an example that shows how the lines of a file can be sorted in a custom order.

    Here is an example of a customSort class:

    1.24 OutLineFile -- extends Vector

    The OutLineFile class is a line-oriented encapsulation of Rexx input/output stream capabilities. The class is intended to prepare a new file, or completely replace an existing file. Subsequently, the OutLineFile instance can be accessed by any of the Vector class methods. When all instance uses are inactive lines are flushed to the external file associated with the stream, and the stream is closed.

    The OutLineFile class is intended for sequential writing of lines to a file, rather than deletions and insertions. The related InOutLineFile is more efficient for deletions and insertions.

    1.24.1 LineStream class methods, additional

    Hint: the file is closed when all instances are no longer active. Often you can accomplish this by dropping the variable that has the file instance value. For example:

    1.25 OutStream -- extends Emitter

    The outstream class is used to write characters or strings to the default output stream (standard output).

    1.25.1 OutStream class method

    1.26 Pattern -- extends Object

    The Pattern class establishes a regular expression pattern, and extended string search capabilities.

    1.26.1 Methods:

    Click here to review an example of a pattern match search, that also returns segments.

    1.27 PatternMatch -- extends Object, non-instantiable

    The PatternMatch class provides information describing matches that occurred during a regular expression pattern search. Instances of the PatternMatch class are created by the search method of the Pattern built-in class.

    1.27.1 Methods:

    The following is an example of a pattern match search, that also returns segments. There are 2 segments in the pattern. These are defined within the outermost level of paired parentheses. The segments are associated with the following portions of the pattern.

    1. (((1-)?([0-9]{3})-){1,2})

    2. ([0-9]{4})

    1.28 Queue -- extends List

    The Queue class is excellent for storing an arbitrary collection of heterogeneous objects. These are normally accessed at the beginning or the end. Other methods of the list class are also available; such as: isEmpty, isNonEmpty, size, setAt, and toString.

    1.28.1 Methods:

    1.29 Set -- extends Aggregate

    The Set class is a Vector, with the distinction that all items are unique, and ordered. An optional comparator instance can be assigned to establish a custom ordering of items. When a comparator instance has not been assigned standard, non-strict, Rexx comparisons are used to establish the ordering. Thus, numeric values are in numeric order. String values are in collating order. When class instance values are encountered, their associated value is the result of their 'ToString' method. When the associated class lineage does not have a 'ToString' method, an implicit value is used which is the class name followed by the relative instance index -- i.e. SOMECLASS #3.

    1.29.1 Set class methods

    The set class supports all aggregate class methods, plus the following methods:

    Observe: the union, intersection, difference, and nonIntersection methods compare one set instance versus another set instance, and return a new set class instance. If otherSet value is not a set instance, an OBJECTION condition is optionally raised. If the OBJECTION condition is not actively being trapped, the new instance that is returned will be empty.

    Here is an example of the use of two sets.

    Here is an example that shows how the set can be sorted in reverse collating order.

    Here is an example that shows how a set can be sorted in a custom order. The customSort class is defined below.

    Here is an example of a customSort class:

    1.30 Socket -- extends Object

    The Socket class provides TCP/IP socket capabilities. The class can be used for UDP datagram clients or servers, or TCP clients.

    Note: the Socket class cannot be used to implement TCP servers.

    1.30.1 Methods:

    1.31 Stack -- extends Vector

    The Stack class is excellent for storing an arbitrary collection of heterogeneous objects. These are normally accessed at the beginning or the end. Other methods of the vector class are also available; such as: isEmpty, isNonEmpty, setAt, size, and toString.

    1.31.1 Methods:

    1.32 System -- extends Object

    The System class is used to access the system name, and other system information.

    1.32.1 System class methods

    1.33 SystemPropertyMap -- extends Map

    The SystemPropertyMap class is used to reference and revise system properties (aka environment variables).

    1.33.1 Methods:

    The SystemPropertyMap class has the same methods as the map class. The following methods have additional considerations.

    The following shows how all environment variables can be displayed.

    You can prepare an HTML table containing all system properties as follows.

    Observe: the addMap and copyMap methods are supported, but have no effect when applied to a SystemPropertyMap instance. This avoids accidental, undesired revisions to system properties.

    1.34 Table -- extends List, non-instantiable

    The Table class is a list of vectors. A set of column headings is defined when the table is constructed. Each list element is called a row. Each of the vectors in a row has a fixed number of items, which are called column values. The number of items in a row is the same as the number of column headings. Item values are Rexx values or instances of other objects. References to rows and columns are indexed. A request to 'getAt( 1, 1 )' retrieves the first column value in the first row.

    The following diagram may help you understand the nature of a table.

    1.34.1 Table class methods

    (*) During an add operation, if there are fewer items than the column width, empty strings are added to the other columns. If there are more items in the aggregate, an OBJECTION condition is raised if it is enabled. Otherwise, the extraneous values are ignored.

    1.35 Tree -- extends Object

    The Tree class is an arbitrary hierarchical object element. It holds three items. A content item is the value associated with this hierarchical element. A child item locates an element that is subordinate to this element. A successor item locates an element that is a subsequent peer of this element.

    The xmlTree program, and it's supporting class, is an excellent example of how the Tree class can be used to process XML information.

    1.35.1 Tree class methods, additional

    1.36 Vector -- extends Aggregate

    The Vector class is excellent for storing an arbitrary collection of heterogeneous objects. The performance of getAt and setAt requests is better than the corresponding list class. Performance is worse than the corresponding list class when items are inserted or removed at the front or the middle of the list.

    1.36.1 Methods:

    The vector class supports all aggregate class methods.

    1.37 WideCharacterVector -- Unicode-16 character values

    The WideCharacterVector class is a vector of two byte hexadecimal literals, in host byte order. It is particularly designed to be a vector of Unicode-16 character values. A reduced set of the vector class methods are supported -- getAt, removeAt, removeAll, setAt, and size.

    1.37.1 WideCharacterVector class methods, additional

    r o o ! ™
    Copyright © 2002-2014
    All Rights Reserved.
    E-Mail: rooSupport@kilowattsoftware.com

    Last updated on: 6 Mar 2011