Chapter 5. The Builtin Classes

This chapter describes all of the Rexx built-in classes.

Fundamental Classes (Section 5.1, “The Fundamental Classes”): This set of classes are the fundamental building blocks for all other classes. It includes the Object class (Section 5.1.1, “The Object Class”), the Class class (Section 5.1.2, “The Class Class”), the String class (Section 5.1.3, “The String Class”), the Method class (Section 5.1.4, “The Method Class”), the Routine class (Section 5.1.5, “The Routine Class”), the Package class (Section 5.1.6, “The Package Class”), and the Message class (Section 5.1.7, “The Message Class”.
Stream Classes (Section 5.2, “The Stream Classes”): This set of classes implement the classic Rexx streams. It includes the Stream class (Section 5.2.4, “The Stream Class”), the InputStream class (Section 5.2.1, “The InputStream Class”), the OutputStream class (Section 5.2.2, “The OutputStream Class”), and the InputOutputStream class (Section 5.2.3, “The InputOutputStream Class”).
Collection Classes (Section 5.3, “The Collection Classes”): This set of classes implement object collections. It includes the Directory class (Section 5.3.9, “The Directory Class”), the Properties class (Section 5.3.11, “The Properties Class”), the Relation class (Section 5.3.13, “The Relation Class”), the Stem class (Section 5.3.15, “The Stem Class”), the Table Class (Section 5.3.16, “The Table Class”), the IdentityTable class (Section 5.3.17, “The IdentityTable Class”), the Array class (Section 5.3.6, “The Array Class”), the List class (Section 5.3.10, “The List Class”), the Queue class (Section 5.3.12, “The Queue Class”), the CircularQueue class (Section 5.3.8, “The CircularQueue Class”), the Bag class (Section 5.3.7, “The Bag Class”), and the Set class (Section 5.3.14, “The Set Class”).
Utility Classes (Section 5.4, “The Utility Classes”): This set of classes are utility in nature and hard to classify. It includes the Alarm class (Section 5.4.2, “The Alarm Class”), the Comparable class (Section 5.4.4, “The Comparable Class”, the Comparator class (Section 5.4.6, “The Comparator Class”), the Orderable class (Section 5.4.5, “The Orderable Class”), the DateTime class (Section 5.4.1, “The DateTime Class”), the File class (Section 5.4.25, “The File Class”), the MutableBuffer class (Section 5.4.15, “The MutableBuffer Class”), the RegularExpression class (Section 5.4.16, “The RegularExpression Class”), the RexxContext class (Section 5.4.20, “The RexxContext Class”), the RexxQueue class (Section 5.4.17, “The RexxQueue Class”), the StackFrame class (Section 5.4.21, “The StackFrame Class”), the StreamSupplier class (Section 5.4.19, “The StreamSupplier Class”), the Supplier class (Section 5.4.18, “The Supplier Class”), the TimeSpan class (Section 5.4.3, “The TimeSpan Class”), and the WeakReference class (Section 5.4.22, “The WeakReference Class”).

5.1. The Fundamental Classes

This section describes the Rexx fundamental classes.

5.1.1. The Object Class

The Object class is the root of the class hierarchy. The instance methods of the Object class are, therefore, available on all objects.

Table 5.1. ooRexx Object Class

Object

new

= \= == \== <> <> ||
'' (abuttal)
' ' (blank)
class
copy
defaultName
hashCode
hasMethod
identityHash
init
instanceMethod
instanceMethods
isA

isinstanceOf
objectName
objectName=
request
run
send
sendWith
setMethod
start
startWith
string
unsetMethod

Note

The Object class also has available class methods that its metaclass, the Class class (Section 5.1.2, “The Class Class”), defines.

5.1.1.1. new (Class Method)


>>-new---------------------------------------------------------><

Returns a new instance of the receiver class.

5.1.1.2. Operator Methods


>>-comparison_operator(argument)-------------------------------><

Returns 1 (true) or 0 (false), the result of performing a specified comparison operation.

For the Object class, if argument is the same object as the receiver object, the result is 1 (true), otherwise 0 (false) is returned. Subclasses may override this method to define equality using different criteria. For example, the String class determines equality based on the value of the string data.

Note

The MapCollection classes such as Table and Relation use the == operator combined with the hashCode method (Section 5.1.1.7, “hashCode”) to determine index and item equivalence. It is generally necessary for a class to override both the hashCode method and the == operator method to maintain the contract specified for the hashCode method. See Section 5.1.1.7, “hashCode” for details on the contract.

The comparison operators you can use in a message are:

=, ==: True if the terms are the same object.
\=, ><, <>, \==: True if the terms are not the same object (inverse of =).

5.1.1.3. Concatenation Methods


>>-concatenation_operator(argument)----------------------------><

Returns a new string that is the concatenation the of receiver object's string value with argument. (See Section 1.11.2.1, “String Concatenation”.) The concatenation_operator can be:

"": concatenates without an intervening blank. The abuttal operator "" is the null string. The language processor uses the abuttal operator to concatenate two terms that another operator does not separate.
||: concatenates without an intervening blank.
" ": concatenates with one blank between the receiver object and the argument. (The operator " " is a blank.)

5.1.1.4. class


>>-class-------------------------------------------------------><

Returns the class object that created the object instance.

5.1.1.5. copy


>>-copy--------------------------------------------------------><

Returns a copy of the receiver object. The copied object has the same methods as the receiver object and an equivalent set of object variables, with the same values.

Example 5.1. Object class - copy method

myarray=.array~of("N","S","E","W")
/* Copies array myarray to array directions */
directions=myarray~copy

Note

The copy method is a "shallow copy". Only the target object is copied. Additional objects referenced by the target object are not copied. For example, copying an Array object instance only copies the array, it does not copy any of the objects stored in the array.

5.1.1.6. defaultName


>>-defaultName-------------------------------------------------><

Returns a short human-readable string representation of the object. The exact form of this representation depends on the object and might not alone be sufficient to reconstruct the object. All objects must be able to produce a short string representation of themselves in this way, even if the object does not have a string value. See Section 4.2.11, “Required String Values” for more information. The defaultName method of the Object class returns a string that identifies the class of the object, for example, an Array or a Directory. See also Section 5.1.1.15, “objectName” and Section 5.1.1.24, “string”. See Section 5.1.1.16, “objectName=” for an example using defaultName.

5.1.1.7. hashCode


>>-hashCode---------------------------------------------------><

Returns a string value that is used as a hash value for MapCollections such as Table, Relation, Set, Bag, and Directory. MapCollections use this string value to hash an object for hash table-based searches.

Object implementations are expected to abide by a general contract for hash code usage:

Whenever hashCode is invoked on the same object more than once, hashCode must return the same hashcode value, provided than none of the internal information the object uses for an "==" comparison has changed.
If two object instances compare equal using the "==" operator, the hashCode methods for both object instances must return the same value.
It is not required that two object instances that compare unequal using "==" return different hash code values.
Returning a wide range of hash values will produce better performance when an object is used as an index for a MapCollection. A return value of 4 string characters is recommended. The characters in the hash value may be any characters from '00'x to 'ff'x, inclusive.

5.1.1.8. hasMethod


>>-hasMethod(methodname)---------------------------------------><

Returns 1 (true) if the receiver object has a method named methodname (translated to uppercase). Otherwise, it returns 0 (false).

Note

The hasMethod object will return true even if the target method is defined as private. A private method has restricted access rules, so its possible to receive an unknown method error (error 97) when invoking methodname even if hasMethod indicates the method exists. See Section 4.2.8, “Public and Private Methods” for private method restrictions.

5.1.1.9. identityHash


>>-identityHash------------------------------------------------><

Returns a unique identity number for the object. This number is guaranteed to be unique for the receiver object until the object is garbage collected.

5.1.1.10. init


>>-init--------------------------------------------------------><

Performs any required object initialization. Subclasses of the Object class can override this method to provide more specific initialization.

5.1.1.11. instanceMethod


>>-instanceMethod(methodname)----------------------------------><

Returns the corresponding Method class instance if the methodname is a valid method of the class. Otherwise it returns the Nil object.

5.1.1.12. instanceMethods


>>-instanceMethods(class)----------------------------------><

Returns a Supplier instance containing the names and corresponding method objects defined by class. If the receiver object is not an instance of class, the Nil object is returned.

5.1.1.13. isA


>>-isA(class)--------------------------------------------------><

Note

This method is an alias of the isInstance (Section 5.1.1.14, “isInstanceOf”) method.

5.1.1.14. isInstanceOf


>>-isInstanceOf(class)-----------------------------------------><

Returns .true ("1") if the object is an instance of the specified class, otherwise it returns .false ("0"), An object is an instance of a class if the object is directly an instance of the specified class or if class is in the object's direct or mixin class inheritance chain. For example:

Example 5.2. Object class - isInstanceOf method


"abc"~isInstanceOf(.string)             ->  1
"abc"~isInstanceOf(.object)             ->  1
"abc"~isInstanceOf(.mutablebuffer)      ->  0

5.1.1.15. objectName


>>-objectName--------------------------------------------------><

Returns any name set on the receiver object using the objectName= method. If the receiver object does not have a name, this method returns the result of the defaultName method. See Section 4.2.11, “Required String Values” for more information. See the objectName= method for an example using objectName.

5.1.1.16. objectName=


>>-objectName=(newname)----------------------------------------><

Sets the receiver object's name to the string newname.

Example 5.3. Object class - objectName= method

points=.array~of("N","S","E","W")
say points~objectName         /* (no change yet) Says: "an Array"    */
points~objectName=("compass") /* Changes obj name POINTS to "compass"*/
say points~objectName         /* Shows new obj name. Says: "compass" */
say points~defaultName        /* Default is still available.         */
                              /* Says "an Array"                     */
say points                    /* Says string representation of       */
                              /* points "compass"                    */
say points[3]                 /* Says: "E"  Points is still an array */
                              /* of 4 items                          */

5.1.1.17. request


>>-request(classid)--------------------------------------------><

Returns an object of the classid class, or the Nil object if the request cannot be satisfied.

This method first compares the identity of the object's class (see the id method of the Class class in Section 5.1.2.8, “id”) to classid. If they are the same, the receiver object is returned as the result. Otherwise, request tries to obtain and return an object satisfying classid by sending the receiver object the conversion message make with the string classid appended (converted to uppercase). For example, a request("string") message causes a makeString message to be sent. If the object does not have the required conversion method, request returns the Nil object.

The conversion methods cause objects to produce different representations of themselves. The presence or absence of a conversion method defines an object's capability to produce the corresponding representations. For example, lists can represent themselves as arrays, because they have a makeArray method, but they cannot represent themselves as directories, because they do not have a makeDirectory method. Any conversion method must return an object of the requested class. For example, makeArray must return an array. The language processor uses the makeString method to obtain string values in certain contexts; see Section 4.2.11, “Required String Values”.

5.1.1.18. run


>>-run(method-+-------------------------------+-)--------------><
              |             +---------------+ |
              |             V               | |
              +-,Individual---+-----------+-+-+
              |               +-,argument-+   |
              +-,Array,argument---------------+

Runs the method object method (see Section 5.1.4, “The Method Class”). The method has access to the object variables of the receiver object, as if the receiver object had defined the method by using setMethod.

If you specify the Individual or Array option, any remaining arguments are arguments for the method. (You need to specify only the first letter; all characters following the first character are ignored.)

Individual: Passes any remaining arguments to the method as arguments in the order you specify them.
Array: Requires argument, which is an array object. (See Section 5.3.6, “The Array Class”.) The member items of the array are passed to the method as arguments. The first argument is at index 1, the second argument at index 2, and so on. If you omitted any indexes when creating the array, the corresponding arguments are omitted when passing the arguments.

If you specify neither Individual nor Array, the method runs without arguments.

The method argument can be a string containing a method source line instead of a method object. Alternatively, you can pass an array of strings containing individual method lines. In either case, run creates an equivalent method object.

Notes:

The run method is a private method. See Section 4.2.8, “Public and Private Methods” for information private method restrictions.
The RUN method is a protected method.

5.1.1.19. send


                    +---------------+
                    V               |
>>-send(messagename---+-----------+-+-)-----------------------><
                      +-,argument-+

Returns a result of invoking a method on the target object using the specified message name and arguments. The send() method allows methods to be invoked using dynamically constructed method names.

The messagename can be a string or an array. If messagename is an array object, its first item is the name of the message and its second item is a class object to use as the starting point for the method search. For more information, see Figure 4.1, “Classes and Inheritance (part 1 of 9)”.

Any arguments are passed to the receiver as arguments for messagename in the order you specify them.

Example 5.4. Object class - send method

world=.WorldObject~new
-- the following 3 calls are equivalent
msg1=world~hello("Fred")
msg2=world~send("HELLO", "Fred")
msg3=.message~new(world,"HELLO", "i", "Fred")~~send

say msg1                  /* Produces Hello Fred 21:04:25.065000  */
                          /* for example                          */
say msg2                  /* Produces Hello Fred 21:04:25.081000  */
                          /* for example                          */
say msg3~result           /* Produces Hello Fred 21:04:25.101000  */
                          /* for example                          */

::class 'WorldObject' public
::method hello
  use arg name
  return "Hello" name time('L')

5.1.1.20. sendWith


>>-sendWith(messagename,arguments)--------------------------------><

Returns a result of invoking a method on the target object using the specified message name and arguments. The send() method allows methods to be invoked using dynamically constructed method names and arguments.

The arguments argument must be a single-dimension array instance. The values contained in arguments are passed to the receiver as arguments for messagename in the order you specify them.

Example 5.5. Object class - sendWith method

world=.WorldObject~new
// the following 3 calls are equivalent
msg1=world~hello("Fred")
msg2=world~sendWith("HELLO", .array~of("Fred"))
msg3=.message~new(world,"HELLO", "A", .array~of("Fred"))~~send

say msg1~result           /* Produces Hello Fred 21:04:25.065000  */
                          /* for example                          */
say msg2~result           /* Produces Hello Fred 21:04:25.081000  */
                          /* for example                          */
say msg3~result           /* Produces Hello Fred 21:04:25.101000  */
                          /* for example                          */

::class 'WorldObject' public
::method hello
  use arg name
  return "Hello" name time('L')

5.1.1.21. setMethod


>>-setMethod(methodname-+----------------------+--)-----------------><
                        |         +-,"FLOAT"-+ |
                        +-,method-+----------+-+
                                  +--,scope--+

Adds a method to the receiver object's collection of object methods. The methodname is the name of the new method. This name is translated to uppercase. If you previously defined a method with the same name using setMethod, the new method replaces the earlier one. If you omit method, setMethod makes the method name methodname unavailable for the receiver object. In this case, sending a message of that name to the receiver object runs the unknown method (if any).

The method can be a string containing a method source line instead of a method object. Or it can be an array of strings containing individual method lines. In either case, setMethod creates an equivalent method object.

The third parameter describes if the method that is attached to an object should have object or float scope. "Float" scope means that it shares the same scope with methods that were defined outside of a class. "Object" scope means it shares the scope with other, potentially statically defined, methods of the object it is attached to.

Notes:

The setMethod method is a private method. See the setPrivate method in Section 5.1.4.10, “setPrivate” for details.
The setMethod method is a protected method.

5.1.1.22. start


                     +---------------+
                     V               |
>>-start(messagename---+-----------+-+-)-----------------------><
                       +-,argument-+

Returns a message object (see Section 5.1.7, “The Message Class”) and sends it a start message to start concurrent processing. The object receiving the message messagename processes this message concurrently with the sender's continued processing.

Any arguments are passed to the receiver as arguments for messagename in the order you specify them.

When the receiver object has finished processing the message, the message object retains its result and holds it until the sender requests it by sending a result message. For further details, see Section 5.1.7.11, “start”.

Example 5.6. Object class - start method

world=.WorldObject~new
msg1=world~start("HELLO")                /* same as next line     */
msg2=.message~new(world,"HELLO")~~start  /* same as previous line */

say msg1~result           /* Produces Hello world 21:04:25.065000 */
                          /* for example                          */
say msg2~result           /* Produces Hello world 21:04:25.081000 */
                          /* for example                          */

::class 'WorldObject' public
::method hello
  return "Hello world" time('L')

5.1.1.23. startWith


>>-startWith(messagename,arguments)--------------------------------><

The arguments argument must be a single-dimension array instance. Any values contained in arguments are passed to the receiver as arguments for messagename in the order you specify them.

Example 5.7. Object class - startWith method

world=.WorldObject~new
msg1=world~startWith("HELLO", .array~of("Fred")                /* same as next line     */
msg2=.message~new(world,"HELLO", 'i', .array~of("Fred"))~~start  /* same as previous line */

say msg1~result           /* Produces Hello Fred 21:04:25.065000  */
                          /* for example                          */
say msg2~result           /* Produces Hello Fred 21:04:25.081000  */
                          /* for example                          */

::class 'WorldObject' public
::method hello
  use arg name
  return "Hello" name time('L')

5.1.1.24. string


>>-string------------------------------------------------------><

Returns a human-readable string representation of the object. The exact form of this representation depends on the object and might not alone be sufficient to reconstruct the object. All objects must be able to produce a string representation of themselves in this way.

The object's string representation is obtained from the objectName method (which can in turn use the defaultName method). See also the objectName method (Section 5.1.1.15, “objectName”) and the defaultName method (Section 5.1.1.6, “defaultName”).

The distinction between this method, the makeString method (which obtains string values—see Section 5.1.3.54, “makeString”) and the request method (see Section 5.1.1.17, “request”) is important. All objects have a string method, which returns a string representation (human-readable form) of the object. This form is useful in tracing and debugging. Only those objects that have information with a meaningful string form have a makeString method to return this value. For example, directory objects have a readable string representation (a Directory), but no string value, and, therefore, no makeString method.

Of the classes that Rexx provides, only the String class has a makeString method. Any subclasses of the String class inherit this method by default, so these subclasses also have string values. Any other class can also provide a string value by defining a makeString method.

5.1.1.25. unsetMethod


>>-unsetMethod(methodname)-------------------------------------><

Cancels the effect of all previous setMethods for method methodname. It also removes any method methodname introduced with enhanced when the object was created. If the object has received no setMethod method, no action is taken.

Notes:

The unsetMethod method is a private method. See the setPrivate method in Section 5.1.4.10, “setPrivate” for details.
The unsetMethod method is a protected method.

5.1.2. The Class Class

The Class class is like a factory that produces the factories that produce objects. It is a subclass of the Object class (Section 5.1.1, “The Object Class”). The instance methods of the Class class are also the class methods of all classes.

Table 5.2. ooRexx Class Class

Object
↓
Class

= \= == \== <> >< activate baseClass defaultName define delete enhanced id inherit isSubclassOf metaClass	method methods mixinClass new queryMixinClass subClass subClasses superClass superClasses inInherit

5.1.2.1. Inherited Methods

Methods inherited from the Object class (Section 5.1.1, “The Object Class”).

new (Class Method)	init	send
= \= == \== <> ><	instanceMethod	sendWith
\|\| '' (abuttal)' ' (blank)	instanceMethods	setMethod
(Operator Methods)	isA	start
class	isInstanceOf	startWith
copy	objectName	string
defaultName	objectName=	unsetMethod
hasMethod	request
identityHash	run

5.1.2.2. activate


>>-activate----------------------------------------------------><

Completes initialization of a class object created from a ::CLASS directive. The activate method is called after all classes in a package have been created and made available, but before execution of the main portion of the program starts to execute. Activate is called for each class in the package in their construction order. The class object is fully constructed and capable of creating new instances of the class. All other classes in the same package are also available, although other classes might not have been activated yet. Because the INIT method is called early in the class construction process, only limited class initialization is possible at that time. The activate method is the prefered method for initializing a class object.

5.1.2.3. baseClass


>>-baseClass---------------------------------------------------><

Returns the base class associated with the class. If the class is a mixin class, the base class is the first superclass that is not also a mixin class. If the class is not a mixin class, the base class is the class receiving the baseClass message.

5.1.2.4. defaultName


>>-defaultName-------------------------------------------------><

Returns a short human-readable string representation of the class. The string returned is of the form

The id class

where id is the identifier assigned to the class when it was created.

Example 5.8. Class class - defaultName method

say .array~defaultName     /* Displays "The Array class"   */
say .account~defaultName   /* Displays "The ACCOUNT class" */
say .savings~defaultName   /* Displays "The Savings class" */

::class account            /* Name is all upper case       */
::class "Savings"          /* String name is mixed case    */

5.1.2.5. define


>>-define(methodname-+---------+-)-----------------------------><
                     +-,method-+

Incorporates the method object method in the receiver class's collection of instance methods. The method name methodname is translated to to uppercase. Using the define method replaces any existing definition for methodname in the receiver class.

If you omit method, the method name methodname is made unavailable for the receiver class. Sending a message of that name to an instance of the class causes the unknown method (if any) to be run.

The method argument can be a string containing a method source line instead of a method object. Alternatively, you can pass an array of strings containing individual method lines. Either way, define creates an equivalent method object.

Notes:

The classes Rexx provides do not permit changes or additions to their method definitions.
The define method is a protected method.

Example 5.9. Class class - define method

bank_account=.object~subclass("Account")
bank_account~define("TYPE",'return "a bank account"')

5.1.2.6. delete


>>-delete(methodname)------------------------------------------><

Removes the receiver class's definition for the method name methodname. If the receiver class defined methodname as unavailable with the define method, this definition is nullified. If the receiver class had no definition for methodname, no action is taken.

Notes:

The classes Rexx provides do not permit changes or additions to their method definitions.
delete deletes only methods the target class defines. You cannot delete inherited methods the target's superclasses define.
The delete method is a protected method.

Example 5.10. Class class - delete method

myclass=.object~subclass("Myclass")        /* After creating a class  */
myclass~define("TYPE",'return "my class"') /* and defining a method   */
myclass~delete("TYPE")                     /* this deletes the method */

5.1.2.7. enhanced


>>-enhanced(methods-+---------------+-)------------------------><
                    | +-----------+ |
                    | V           | |
                    +---,argument-+-+

Returns an enhanced new instance of the receiver class, with object methods that are the instance methods of the class, enhanced by the methods in the collection methods. The collection indexes are the names of the enhancing methods, and the items are the method objects (or strings or arrays of strings containing method code). (See the description of define (Section 5.1.2.5, “define”.) You can use any collection that supports a supplier method.

enhanced sends an init message to the created object, passing the arguments specified on the enhanced method.

Example 5.11. Class class - enhanced method

/* Set up rclass with class method or methods you want in your */
/* remote class */
rclassmeths = .directory~new

rclassmeths["DISPATCH"]=d_source     /* d_source must have code for a  */
                                     /* DISPATCH  method.              */
/* The following sends init("Remote Class") to a new instance */
rclass=.class~enhanced(rclassmeths,"Remote Class")

5.1.2.8. id


>>-id----------------------------------------------------------><

Returns the class identity (instance) string. (This is the string that is an argument on the subClass and mixinClass methods.) The string representations of the class and its instances contain the class identity.

Example 5.12. Class class - id method

myobject=.object~subClass("my object")  /* Creates a subclass    */
say myobject~id                         /* Produces: "my object" */

5.1.2.9. inherit


>>-inherit(classobj-+-----------+-)----------------------------><
                    +-,classpos-+

Causes the receiver class to inherit the instance and class methods of the class object classobj. The classpos is a class object that specifies the position of the new superclass in the list of superclasses. (You can use the superClasses method to return the immediate superclasses.)

The new superclass is inserted in the search order after the specified class. If the classpos class is not found in the set of superclasses, an error is raised. If you do not specify classpos, the new superclass is added to the end of the superclasses list.

Inherited methods can take precedence only over methods defined at or above the base class of the classobj in the class hierarchy. Any subsequent change to the instance methods of classobj takes immediate effect for all the classes that inherit from it.

The new superclass classobj must be created with the mixinClass option of the ::CLASS directive or the mixinClass method and the base class of the classobj must be a direct superclass of the receiver object. The receiver must not already descend from classobj in the class hierarchy and vice versa.

The method search order of the receiver class after inherit is the same as before inherit, with the addition of classobj and its superclasses (if not already present).

Notes:

You cannot change the classes that Rexx provides by sending inherit messages.
The inherit method is a protected method.

Example 5.13. Class class - inherit method

room~inherit(.location)

5.1.2.10. isSubClassOf


>>-isSubclassOf(class)-------------------------------------><

Returns .true ("1") if the object is a subclass of the specified class. Returns .false ("0") if the object is not a subclass of the specified class. A class is a subclass of a class if the target class is the same as class or if class is in the object's direct or mixin class inheritance chain. For example:

Example 5.14. Class class - isSubclassOf method


.String~isSubclassOf(.object)             ->  1
.String~isSubclassOf(.mutablebuffer)      ->  0

5.1.2.11. metaClass


>>-metaClass---------------------------------------------------><

Returns the receiver class's default metaclass. This is the class used to create subclasses of this class when you send subClass or mixinClass messages (with no metaclass arguments). The instance methods of the default metaclass are the class methods of the receiver class. For more information about class methods, see Section 4.1.1, “Object Classes”. See also the description of the subClass method in Section 5.1.2.17, “subclass”.

5.1.2.12. method


>>-method(methodname)------------------------------------------><

Returns the method object for the receiver class's definition for the method name methodname. If the receiver class defined methodname as unavailable, this method returns the Nil object. If the receiver class did not define methodname, an error is raised.

Example 5.15. Class class - method method

/* Create and retrieve the method definition of a class */
myclass=.object~subClass("My class")   /* Create a class         */
mymethod=.method~new(" ","Say arg(1)") /* Create a method object */
myclass~define("ECHO",mymethod)        /* Define it in the class */
method_source = myclass~method("ECHO")~source     /* Extract it  */
say method_source                 /* Says "an Array"              */
say method_source[1]              /* Shows the method source code */

5.1.2.13. methods


>>-methods-+----------------+----------------------------------><
           +-(class_object)-+

Returns a Supplier object (Section 5.4.18, “The Supplier Class”) for all the instance methods of the receiver class and its superclasses, if you specify no argument. If class_object is the Nil object, methods returns a supplier object for only the instance methods of the receiver class. If you specify a class_object, this method returns a supplier object containing only the instance methods that class_object defines. The supplier enumerates all the names and methods existing at the time of the supplier's creation.

Note

Methods that have been hidden with a setMethod or define method are included with the other methods that methods returns. The hidden methods have the Nil object for the associated method.

Example 5.16. Class class - methods method

objsupp=.object~methods
do while objsupp~available
say objsupp~index           -- displays all instance method
objsupp~next                -- names of the Object class
end

5.1.2.14. mixinClass


>>-mixinClass(classid-+-------------------------+-)------------><
                      +-,metaclass-+----------+-+
                                   +-,methods-+

Returns a new mixin subclass of the receiver class. You can use this method to create a new mixin class that is a subclass of the superclass to which you send the message. The classid is a string that identifies the new mixin subclass. You can use the id method to retrieve this string.

The metaclass is a class object. If you specify metaclass, the new subclass is an instance of metaclass. (A metaclass is a class that you can use to create a class, that is, a class whose instances are classes. The Class class and its subclasses are metaclasses.)

If you do not specify a metaclass, the new mixin subclass is an instance of the default metaclass of the receiver class. For subclasses of the Object class, the default metaclass is the Class class.

The methods is a collection whose indexes are the names of methods and whose items are method objects (or strings or arrays of strings containing method code). If you specify methods, the new class is enhanced with class methods from this collection. (The metaclass of the new class is not affected.)

The metaClass method returns the metaclass of a class.

The method search order of the new subclass is the same as that of the receiver class, with the addition of the new subclass at the start of the order.

Example 5.17. Class class - mixinClass method

buyable=.object~mixinClass("Buyable")  /* New subclass is buyable    */
                                       /* Superclass is Object class */

5.1.2.15. new


>>-new-+---------------+---------------------------------------><
       |    +-,---+    |
       |    V     |    |
       +-(----arg-+--)-+

Returns a new instance of the receiver class, whose object methods are the instance methods of the class. This method initializes a new instance by running its init methods. (See Section 4.2.9, “Initialization”.) new also sends an init message. If you specify args, new passes these arguments on the init message.

Example 5.18. Class class - new method


/* new method example */
a = .account~new             /* -> Object variable balance=0           */
y = .account~new(340.78)     /* -> Object variable balance=340.78      */
                             /*    plus free toaster oven              */
::class account subclass object
::method init                /* Report time each account created       */
                             /* plus free toaster when more than $100  */
Expose balance
Arg opening_balance
Say "Creating" self~objectName "at time" time()
If datatype(opening_balance, "N") then balance = opening_balance
else balance = 0
If balance > 100 then Say "  You win a free toaster oven"

5.1.2.16. queryMixinClass


>>-queryMixinClass---------------------------------------------><

Returns 1 (true) if the class is a mixin class, or 0 (false).

5.1.2.17. subclass


>>-subclass(classid-+-------------------------+-)--------------><
                    +-,metaclass-+----------+-+
                                 +-,methods-+

Returns a new subclass of the receiver class. You can use this method to create a new class that is a subclass of the superclass to which you send the message. The classid is a string that identifies the subclass. (You can use the id method to retrieve this string.)

If you do not specify a metaclass, the new subclass is an instance of the default metaclass of the receiver class. For subclasses of the Object class, the default metaclass is the Class class.

The metaclass method returns the metaclass of a class.

The method search order of the new subclass is the same as that of the receiver class, with the addition of the new subclass at the start of the order.

Example 5.19. Class class - subclass method

room=.object~subclass("Room")   /* Superclass is .object     */
                                /* Subclass is room          */
                                /* Subclass identity is Room */

5.1.2.18. subclasses


>>-subclasses--------------------------------------------------><

Returns the immediate subclasses of the receiver class in the form of a single-index array of the required size, in an unspecified order. (The program should not rely on any order.)

5.1.2.19. superClass


>>-superClass------------------------------------------------><

Returns the immediate superclass of the receiver class. The immediate superclass is the original class used on a subClass or a mixinClass method. For the Object Class, superClass returns .Nil.

Example 5.20. Class class - superClass method

say .object~superclass    -- displays "The NIL object"
say .class~superclass     -- displays "The Object class"
say .set~superclass       -- displays "The Table class"

5.1.2.20. superClasses


>>-superClasses------------------------------------------------><

Returns the immediate superclasses of the receiver class in the form of a single-index array of the required size. The immediate superclasses are the original class used on a subClass or a mixinClass method, plus any additional superclasses defined with the inherit method. The array is in the order in which the class has inherited the classes. The original class used on a subClass or mixinClass method is the first item of the array.

Example 5.21. Class class - superClasses method

z=.class~superClasses
/* To obtain the information this returns, you could use:     */
do i over z
  say i
end

5.1.2.21. uninherit


>>-uninherit(classobj)-----------------------------------------><

Nullifies the effect of any previous inherit message sent to the receiver for the class classobj.

Note

You cannot change the classes that Rexx provides by sending uninherit messages.

Example 5.22. Class class - uninherut method

location=.object~mixinClass("Location")
room=.object~subclass("Room")~~inherit(location) /* Creates subclass */
/* and specifies inheritance */
room~uninherit(location)

5.1.3. The String Class

String objects represent character-string data values. A character string value can have any length and contain any characters.

Table 5.3. ooRexx String Class

Object
↓
String
+ Comparable
new cr nl null tab
+ - * ** / // % \ = \= <> >< == \== > >= \> < <= \< >> >>= << <<= \<< \>> & && \| \|\| '' (abuttal) ' ' (blank) abbrev abs b2x bitAnd bitOr bitXor c2d c2x caselessAbbrev caselessChangeStr caselessCompare caselessCompareTo caselessCountStr caselessEquals caselessLastPos caselessMatch caselessMatchChar caselessPos caselessWordPos ceiling	center/centre changeStr compare compareTo copies countStr d2c d2x dataType decodeBase64 delStr delWord encodeBase64 equals floor format hashCode insert lastPos left length lower makeArray makeString match matchChar max min	overlay pos replaceAt reverse right round sign space strip subChar subStr subWord subWords translate trunc upper verify word wordIndex wordLength wordPos words x2b x2c x2d

Note

The String class also has available class methods that its metaclass, the Class class (Section 5.1.2, “The Class Class”, defines.

5.1.3.1. Inherited Methods

Methods inherited from the Object class (Section 5.1.1, “The Object Class”.

new (Class Method)	init	send
= \= == \== <> ><	instanceMethod	sendWith
\|\| '' (abuttal)' ' (blank)	instanceMethods	setMethod
(Operator Methods)	isA	start
class	isInstanceOf	startWith
copy	objectName	string
defaultName	objectName=	unsetMethod
hasMethod	request
identityHash	run

Methods inherited from the Comparable class (Section 5.4.4, “The Comparable Class”.

compareTo

5.1.3.2. new (Class Method)


>>-new(stringvalue)--------------------------------------------><

Returns a new string object initialized with the characters in stringvalue.

5.1.3.3. nl (Class Method)


>>-nl----------------------------------------------------------><

Returns the single character string for the new line character, which has the value '0a'x.

5.1.3.4. cr Class Method)


>>-cr----------------------------------------------------------><

Returns the single character string for the carriage return character, which has the value '0d'x.

5.1.3.5. null Class Method)


>>-null--------------------------------------------------------><

Returns the single character string for the null character, which has the value '00'x.

5.1.3.6. tab Class Method)


>>-tab---------------------------------------------------------><

Returns the single character string for the tab character, which has the value '09'x.

5.1.3.7. Arithmetic Methods


>>-arithmetic_operator(argument)-------------------------------><

Note

The syntax diagram above is for the non-prefix operators. The prefix + and argument.

Returns the result of performing the specified arithmetic operation on the receiver object. The receiver object and the argument must be valid numbers (see Section 1.10.4.5, “Numbers”). The arithmetic_operator can be:

+	Addition
-	Subtraction
*	Multiplication
/	Division
%	Integer division (divide and return the integer part of the result)
//	Remainder (divide and return the remainder—not modulo, because the result can be negative)
**	Exponentiation (raise a number to a whole-number power)
Prefix -	Same as the subtraction: `0 - number`
Prefix +	Same as the addition: `0 + number`

See Chapter 10, Numbers and Arithmetic for details about precision, the format of valid numbers, and the operation rules for arithmetic. Note that if an arithmetic result is shown in exponential notation, it might have been rounded.

Example 5.23. String class - arithmetic methods


5+5     ->    10
8-5     ->     3
5*2     ->    10
6/2     ->     3
9//4    ->     1
9%4     ->     2
2**3    ->     8
+5      ->     5             /* Prefix +  */
-5      ->    -5             /* Prefix -  */

5.1.3.8. Comparison Methods


>>-comparison_operator(argument)-------------------------------><

Returns 1 (true) or 0 (false), the result of performing the specified comparison operation. The receiver object and the argument are the terms compared. Both must be string objects. If argument is not a string object, it is converted to its string representation for the comparison. The one exception is when argument is the Nil object for the ==, \==, =, \=, ><, and <> operators. A string object will never compare equal to the Nil object, even when the string matches the string value of the Nil object ("The NIL object"). As a result, == will always return 0 (false) when compared to the Nil object and \== will always return 1 (true). All of the relational comparisions (for example, <, >, <=, etc.) will always return .false when compared to the Nil object.

The comparison operators you can use in a message are:

=	True if the terms are equal (for example, numerically or when padded). False if argument is the Nil object.
\=, ><, <>	True if the terms are not equal (inverse of =). True if argument is the Nil object.
>	Greater than. False if argument is the Nil object.
<	Less than. False if argument is the Nil object.
>=	Greater than or equal to. False if argument is the Nil object.
\<	Not less than. False if argument is the Nil object.
<=	Less than or equal to. False if argument is the Nil object.
\>	Not greater than. False if argument is the Nil object.

Example 5.24. String class - comparison methods


5=5        ->     1          /* equal            */

42\=41     ->     1          /* All of these are */
42><41     ->     1          /* "not equal"      */
42<>41     ->     1

13>12      ->     1          /* Variations of    */
12<13      ->     1          /* less than and    */
13>=12     ->     1          /* greater than     */
12\<13     ->     0
12<=13     ->     1
12\>13     ->     1

All strict comparison operations have one of the characters doubled that define the operator. The == and \== operators check whether two strings match exactly. The two strings must be identical (character by character) and of the same length to be considered strictly equal.

The strict comparison operators such as >> or << carry out a simple character-by-character comparison. There is no padding of either of the strings being compared. The comparison of the two strings is from left to right. If one string is shorter than and a leading substring of another, then it is smaller than (less than) the other. The strict comparison operators do not attempt to perform a numeric comparison on the two operands.

For all the other comparison operators, if both terms are numeric, the String class does a numeric comparison (ignoring, for example, leading zeros— see Section 10.4, “Numeric Comparisons”). Otherwise, it treats both terms as character strings, ignoring leading and trailing whitespace characters and padding the shorter string on the right with blanks.

Character comparison and strict comparison operations are both case-sensitive, and for both the exact collating order can depend on the character set. In an ASCII environment, the digits are lower than the alphabetic characters, and lowercase alphabetic characters are higher than uppercase alphabetic characters.

The strict comparison operators you can use in a message are:

==	True if terms are strictly equal (identical)
\==	True if the terms are NOT strictly equal (inverse of ==)
>>	Strictly greater than
<<	Strictly less than
>>=	Strictly greater than or equal to
\<<	Strictly NOT less than
<<=	Strictly less than or equal to
\>>	Strictly NOT greater than

Example 5.25. String class - comparison methods


"space"=="space"     ->     1         /* Strictly equal     */

"space"\==" space"   ->     1         /* Strictly not equal */

"space">>" space"    ->     1         /* Variations of      */
" space"<<"space"    ->     1         /* strictly greater   */
"space">>=" space"   ->     1         /* than and less than */
"space"\<<" space"   ->     1
" space"<<="space"   ->     1
" space"\>>"space"   ->     1

5.1.3.9. Logical Methods


>>-logical_operator(argument)----------------------------------><

Note

For NOT (prefix \), omit the parentheses and argument.

Returns 1 (true) or 0 (false), the result of performing the specified logical operation. The receiver object and the argument are character strings that evaluate to 1 or 0.

The logical_operator can be:

&	AND (Returns `1` if both terms are true.)
\|	Inclusive OR (Returns `1` if either term or both terms are true.)
&&	Exclusive OR (Returns `1` if either term, but not both terms, is true.)
Prefix \	Logical NOT (Negates; `1` becomes `0`, and `0` becomes `1`.)

Example 5.26. String class - logical methods


1&0     ->     0
1|0     ->     1
1&&0    ->     1
\1      ->     0

5.1.3.10. Concatenation Methods


>>-concatenation_operator(argument)----------------------------><

Concatenates the receiver object with argument. (See Section 1.11.2.1, “String Concatenation”.) The concatenation_operator can be:

""	concatenates without an intervening blank. The abuttal operator "" is the null string. The language processor uses the abuttal to concatenate two terms that another operator does not separate.
\|\|	concatenates without an intervening blank.
" "	concatenates with one blank between the receiver object and the argument. (The operator " " is a blank.)

Example 5.27. String class - concatenation methods


f = "abc"
f"def"      ->   "abcdef"
f || "def"  ->   "abcdef"
f "def"     ->   "abc def"

5.1.3.11. abbrev


>>-abbrev(info-+---------+-)-----------------------------------><
               +-,length-+

Returns 1 if info is equal to the leading characters of the receiving string and the length of info is not less than length. Returns 0 if either of these conditions is not met.

If you specify length, it must be a positive whole number or zero. The default for length is the number of characters in info.

Example 5.28. String class - abbrev method


"Print"~abbrev("Pri")      ->    1
"PRINT"~abbrev("Pri")      ->    0
"PRINT"~abbrev("PRI",4)    ->    0
"PRINT"~abbrev("PRY")      ->    0
"PRINT"~abbrev("")         ->    1
"PRINT"~abbrev("",1)       ->    0

Note

A null string always matches if a length of 0, or the default, is used. This allows a default keyword to be selected automatically if desired.

Example 5.29. String class - abbrev method

say "Enter option:";   pull option .
select  /* keyword1 is to be the default */
  when "keyword1"~abbrev(option) then ...
  when "keyword2"~abbrev(option) then ...
  ...
  otherwise nop;
end;

5.1.3.12. abs


>>-abs---------------------------------------------------------><

Returns the absolute value of the receiving string. The result has no sign and is formatted according to the current NUMERIC settings.

Example 5.30. String class - abs method

12.3~abs      ->     12.3
"-0.307"~abs  ->     0.307

5.1.3.13. b2x


>>-b2x---------------------------------------------------------><

Returns a string, in character format, that represents the receiving binary string converted to hexadecimal.

The receiving string is a string of binary (0 or 1) digits. It can be of any length. It can optionally include whitespace characters (at 4-digit boundaries only, not leading or trailing). These are to improve readability and are ignored.

The returned string uses uppercase alphabetic characters for the values A-F and does not include whitespace.

If the receiving binary string is a null string, b2x returns a null string. If the number of binary digits in the receiving string is not a multiple of four, up to three 0 digits are added on the left before the conversion to make a total that is a multiple of four.

Example 5.31. String class - b2x method


"11000011"~b2x     ->   "C3"
"10111"~b2x        ->   "17"
"101"~b2x          ->   "5"
"1 1111 0000"~b2x  ->   "1F0"

You can combine b2x with the methods x2d and x2c to convert a binary number into other forms.

Example 5.32. String class - b2x method with x2d

"10111"~b2x~x2d  ->   "23"   /* decimal 23 */

5.1.3.14. bitAnd


>>-bitAnd-+--------------------+-------------------------------><
          +-(string-+------+-)-+
                    +-,pad-+

Returns a string composed of the receiver string and the argument string logically ANDed together, bit by bit. (The encodings of the strings are used in the logical operation.) The length of the result is the length of the longer of the two strings. If you omit the pad character, the AND operation stops when the shorter of the two strings is exhausted, and the unprocessed portion of the longer string is appended to the partial result. If you provide pad, it extends the shorter of the two strings on the right before the logical operation. The default for string is the zero-length (null) string.

Example 5.33. String class - bitand method


"12"x~bitAnd                   ->    "12"x
"73"x~bitAnd("27"x)            ->    "23"x
"13"x~bitAnd("5555"x)          ->    "1155"x
"13"x~bitAnd("5555"x,"74"x)    ->    "1154"x
"pQrS"~bitAnd(,"DF"x)          ->    "PQRS"      /* ASCII   */

5.1.3.15. bitOr


>>-bitOr-+--------------------+--------------------------------><
         +-(string-+------+-)-+
                   +-,pad-+

Returns a string composed of the receiver string and the argument string logically inclusive-ORed, bit by bit. The encodings of the strings are used in the logical operation. The length of the result is the length of the longer of the two strings. If you omit the pad character, the OR operation stops when the shorter of the two strings is exhausted, and the unprocessed portion of the longer string is appended to the partial result. If you provide pad, it extends the shorter of the two strings on the right before the logical operation. The default for string is the zero-length (null) string.

Example 5.34. String class - bitor method


"12"x~bitOr                   ->    "12"x
"15"x~bitOr("24"x)            ->    "35"x
"15"x~bitOr("2456"x)          ->    "3556"x
"15"x~bitOr("2456"x,"F0"x)    ->    "35F6"x
"1111"x~bitOr(,"4D"x)         ->    "5D5D"x
"pQrS"~bitOr(,"20"x)          ->    "pqrs" /* ASCII   */

5.1.3.16. bitXor


>>-bitXor-+--------------------+-------------------------------><
          +-(string-+------+-)-+
                    +-,pad-+

Returns a string composed of the receiver string and the argument string logically eXclusive-ORed, bit by bit. The encodings of the strings are used in the logical operation. The length of the result is the length of the longer of the two strings. If you omit the pad character, the XOR operation stops when the shorter of the two strings is exhausted, and the unprocessed portion of the longer string is appended to the partial result. If you provide pad, it extends the shorter of the two strings on the right before carrying out the logical operation. The default for string is the zero-length (null) string.

Example 5.35. String class - bitxor method


"12"x~bitXor                      ->  "12"x
"12"x~bitXor("22"x)               ->  "30"x
"1211"x~bitXor("22"x)             ->  "3011"x
"1111"x~bitXor("444444"x)         ->  "555544"x
"1111"x~bitXor("444444"x,"40"x)   ->  "555504"x
"1111"x~bitXor(,"4D"x)            ->  "5C5C"x
"C711"x~bitXor("222222"x," ")     ->  "E53302"x  /* ASCII  */

5.1.3.17. c2d


>>-c2d-+-----+-------------------------------------------------><
       +-(n)-+

Returns the decimal value of the binary representation of the receiving string. If the result cannot be expressed as a whole number, an error results. That is, the result must not have more digits than the current setting of NUMERIC DIGITS. If you specify n, it is the length of the returned result. If you do not specify n, the receiving string is processed as an unsigned binary number. If the receiving string is null, C2D returns 0.

Example 5.36. String class - c2d method


"09"X~c2d       ->        9
"81"X~c2d       ->      129
"FF81"X~c2d     ->    65409
""~c2d          ->        0
"a"~c2d         ->       97     /*  ASCII   */

If you specify n, the receiving string is taken as a signed number expressed in n characters. The number is positive if the leftmost bit is off, and negative if the leftmost bit is on. In both cases, it is converted to a whole number, which can therefore be negative. The receiving string is padded on the left with "00"x characters (not "sign-extended"), or truncated on the left to n characters. This padding or truncation is as though receiving_string~right(n,'00'x) had been processed. If n is 0, c2d always returns 0.

Example 5.37. String class - c2d method


"81"X~c2d(1)      ->     -127
"81"X~c2d(2)      ->      129
"FF81"X~c2d(2)    ->     -127
"FF81"X~c2d(1)    ->     -127
"FF7F"X~c2d(1)    ->      127
"F081"X~c2d(2)    ->    -3967
"F081"X~c2d(1)    ->     -127
"0031"X~c2d(0)    ->        0

5.1.3.18. c2x


>>-c2x---------------------------------------------------------><

Returns a string, in character format, that represents the receiving string converted to hexadecimal. The returned string contains twice as many bytes as the receiving string. On an ASCII system, sending a c2x message to the receiving string 1 returns 31 because "31"X is the ASCII representation of 1.

The returned string has uppercase alphabetic characters for the values A-F and does not include whitespace. The receiving string can be of any length. If the receiving string is null, c2x returns a null string.

Example 5.38. String class - c2x method


"0123"X~c2x    ->    "0123"   /* "30313233"X     in ASCII */
"ZD8"~c2x      ->    "5A4438" /* "354134343338"X in ASCII */

5.1.3.19. caselessAbbrev


>>-caselessAbbrev(info-+---------+-)-----------------------------------><
                       +-,length-+

Returns 1 if info is equal to the leading characters of the receiving string and the length of info is not less than length. Returns 0 if either of these conditions is not met. The characters are tested using a caseless comparison.

If you specify length, it must be a positive whole number or zero. The default for length is the number of characters in info.

Example 5.39. String class - caselessAbbrev method


"Print"~caselessAbbrev("Pri")      ->    1
"PRINT"~caselessAbbrev("Pri")      ->    1
"PRINT"~caselessAbbrev("PRI",4)    ->    0
"PRINT"~caselessAbbrev("PRY")      ->    0
"PRINT"~caselessAbbrev("")         ->    1
"PRINT"~caselessAbbrev("",1)       ->    0

Note

A null string always matches if a length of 0, or the default, is used. This allows a default keyword to be selected automatically if desired.

Example 5.40. String class - caselessAbbrev method

say "Enter option:";   parse pull option .
select  /* keyword1 is to be the default */
  when "keyword1"~caselessAbbrev(option) then ...
  when "keyword2"~caselessAbbrev(option) then ...
  ...
  otherwise nop;
end;

5.1.3.20. caselessChangeStr


>>-caselessChangeStr(needle,newneedle--+--------+--)---------------------------------><
                                       +-,count-+

Returns a copy of the receiver object in which newneedle replaces occurrences of needle. If count is not specified, all occurrences of needle are replaced. If count is specified, it must be a positive, whole number that gives the maximum number of occurrences to be replaced. The needle searches are performed using caseless comparisons.

Here are some examples:

Example 5.41. String class - caselessChangeStr method


"AbaAbb"~caselessChangeStr("A","")     ->    "bbb"
AbaBabAB~changeStr("ab","xy")          ->    "xyxyxyxy"
AbaBabAB~changeStr("ab","xy",1)        ->    "xyaBabAB"

5.1.3.21. caselessCompare


>>-caselessCompare(string-+------+-)-----------------------------------><
                          +-,pad-+

Returns 0 if the argument string is identical to the receiving string using a caseless comparison. Otherwise, returns the position of the first character that does not match. The shorter string is padded on the right with pad if necessary. The default pad character is a blank.

Example 5.42. String class - caselessCompare method


"abc"~caselessCompare("ABC")         ->    0
"abc"~caselessCompare("Ak")          ->    2
"ab "~caselessCompare("AB")          ->    0
"AB "~caselessCompare("ab"," ")      ->    0
"ab "~caselessCompare("ab","x")      ->    3
"abXX "~caselessCompare("ab","x")    ->    5

5.1.3.22. caselessCompareTo


>>-caselessCompareTo(string-+-----------------------+-)----------------------><
                            +-,--+---+--+---------+-+
                                 +-n-+  +-,length-+

Performs a caseless sort comparison of the target string to the string argument. If the two strings are equal, 0 is returned. If the target string is larger, 1 is returned. -1 if the string argument is the larger string. The comparison is performed starting at character n for length characters in both strings. n must be a positive whole number. If n is omitted, the comparison starts at the first character. length must be a non-negative whole number. If omitted, the comparison will take place to the end of the target string.

Example 5.43. String class - caselessCompareTo method



"abc"~caselessCompareTo("abc")         ->    0
"b"~caselessCompareTo("a")             ->    1
"a"~caselessCompareTo("b")             ->   -1
"abc"~caselessCompareTo("aBc")         ->    0
"aBc"~caselessCompareTo("abc")         ->    0
"000abc000"~caselessCompareTo(111abc111", 4, 3)  -> 0

5.1.3.23. caselessCountStr


>>-caselessCountStr(needle)--------------------------------------------><

Returns a count of the occurrences of needle in the receiving string that do not overlap. All matches are made using caseless comparisons.

Here are some examples:

Example 5.44. String class - caselessCountStr method


"a0Aa0A"~caselessCountStr("a")        ->    4
"J0kKk0"~caselessCountStr("KK")       ->    1

5.1.3.24. caselessEquals


>>-caselessEquals(other)-----------------------------------------------><

Returns .true ("1") if the target string is strictly equal to the other string, using a caseless comparison. Returns .false ("0") if the two strings are not strictly equal.

Example 5.45. String class - caselessEquals method

"a"~caselessEquals("A")          ->    1
"aa"~caselessEquals("A")         ->    0
"4"~caselessEquals("3")          ->    0

5.1.3.25. caselessLastPos


>>-caselessLastPos(needle-+---------------------------+-)---><
                          +-,--+-------+--+---------+-+
                               +-start-+  +-,length-+

Returns the position of the last occurrence of a string, needle, in the receiving string. (See also Section 5.1.3.60, “pos”.) It returns 0 if needle is the null string or not found. By default, the search starts at the last character of the receiving string and scans backward to the beginning of the string. You can override this by specifying start, the point at which the backward scan starts and length, the range of characters to scan. The start must be a positive whole number and defaults to receiving_string~length if larger than that value or omitted. The length must be a non-negative whole number and defaults to start. The search is performed using caseless comparisons.

Example 5.46. String class - caselessLastPos method

"abc def ghi"~caselessLastPos(" ")      ->    8
"abcdefghi"~caselessLastPos(" ")        ->    0
"efgxyz"~caselessLastPos("XY")          ->    4
"abc def ghi"~caselessLastPos(" ",7)    ->    4
"abc def ghi"~caselessLastPos(" ",7,3)  ->    0

5.1.3.26. caselessMatch


>>-caselessMatch(start,other-+----------------------------+-)-------------------><
                             +-,--+---+--+---------+------+
                                  +-n-+  +-,length-+

Returns .true ("1") if the characters of the other match the characters of the target string beginning at position start. Return .false ("0") if the characters are not a match. The matching is performed using caseless comparisons. start must be a positive whole number less than or equal to the length of the target string.

If n is specified, the match will be performed starting with character n of other. The default value for n is "1". n must be a positive whole number less than or equal to the length of other.

If length is specified, it defines a substring of other that is used for the match. length must be a positive whole number and the combination of n and length must be a valid substring within the bounds of other.

The caselessMatch method is useful for efficient string parsing as it does not require new string objects be extracted from the target string.

Example 5.47. String class - caselessMatch method

"Saturday"~caselessMatch(6, "day")           ->    1
"Saturday"~caselessMatch(6, "DAY")           ->    1
"Saturday"~caselessMatch(6, "SUNDAY", 4, 3)  ->    1
"Saturday"~caselessMatch(6, "daytime", 1, 3) ->    1

5.1.3.27. caselessMatchChar


>>-caselessMatchChar(n,chars)-------------------------><

Returns .true ("1") if the character at position n matches any character of the string chars. Returns .false ("0") if the character does not match any of the characters in the reference set. The match is made using caseless comparisons. The argument n must be a positive whole number less than or equal to the length of the target string.

Example 5.48. String class - caselessMatchChar method

"a+b"~caselessMatchChar(2, "+-*/")           ->    1
"a+b"~caselessMatchChar(1, "+-*/")           ->    0
"Friday"~caselessMatchChar(3, "aeiou")       ->    1
"FRIDAY"~caselessMatchChar(3, "aeiou")       ->    1

5.1.3.28. caselessPos


>>-caselessPos(needle-+---------------------------+-)---><
                      +-,--+-------+--+---------+-+
                           +-start-+  +-,length-+

Returns the position in the receiving string of another string, needle. (See also Section 5.1.3.49, “lastPos”.) It returns 0 if needle is the null string or is not found or if start is greater than the length of the receiving string. The search is performed using caseless comparisons. By default, the search starts at the first character of the receiving string (that is, the value of start is 1), and continues to the end of the string. You can override this by specifying start , the point at which the search starts, and length, the bounding limit for the search. If specified, start must be a positive whole number and length must be a non-negative whole number.

Example 5.49. String class - caselessPos method

"Saturday"~caselessPos("DAY")       ->    6
"abc def ghi"~caselessPos("x")      ->    0
"abc def ghi"~caselessPos(" ")      ->    4
"abc def ghi"~caselessPos(" ",5)    ->    8
"abc def ghi"~caselessPos(" ",5,3)  ->    0

5.1.3.29. caselessWordPos


>>-caselessWordPos(phrase-+--------+-)---------------------------------><
                          +-,start-+

Returns the word number of the first word of phrase found in the receiving string, or 0 if phrase contains no words or if phrase is not found. Word matches are made independent of case. Several whitespace characters between words in either phrase or the receiving string are treated as a single blank for the comparison, but, otherwise, the words must match exactly.

By default the search starts at the first word in the receiving string. You can override this by specifying start (which must be positive), the word at which the search is to be started.

Example 5.50. String class - caselessWordPos method

"now is the time"~caselessWordPos("the")              ->  3
"now is the time"~caselessWordPos("The")              ->  3
"now is the time"~caselessWordPos("IS THE")           ->  2
"now is the time"~caselessWordPos("is   the")         ->  2
"now is   the time"~caselessWordPos("is   time ")     ->  0
"To be or not to be"~caselessWordPos("BE")            ->  2
"To be or not to be"~caselessWordPos("BE",3)          ->  6

5.1.3.30. ceiling


>>-ceiling-----------------------------------------------------><

Returns the largest integer not less than the receiving string. The receiving string is first rounded according to standard Rexx rules, as though the operation receiving_string+0 had been carried out. The ceiling is then calculated and returned. The result is never in exponential form. If there are no nonzero digits in the result, any minus sign is removed.

Example 5.51. String class - ceiling method

2~ceiling             ->    2
'-2'~ceiling          ->    -2
12.3~ceiling          ->    13
'-12.3'~ceiling       ->    -12

Note

The number is rounded according to the current setting of NUMERIC DIGITS if necessary, before the method processes it.

5.1.3.31. center/centre


>>-+-center(-+-length-+--------+-)-----------------------------><
   +-centre(-+        +-,--pad-+

Returns a string of length length with the receiving string centered in it. The pad characters are added as necessary to make up length. The length must be a positive whole number or zero. The default pad character is blank. If the receiving string is longer than length, it is truncated at both ends to fit. If an odd number of characters are truncated or added, the right-hand end loses or gains one more character than the left-hand end.

Note

To avoid errors because of the difference between British and American spellings, this method can be called either center or centre.

Example 5.52. String class - center method


abc~center(7)               ->    "  ABC  "
abc~CENTER(8,"-")           ->    "--ABC---"
"The blue sky"~centre(8)    ->    "e blue s"
"The blue sky"~centre(7)    ->    "e blue "

5.1.3.32. changeStr


>>-changeStr(needle,newneedle--+--------+--)---------------------------------><
                               +-,count-+

Returns a copy of the receiver object in which newneedle replaces occurrences of needle.

If count is not specified, all occurrences of needle are replaced. If count is specified, it must be a positive, whole number that gives the maximum number of occurrences to be replaced.

Here are some examples:

Example 5.53. String class - changeStr method


101100~changeStr("1","")     ->    "000"
101100~changeStr("1","X")    ->    "X0XX00"
101100~changeStr("1","X",1)  ->    "X01100"

5.1.3.33. compare


>>-compare(string-+------+-)-----------------------------------><
                  +-,pad-+

Returns 0 if the argument string is identical to the receiving string. Otherwise, returns the position of the first character that does not match. The shorter string is padded on the right with pad if necessary. The default pad character is a blank.

Example 5.54. String class - compare method


"abc"~compare("abc")         ->    0
"abc"~compare("ak")          ->    2
"ab "~compare("ab")          ->    0
"ab "~compare("ab"," ")      ->    0
"ab "~compare("ab","x")      ->    3
"ab-- "~compare("ab","-")    ->    5

5.1.3.34. compareTo


>>-compareTo(string-+-----------------------+-)----------------------><
                    +-,--+---+--+---------+-+
                         +-n-+  +-,length-+

Performs a sort comparison of the target string to the string argument. If the two strings are equal, 0 is returned. If the target string is larger, 1 is returned. -1 if the string argument is the larger string. The comparison is performed starting at character n for length characters in both strings. n must be a positive whole number. If n is omitted, the comparison starts at the first character. length must be a non-negative whole number. If omitted, the comparison will take place to the end of the target string.

Example 5.55. String class - compareTo method



"abc"~compareTo("abc")         ->    0
"b"~compareTo("a")             ->    1
"a"~compareTo("b")             ->   -1
"abc"~compareTo("aBc")         ->    1
"aBc"~compareTo("abc")         ->   -1
"000abc000"~compareTo(111abc111", 4, 3)  -> 0

5.1.3.35. copies


>>-copies(n)---------------------------------------------------><

Returns n concatenated copies of the receiving string. The n must be a positive whole number or zero.

Example 5.56. String class - copies method


"abc"~copies(3)    ->    "abcabcabc"
"abc"~copies(0)    ->    ""

5.1.3.36. countStr


>>-countStr(needle)--------------------------------------------><

Returns a count of the occurrences of needle in the receiving string that do not overlap.

Here are some examples:

Example 5.57. String class - countStr method


"101101"~countStr("1")        ->    4
"J0KKK0"~CountStr("KK")       ->    1

5.1.3.37. d2c


>>-d2c-+-----+-------------------------------------------------><
       +-(n)-+

Returns a string, in character format, that is the ASCII representation of the receiving string, a decimal number. If you specify n, it is the length of the final result in characters; leading blanks are added to the returned string. The n must be a positive whole number or zero.

The receiving string must not have more digits than the current setting of NUMERIC DIGITS.

If you omit n, the receiving string must be a positive whole number or zero, and the result length is as needed. Therefore, the returned result has no leading "00"x characters.

Example 5.58. String class - d2c method

"65"~d2c       ->   "A"      /* "41"x is an ASCII "A"    */
"65"~d2c(1)    ->   "A"
"65"~d2c(2)    ->   " A"
"65"~d2c(5)    ->   "    A"
"109"~d2c      ->   "m"      /* "6D"x  is an ASCII "m"   */
"-109"~d2c(1)  ->   "ô"      /* "93"x  is an ASCII "ô"   */
"76"~d2c(2)    ->   " L"     /* "4C"x  is an ASCII " L"  */
"-180"~d2c(2)  ->   " L"

5.1.3.38. d2x


>>-d2x-+-----+-------------------------------------------------><
       +-(n)-+

Returns a string, in character format, that represents the receiving string, a decimal number converted to hexadecimal. The returned string uses uppercase alphabetic characters for the values A-F and does not include whitespace.

The receiving string must not have more digits than the current setting of NUMERIC DIGITS.

If you specify n, it is the length of the final result in characters. After conversion the returned string is sign-extended to the required length. If the number is too big to fit into n characters, it is truncated on the left. If you specify n, it must be a positive whole number or zero.

If you omit n, the receiving string must be a positive whole number or zero, and the returned result has no leading zeros.

Example 5.59. String class - d2x method

"9"~d2x        ->    "9"
"129"~d2x      ->    "81"
"129"~d2x(1)   ->    "1"
"129"~d2x(2)   ->    "81"
"129"~d2x(4)   ->    "0081"
"257"~d2x(2)   ->    "01"
"-127"~d2x(2)  ->    "81"
"-127"~d2x(4)  ->    "FF81"
"12"~d2x(0)    ->    ""

5.1.3.39. dataType


>>-dataType-+--------+-----------------------------------------><
            +-(type)-+

Returns NUM if you specify no argument and the receiving string is a valid Rexx number that can be added to 0 without error. It returns CHAR if the receiving string is not a valid number.

If you specify type, it returns 1 if the receiving string matches the type. Otherwise, it returns 0. If the receiving string is null, the method returns 0 (except when the type is X or B, for which dataType returns 1 for a null string). The following are valid types. You need to specify only the capitalized letter, or the number of the last type listed. The language processor ignores all characters surrounding it.

Alphanumeric: returns 1 if the receiving string contains only characters from the ranges a-z, A-Z, and 0-9.
Binary: returns 1 if the receiving string contains only the characters 0 or 1, or whitespace. Whitespace characters can appear only between groups of 4 binary characters. It also returns 1 if string is a null string, which is a valid binary string.
Lowercase: returns 1 if the receiving string contains only characters from the range a-z.
Mixed case: returns 1 if the receiving string contains only characters from the ranges a-z and A-Z.
Number: returns 1 if receiving_string~dataType returns NUM.
lOgical: returns 1 if the receiving string is exactly "0" or "1". Otherwise it returns 0.
Symbol: returns 1 if the receiving string is a valid symbol, that is, if SYMBOL(string) does not return BAD. (See Section 1.10.4.4, “Symbols”.) Note that both uppercase and lowercase alphabetic characters are permitted.
Uppercase: returns 1 if the receiving string contains only characters from the range A-Z.
Variable: returns 1 if the receiving string could appear on the left-hand side of an assignment without causing a SYNTAX condition.
Whole number: returns 1 if the receiving string is a whole number under the current setting of NUMERIC DIGITS.
heXadecimal: returns 1 if the receiving string contains only characters from the ranges a-f, A-F, 0-9, and whitespace characters (as long as whitespace characters appear only between pairs of hexadecimal characters). Also returns 1 if the receiving string is a null string.
9 Digits: returns 1 if receiving_string~dataType("W") returns 1 when NUMERIC DIGITS is set to 9.

Example 5.60. String class - datatype method


" 12 "~dataType          ->   "NUM"
""~dataType              ->   "CHAR"
"123*"~dataType          ->   "CHAR"
"12.3"~dataType("N")     ->    1
"12.3"~dataType("W")     ->    0
"Fred"~dataType("M")     ->    1
""~dataType("M")         ->    0
"Fred"~dataType("L")     ->    0
"?20K"~dataType("s")     ->    1
"BCd3"~dataType("X")     ->    1
"BC d3"~dataType("X")    ->    1
"1"~dataType("O")        ->    1
"11"~dataType("O")        ->   0

Note

The dataType method tests the meaning or type of characters in a string, independent of the encoding of those characters (for example, ASCII or EBCDIC).

5.1.3.40. decodeBase64


>>-decodeBase64------------------------------------------------><

Returns a new string containing the decoded version of the base64 encoded receiving string. If the receiving string is not in base64 format then the returned result is undefined.

Example 5.61. String class - decodeBase64 method


"YWJjZGVm"~decodeBase64       ->    "abcdef"

5.1.3.41. delStr


>>-delStr(n--+---------+--)------------------------------------><
             +-,length-+

Returns a copy of the receiving string after deleting the substring that begins at the nth character and is of length characters. If you omit length, or if length is greater than the number of characters from n to the end of string, the method deletes the rest of string (including the nth character). The length must be a positive whole number or zero. The n must be a positive whole number. If n is greater than the length of the receiving string, the method returns the receiving string unchanged.

Example 5.62. String class - delStr method


"abcd"~delStr(3)       ->    "ab"
"abcde"~delStr(3,2)    ->    "abe"
"abcde"~delStr(6)      ->    "abcde"

5.1.3.42. delWord


>>-delWord(n--+---------+--)-----------------------------------><
              +-,length-+

Returns a copy of the receiving string after deleting the substring that starts at the nth word and is of length blank-delimited words. If you omit length, or if length is greater than the number of words from n to the end of the receiving string, the method deletes the remaining words in the receiving string (including the nth word). The length must be a positive whole number or zero. The n must be a positive whole number. If n is greater than the number of words in the receiving string, the method returns the receiving string unchanged. The string deleted includes any whitespace characters following the final word involved but none of the whitespace characters preceding the first word involved.

Example 5.63. String class - delWord method


"Now is the  time"~delWord(2,2)  ->  "Now time"
"Now is the time "~delWord(3)    ->  "Now is "
"Now is the  time"~delWord(5)    ->  "Now is the  time"
"Now is   the time"~delWord(3,1) ->  "Now is   time"

5.1.3.43. encodeBase64


>>-encodeBase64------------------------------------------------><

Returns a new string that is the base64 encoded version of the receiving string.

Example 5.64. String class - encodeBase64 method


"abcdef"~encodeBase64       ->    "YWJjZGVm"

5.1.3.44. equals


>>-equals(other)-------------------------------------------------------><

Returns .true ("1") if the target string is strictly equal to the other string. Returns .false ("0") if the two strings are not strictly equal. This is the same comparison performed by the "==" comparison method.

Example 5.65. String class - equals method

"3"~equals("3")          ->    1
"33"~equals("3")         ->    0
"4"~equals("3")          ->    0

5.1.3.45. floor


>>-floor-------------------------------------------------------><

Returns the largest integer not greater than the receiving string. The receiving string is first rounded according to standard Rexx rules, as though the operation receiving_string+0 had been carried out. The floor is then calculated and returned. The result is never in exponential form. If there are no nonzero digits in the result, any minus sign is removed.

Example 5.66. String class - floor method

2~floor               ->    2
'-2'~floor            ->    -2
12.3~floor            ->    12
'-12.3'~floor         ->    -13

Note

The number is rounded according to the current setting of NUMERIC DIGITS if necessary, before the method processes it.

5.1.3.46. format


>>-format-+---------------------------------------------------------+-><
          +-(-before-+------------------------------------------+-)-+
                     +-,--+-------+--+------------------------+-+
                          +-after-+  +-,--+------+--+-------+-+
                                          +-expp-+  +-,expt-+

Returns a copy of the receiving string, a number, rounded and formatted.

The number is first rounded according to standard Rexx rules, as though the operation receiving_string+0 had been carried out. If you specify no arguments the result of the method is the same as the result of this operation. If you specify any options, the number is formatted as described in the following.

The before and after options describe how many characters are to be used for the integer and decimal parts of the result. If you omit either or both of them, the number of characters for that part is as needed.

If before is not large enough to contain the integer part of the number (plus the sign for a negative number), an error results. If before is larger than needed for that part, the number is padded on the left with blanks. If after is not the same size as the decimal part of the number, the number is rounded (or extended with zeros) to fit. Specifying 0 causes the number to be rounded to an integer.

Example 5.67. String class - format method

"3"~format(4)            ->    "   3"
"1.73"~format(4,0)       ->    "   2"
"1.73"~format(4,3)       ->    "   1.730"
"-.76"~format(4,1)       ->    "  -0.8"
"3.03"~format(4)         ->    "   3.03"
" - 12.73"~format(,4)    ->    "-12.7300"
" - 12.73"~format        ->    "-12.73"
"0.000"~format           ->    "0"

expp and expt control the exponent part of the result, which, by default, is formatted according to the current NUMERIC settings of DIGITS and FORM. expp sets the number of places for the exponent part; the default is to use as many as needed (which can be zero). expt specifies when the exponential expression is used. The default is the current setting of NUMERIC DIGITS.

If expp is 0, the number is not an exponential expression. If expp is not large enough to contain the exponent, an error results.

If the number of places needed for the integer or decimal part exceeds expt or twice expt, respectively, exponential notation is used. If expt is 0, exponential notation is always used unless the exponent would be 0. (If expp is 0, this overrides a 0 value of expt.) If the exponent would be 0 when a nonzero expp is specified, then expp+2 blanks are supplied for the exponent part of the result. If the exponent would be 0 and expp is not specified, the number is not an exponential expression.

Example 5.68. String class - format method

"12345.73"~format(, ,2,2)   ->    "1.234573E+04"
"12345.73"~format(,3, ,0)   ->    "1.235E+4"
"1.234573"~format(,3, ,0)   ->    "1.235"
"12345.73"~format(, ,3,6)   ->    "12345.73"
"1234567e5"~format(,3,0)    ->    "123456700000.000"

5.1.3.47. hashCode


>>-hashCode---------------------------------------------------><

Returns a string value that is used as a hash value for MapCollection such as Table, Relation, Set, Bag, and Directory. The String hash code method will return the same hash value for all pairs of string instances for which the == operator is true. See Section 5.1.1.7, “hashCode” for details.

5.1.3.48. insert


>>-insert(new-+---------------------------------------+-)------><
              +-,--+---+--+-------------------------+-+
                   +-n-+  +-,--+--------+--+------+-+
                               +-length-+  +-,pad-+

Returns a copy of the receiver string with the string new, padded or truncated to length length, inserted after the nth character. The default value for n is 0, which means insertion at the beginning of the string. If specified, n and length must be positive whole numbers or zero. If n is greater than the length of the receiving string, the string new is padded at the beginning. The default value for length is the length of new. If length is less than the length of the string new, then insert truncates new to length length. The default pad character is a blank.

Example 5.69. String class - insert method

"abc"~insert("123")            ->    "123abc"
"abcdef"~insert(" ",3)         ->    "abc def"
"abc"~insert("123",5,6)        ->    "abc  123   "
"abc"~insert("123",5,6,"+")    ->    "abc++123+++"
"abc"~insert("123", ,5,"-")    ->    "123--abc"

5.1.3.49. lastPos


>>-lastPos(needle-+---------------------------+-)---><
                  +-,--+-------+--+---------+-+
                       +-start-+  +-,length-+

Example 5.70. String class - lastPos method

"abc def ghi"~lastPos(" ")      ->    8
"abcdefghi"~lastPos(" ")        ->    0
"efgxyz"~lastPos("xy")          ->    4
"abc def ghi"~lastPos(" ",7)    ->    4
"abc def ghi"~lastPos(" ",7,3)  ->    0

5.1.3.50. left


>>-left(length-+------+-)--------------------------------------><
               +-,pad-+

Returns a string of length length, containing the leftmost length characters of the receiving string. The string returned is padded with pad characters (or truncated) on the right as needed. The default pad character is a blank. The length must be a positive whole number or zero. The left method is exactly equivalent to:


>>-SUBSTR(string,1,length-+------+-)---------------------------><
                          +-,pad-+

Example 5.71. String class - left method

"abc d"~left(8)        ->    "abc d   "
"abc d"~left(8,".")    ->    "abc d..."
"abc  def"~left(7)     ->    "abc  de"

5.1.3.51. length


>>-length------------------------------------------------------><

Returns the length of the receiving string.

Example 5.72. String class - length method

"abcdefgh"~length     ->    8
"abc defg"~length     ->    8
""~length             ->    0

5.1.3.52. lower


>>-lower(+---+--+---------+---)----------------------><
         +-n-+  +-,length-+

Returns a new string with the characters of the target string beginning with character n for length characters converted to lowercase. If n is specified, it must be a positive whole number. If n is not specified, the case conversion will start with the first character. If length is specified, it must be a non-negative whole number. If length is not specified, the default is to convert the remainder of the string.

Example 5.73. String class - lower method

"Albert Einstein"~lower      ->    "albert einstein"
"ABCDEF"~lower(4)            ->    "ABCdef"
"ABCDEF"~lower(3,2)          ->    "ABcdEF"

5.1.3.53. makeArray


>>-makeArray(-+-----------+-)----><
              +-Separator-+

This method returns an array of strings containing the single lines that were separated using the separator string. The separator may be any string, including the null string. If the null string is used, an array containing each character of the string is returned. If the target string starts with the separator, the first array item will be a null string. If the string ends with a separator, no extra null string item will be added. The default separator is the newline character.

Example 5.74. String class - makeArray method


string = "hello".endofline"world".endofline"this is an array."
array = string~makeArray
say "the second line is:" array[2]  /*  world  */

string = "hello*world*this is an array."
array = string~makeArray("*")
say "the third line is:" array[3]  /*  this is an array.  */

string = "hello*world*this is an array.*"
array = string~makeArray("*")     /* contains 3 items */

5.1.3.54. makeString


>>-makeString--------------------------------------------------><

Returns a string with the same string value as the receiver object. If the receiver is an instance of a subclass of the String class, this method returns an equivalent string object. If the receiver is a string object (not an instance of a subclass of the String class), this method returns the receiver object. See Section 4.2.11, “Required String Values”.

5.1.3.55. match


>>-match(start,other-+----------------------------+-)-------------------><
                     +-,--+---+--+---------+------+
                          +-n-+  +-,length-+

Returns .true ("1") if the characters of the other match the characters of the target string beginning at position start. Return .false ("0") if the characters are not a match. start must be a positive whole number less than or equal to the length of the target string.

If n is specified, the match will be performed starting with character n of other. The default value for n is "1". n must be a positive whole number less than or equal to the length of other.

The match method is useful for efficient string parsing as it does not require new string objects be extracted from the target string.

Example 5.75. String class - match method

"Saturday"~match(6, "day")           ->    1
"Saturday"~match(6, "DAY")           ->    0
"Saturday"~match(6, "Sunday", 4, 3)  ->    1
"Saturday"~match(6, "daytime", 1, 3) ->    1

5.1.3.56. matchChar


>>-matchChar(n,chars)-------------------------><

Returns .true ("1") if the character at position n matches any character of the string chars. Returns .false ("0") if the character does not match any of the characters in the reference set. The argument n must be a positive whole number less than or equal to the length of the target string.

Example 5.76. String class - matchChar method

"a+b"~matchChar(2, "+-*/")           ->    1
"a+b"~matchChar(1, "+-*/")           ->    0
"Friday"~matchChar(3, "aeiou")       ->    1
"FRIDAY"~matchChar(3, "aeiou")       ->    0

5.1.3.57. max


>>-max-+------------------+------------------------------------><
       |    +-,------+    |
       |    V        |    |
       +-(----number-+--)-+

Returns the largest number from among the receiver and any arguments. The number that max returns is formatted according to the current NUMERIC settings. You can specify any number of numbers.

Example 5.77. String class - max method

12~max(6,7,9)                                                ->    12
17.3~max(19,17.03)                                           ->    19
"-7"~max("-3","-4.3")                                        ->    -3
1~max(2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21)   ->    21

5.1.3.58. min


>>-min-+------------------+------------------------------------><
       |    +-,------+    |
       |    V        |    |
       +-(----number-+--)-+

Returns the smallest number from among the receiver and any arguments. The number that min returns is formatted according to the current NUMERIC settings. You can specify any number of numbers.

Example 5.78. String class - min method

12~min(6,7,9)                                                ->     6
17.3~min(19,17.03)                                           ->    17.03
"-7"~MIN("-3","-4.3")                                        ->    -7
21~min(20,19,18,17,16,15,14,13,12,11,10,9,8,7,6,5,4,3,2,1)   ->     1

5.1.3.59. overlay


>>-overlay(new-+---------------------------------------+-)-----><
               +-,--+---+--+-------------------------+-+
                    +-n-+  +-,--+--------+--+------+-+
                                +-length-+  +-,pad-+

Returns a copy of the receiving string, which, starting at the nth character, is overlaid with the string new, padded or truncated to length length. The overlay can extend beyond the end of the receiving string. If you specify length, it must be a positive whole number or zero. The default value for length is the length of new. If n is greater than the length of the receiving string, padding is added before the new string. The default pad character is a blank, and the default value for n is 1. If you specify n, it must be a positive whole number.

Example 5.79. String class - overlay method

"abcdef"~overlay(" ",3)         ->    "ab def"
"abcdef"~overlay(".",3,2)       ->    "ab. ef"
"abcd"~overlay("qq")            ->    "qqcd"
"abcd"~overlay("qq",4)          ->    "abcqq"
"abc"~overlay("123",5,6,"+")    ->    "abc+123+++"

5.1.3.60. pos


>>-pos(needle-+---------------------------+-)---><
              +-,--+-------+--+---------+-+
                   +-start-+  +-,length-+

Returns the position in the receiving string of another string, needle. (See also Section 5.1.3.49, “lastPos”.) It returns 0 if needle is the null string or is not found or if start is greater than the length of the receiving string. By default, the search starts at the first character of the receiving string (that is, the value of start is 1), and continues to the end of the string. You can override this by specifying start , the point at which the search starts, and length, the bounding limit for the search. If specified, start must be a positive whole number and length must be a non-negative whole number.

Example 5.80. String class - pos method

"Saturday"~pos("day")       ->    6
"abc def ghi"~pos("x")      ->    0
"abc def ghi"~pos(" ")      ->    4
"abc def ghi"~pos(" ",5)    ->    8
"abc def ghi"~pos(" ",5,3)  ->    0

5.1.3.61. replaceAt


>>-replaceAt(new-,-n-,-+----------+-+-------+-)-----><
                       +-,-length-+ +-,-pad-+

Returns a copy of the receiving string, with the characters from the nth character for length characters replaced with new. The replacement position and length can extend beyond the end of the receiving string. The starting position, n, is required and must be a positive whole number. The length argument is optional and must be a positive whole number or zero. If omitted, length defaults to the length of new.

If n is greater than the length of the receiving string, padding is added before the new string. The default pad character is a blank.

Example 5.81. String class - replaceAt method

"abcdef"~replaceAt(" ",3, 1)      ->    "ab def"
"abcdef"~replaceAt(" ",3, 3)      ->    "ab f"
"abc"~replaceAt("123",5,6,"+")    ->    "abc+123"

5.1.3.62. reverse


>>-reverse-----------------------------------------------------><

Returns a copy of the receiving string reversed.

Example 5.82. String class - reverse method

"ABc."~reverse    ->    ".cBA"
"XYZ "~reverse    ->    " ZYX"

5.1.3.63. right


>>-right(length-+------+-)-------------------------------------><
                +-,pad-+

Returns a string of length length containing the rightmost length characters of the receiving string. The string returned is padded with pad characters, or truncated, on the left as needed. The default pad character is a blank. The length must be a positive whole number or zero.

Example 5.83. String class - right method

"abc  d"~right(8)     ->    "  abc  d"
"abc def"~right(5)    ->    "c def"
"12"~right(5,"0")     ->    "00012"

5.1.3.64. round


>>-round------------------------------------------------------><

Returns the nearest to the receiving string. The receiving string is first rounded according to standard Rexx rules, as though the operation receiving_string+0 had been carried out. The rounded value is then calculated and returned. The result is never in exponential form. If there are no nonzero digits in the result, any minus sign is removed.

Example 5.84. String class - round method

2~round               ->    2
'-2'~round            ->    -2
2.4~round             ->    2
'-2.4'~round          ->    -2
2.5~round             ->    3
'-2.5'~round          ->    -3

Note

The number is rounded according to the current setting of NUMERIC DIGITS if necessary, before the method processes it.

5.1.3.65. sign


>>-sign--------------------------------------------------------><

Returns a number that indicates the sign of the receiving string, which is a number. The receiving string is first rounded according to standard Rexx rules, as though the operation receiving_string+0 had been carried out. It returns -1 if the receiving string is less than 0, 0 if it is 0, and 1 if it is greater than 0.

Example 5.85. String class - sign method

"12.3"~sign       ->     1
" -0.307"~sign    ->    -1
0.0~sign          ->     0

5.1.3.66. space


>>-space-+---------------+-------------------------------------><
         +-(n-+------+-)-+
              +-,pad-+

Returns a copy of receiving string, with n pad characters between each whitespace-delimited word. If you specify n, it must be a positive whole number or zero. If it is 0, all whitespace characters are removed. Leading and trailing whitespace characters are always removed. The default for n is 1, and the default pad character is a blank.

Example 5.86. String class - space method

"abc  def  "~space           ->    "abc def"
"  abc def"~space(3)         ->    "abc   def"
"abc  def  "~space(1)        ->    "abc def"
"abc  def  "~space(0)        ->    "abcdef"
"abc  def  "~space(2,"+")    ->    "abc++def"

5.1.3.67. strip


>>-strip-+----------------------+-------------------------------><
         +-(option-+--------+-)-+
                   +-,chars-+

Returns a copy of the receiving string with leading characters, trailing characters, or both, removed, based on the option you specify. The following are valid options. (You need to specify only the first capitalized letter; all characters following it are ignored.)

Both: Removes both leading and trailing characters. This is the default.
Leading: Removes leading characters.
Trailing: Removes trailing characters.

The chars specifies the set of characters to be removed, and the default is to remove all whitespace characters (spaces and horizontal tabs). If chars, is a null string, then no characters are removed. Otherwise, any occurrences of the characters in chars will be removed.

Example 5.87. String class - strip method

"  ab c  "~strip         ->    "ab c"
"  ab c  "~strip("L")    ->    "ab c  "
"  ab c  "~strip("t")    ->    "  ab c"
"12.7000"~strip(,0)      ->    "12.7"
"0012.700"~strip(,0)     ->    "12.7"
"0012.000"~strip(,".0"") ->    "12"

5.1.3.68. subchar


>>-subchar(n)----------------------------------------------><

Returns the n'th character of the receiving string. n must be a positive whole number. If n is greater that the length of the receiving string then a zero-length string is returned.

5.1.3.69. substr


>>-substr(n-+-------------------------+-)----------------------><
            +-,--+--------+--+------+-+
                 +-length-+  +-,pad-+

Returns the substring of the receiving string that begins at the nth character and is of length length, padded with pad if necessary. The n must be a positive whole number. If n is greater than receiving_string~length, only pad characters are returned.

If you omit length, the rest of the string is returned. The default pad character is a blank.

Example 5.88. String class - substr method

"abc"~substr(2)          ->    "bc"
"abc"~substr(2,4)        ->    "bc  "
"abc"~substr(2,6,".")    ->    "bc...."

Note

In some situations the positional (numeric) patterns of parsing templates are more convenient for selecting substrings, in particular if you need to extract more than one substring from a string. See also Section 5.1.3.50, “left” and Section 5.1.3.63, “right”.

5.1.3.70. subWord


>>-subWord(n-+---------+-)-------------------------------------><
             +-,length-+

Returns the substring of the receiving string that starts at the nth word and is up to length blank-delimited words. The n must be a positive whole number. If you omit length, it defaults to the number of remaining words in the receiving string. The returned string never has leading or trailing whitespace, but includes all whitespace characters between the selected words.

Example 5.89. String class - subWord method

"Now is the  time"~subWord(2,2)    ->    "is the"
"Now is the  time"~subWord(3)      ->    "the  time"
"Now is the  time"~subWord(5)      ->    ""

5.1.3.71. subWords


>>-subWords(--+---+-+---------+-)-------------------------------------><
              +-n-+ +-,length-+

Returns an array containing all words within the substring of the receiving string that starts at the nth word and is up to length blank-delimited words. The n must be a positive whole number. If you omit n, it defaults to 1. If you omit length, it defaults to the number of remaining words in the receiving string. The strings in the returned array never have leading or trailing whitespace.

Example 5.90. String class - subWords method

"Now is the  time"~subWords         ->    .array~of("Now", "is", "the", "time")
"Now is the  time"~subWords(2,2)    ->    .array~of("is", "the")
"Now is the  time"~subWords(3)      ->    .array~of("the", "time")
"Now is the  time"~subWords(5)      ->    .array~new(0)

The subWords method is useful for iterating over the individual words in a string.

Example 5.91. String class - subWords method

    do word over source~subWords    -- extract all of the words to loop over
       say word
    end

5.1.3.72. translate


>>-translate-+--------------------------------------------------------------------------+-><
             +-(--+-------------------------------------+-+-----------------------+-)---+
                  +-tableo--+-------------------------+-+ +-,--+---+--+---------+-+
                            +-,--+--------+--+------+-+        +-n-+  +-,length-+
                                 +-tablei-+  +-,pad-+

Returns a copy of the receiving string with each character translated to another character or unchanged. You can also use this method to reorder the characters in the output table. (See last example)

The output table is tableo and the input translation table is tablei. translate searches tablei for each character in the receiving string. If the character is found, the corresponding character in tableo is used in the result string. If there are duplicates in tablei, the first (leftmost) occurrence is used. If the character is not found, the original character in the receiving string is used. The result string is always of the same length as the receiving string.

The tables can be of any length. If you specify neither translation table and omit pad, the receiving string is translated to uppercase (that is, lowercase a-z to uppercase A-Z), but if you include pad the entire string is translated to pad characters. tablei defaults to XRANGE("00"x,"FF"x), and tableo defaults to the null string and is padded with pad or truncated as necessary. The default pad is a blank.

n is the position of the first character of the translated range. The default starting position is 1. length is the range of characters to be translated. If omitted, length remainder of the string from the starting position to the end is used.

Example 5.92. String class - translate method

"abcdef"~translate                         ->    "ABCDEF"
"abcdef"~translate(, , , 3, 2)             ->    "abCDef"
"abcdef"~translate("12", "ec")             ->    "ab2d1f"
"abcdef"~translate("12", "abcd", ".")      ->    "12..ef"
"APQRV"~translate(, "PR")                  ->    "A Q V"
"APQRV"~translate(XRANGE("00"X, "Q"))      ->    "APQ  "
"4123"~translate("abcd", "1234", , 2, 2)   ->    "4ab3"
"4123"~translate("abcd", "1234")           ->    "dabc"

Note

The last example shows how to use the translate method to reorder the characters in a string. In the example, the last character of any 4-character string specified as the first argument would be moved to the beginning of the string.

5.1.3.73. trunc


>>-trunc-+-----+-----------------------------------------------><
         +-(n)-+

Returns the integer part the receiving string, which is a number, and n decimal places. The default n is 0 and returns an integer with no decimal point. If you specify n, it must be a positive whole number or zero. The receiving string is first rounded according to standard Rexx rules, as though the operation receiving_string+0 had been carried out. This number is then truncated to n decimal places or trailing zeros are added if needed to reach the specified length. The result is never in exponential form. If there are no nonzero digits in the result, any minus sign is removed.

Example 5.93. String class - trunc method

12.3~trunc            ->    12
127.09782~trunc(3)    ->    127.097
127.1~trunc(3)        ->    127.100
127~trunc(2)          ->    127.00

Note

The number is rounded according to the current setting of NUMERIC DIGITS if necessary, before the method processes it.

5.1.3.74. upper


>>-upper(+---+--+---------+---)----------------------><
         +-n-+  +-,length-+

Returns a new string with the characters of the target string beginning with character n for length characters converted to uppercase. If n is specified, it must be a positive whole number. If n is not specified, the case conversion will start with the first character. If length is specified, it must be a non-negative whole number. If length is not specified, the default is to convert the remainder of the string.

Example 5.94. String class - upper method

"Albert Einstein"~upper      ->    "ALBERT EINSTEIN"
"abcdef"~upper(4)            ->    "abcDEF"
"abcdef"~upper(3,2)          ->    "abCDef"

5.1.3.75. verify


>>-verify(reference-+----------------------------------------------+-)--><
                    +-,--+--------+--+---------------------------+-+
                         +-option-+  +-,--+-------+--+---------+-+
                                          +-start-+  +-,length-+

Returns a number that, by default, indicates whether the receiving string is composed only of characters from reference. It returns 0 if all characters in the receiving string are in reference or returns the position of the first character in the receiving string not in reference.

The option can be either Nomatch (the default) or Match. (You need to specify only the first capitalized and highlighted letter; all characters following the first character are ignored)

If you specify Match, the method returns the position of the first character in the receiving string that is in reference, or returns 0 if none of the characters are found.

The default for start is 1. Thus, the search starts at the first character of the receiving string. You can override this by specifying a different start point, which must be a positive whole number.

The default for length is the length of the string from start to the end of the string. Thus, the search proceeds to the end of the receiving string. You can override this by specifying a different length, which must be a non-negative whole number.

If the receiving string is null, the method returns 0, regardless of the value of the option. Similarly, if start is greater than receiving_string~length, the method returns 0. If reference is null, the method returns 0 if you specify Match. Otherwise, the method returns the start value.

Example 5.95. String class - verify method

"123"~verify("1234567890")             ->    0
"1Z3"~verify("1234567890")             ->    2
"AB4T"~verify("1234567890")            ->    1
"AB4T"~verify("1234567890","M")        ->    3
"AB4T"~verify("1234567890","N")        ->    1
"1P3Q4"~verify("1234567890", ,3)       ->    4
"123"~verify("",N,2)                   ->    2
"ABCDE"~verify("", ,3)                 ->    3
"AB3CD5"~verify("1234567890","M",4)    ->    6
"ABCDEF"~verify("ABC","N",2,3)         ->    4
"ABCDEF"~verify("ADEF","M",2,3)        ->    4

5.1.3.76. word


>>-word(n)-----------------------------------------------------><

Returns the nth whitespace-delimited word in the receiving string or the null string if the receiving string has fewer than n words. The n must be a positive whole number. This method is exactly equivalent to receiving_string~subWord(n,1).

Example 5.96. String class - word method

"Now is the time"~word(3)    ->    "the"
"Now is the time"~word(5)    ->    ""

5.1.3.77. wordIndex


>>-wordIndex(n)------------------------------------------------><

Returns the position of the first character in the nth whitespace-delimited word in the receiving string. It returns 0 if the receiving string has fewer than n words. The n must be a positive whole number.

Example 5.97. String class - wordIndex method

"Now is the time"~wordIndex(3)    ->    8
"Now is the time"~wordIndex(6)    ->    0

5.1.3.78. wordLength


>>-wordLength(n)-----------------------------------------------><

Returns the length of the nth whitespace-delimited word in the receiving string or 0 if the receiving string has fewer than n words. The n must be a positive whole number.

Example 5.98. String class - wordLength method

"Now is the time"~wordLength(2)       ->    2
"Now comes the time"~wordLength(2)    ->    5
"Now is the time"~wordLength(6)       ->    0

5.1.3.79. wordPos


>>-wordPos(phrase-+--------+-)---------------------------------><
                  +-,start-+

Returns the word number of the first word of phrase found in the receiving string, or 0 if phrase contains no words or if phrase is not found. Several whitespace characters between words in either phrase or the receiving string are treated as a single blank for the comparison, but, otherwise, the words must match exactly.

By default the search starts at the first word in the receiving string. You can override this by specifying start (which must be positive), the word at which the search is to be started.

Example 5.99. String class - wordPos method

"now is the time"~wordPos("the")              ->  3
"now is the time"~wordPos("The")              ->  0
"now is the time"~wordPos("is the")           ->  2
"now is the time"~wordPos("is   the")         ->  2
"now is   the time"~wordPos("is   time ")     ->  0
"To be or not to be"~wordPos("be")            ->  2
"To be or not to be"~wordPos("be",3)          ->  6

5.1.3.80. words


>>-words-------------------------------------------------------><

Returns the number of whitespace-delimited words in the receiving string.

Example 5.100. String class - words method

"Now is the time"~words      ->    4
" "~words                    ->    0

5.1.3.81. x2b


>>-x2b---------------------------------------------------------><

Returns a string, in character format, that represents the receiving string, which is a string of hexadecimal characters converted to binary. The receiving string can be of any length. Each hexadecimal character is converted to a string of 4 binary digits. The receiving string can optionally include whitespace characters (at byte boundaries only, not leading or trailing) to improve readability; they are ignored.

The returned string has a length that is a multiple of four, and does not include any whitespace.

If the receiving string is null, the method returns a null string.

Example 5.101. String class - x2b method

"C3"~x2b        ->  "11000011"
"7"~x2b         ->  "0111"
"1 C1"~x2b      ->  "000111000001"

You can combine x2b with the methods d2x and c2x to convert numbers or character strings into binary form.

Example 5.102. String class - x2b method with c2x

"C3"x~c2x~x2b  ->  "11000011"
"129"~d2x~x2b  ->  "10000001"
"12"~d2x~x2b   ->  "1100"

5.1.3.82. x2c


>>-x2c---------------------------------------------------------><

Returns a string, in character format, that represents the receiving string, which is a hexadecimal string converted to character. The returned string is half as many bytes as the receiving string. The receiving string can be any length. If necessary, it is padded with a leading 0 to make an even number of hexadecimal digits.

You can optionally include whitespace in the receiving string (at byte boundaries only, not leading or trailing) to improve readability; they are ignored.

If the receiving string is null, the method returns a null string.

Example 5.103. String class - x2c method

"4865 6c6c 6f"~x2c ->  "Hello"     /*  ASCII             */
"3732 73"~x2c      ->  "72s"       /*  ASCII             */

5.1.3.83. x2d


>>-x2d-+-----+-------------------------------------------------><
       +-(n)-+

Returns the decimal representation of the receiving string, which is a string of hexadecimal characters. If the result cannot be expressed as a whole number, an error results. That is, the result must not have more digits than the current setting of NUMERIC DIGITS.

You can optionally include whitespace characters in the receiving string (at byte boundaries only, not leading or trailing) to improve readability; they are ignored.

If the receiving string is null, the method returns 0.

If you do not specify n, the receiving string is processed as an unsigned binary number.

Example 5.104. String class - x2d method

"0E"~x2d        ->    14
"81"~x2d        ->    129
"F81"~x2d       ->    3969
"FF81"~x2d      ->    65409
"46 30"X~x2d    ->    240          /*  ASCII   */
"66 30"X~x2d    ->    240          /*  ASCII   */

If you specify n, the receiving string is taken as a signed number expressed in n hexadecimal digits. If the leftmost bit is off, then the number is positive; otherwise, it is a negative number. In both cases it is converted to a whole number, which can be negative. If n is 0, the method returns 0.

If necessary, the receiving string is padded on the left with 0 characters (note, not "sign-extended"), or truncated on the left to n characters.

Example 5.105. String class - x2d method

"81"~x2d(2)      ->    -127
"81"~x2d(4)      ->    129
"F081"~x2d(4)    ->    -3967
"F081"~x2d(3)    ->    129
"F081"~x2d(2)    ->    -127
"F081"~x2d(1)    ->    1
"0031"~x2d(0)    ->    0

5.1.4. The Method Class

The Method class creates method objects from Rexx source code. It is a subclass of the Object class (Section 5.1.1, “The Object Class”).

Table 5.4. ooRexx Method Class

Object
↓
Method
new newFile loadExternalMethod
isGuarded isPrivate isProtected package setGuarded	setPrivate setProtected setSecurityManager setUnguarded source

Note

The Method class also has available class methods that its metaclass, the Class class, defines.

5.1.4.1. Inherited Methods

Methods inherited from the Object class (Section 5.1.1, “The Object Class”).

new (Class Method)	init	send
= \= == \== <> ><	instanceMethod	sendWith
\|\| '' (abuttal)' ' (blank)	instanceMethods	setMethod
(Operator Methods)	isA	start
class	isInstanceOf	startWith
copy	objectName	string
defaultName	objectName=	unsetMethod
hasMethod	request
identityHash	run

5.1.4.2. new (Class Method)


>>-new(name,source--+-------------+---)-------------------><
                    +--, context--+

Returns a new instance of method class, which is an executable representation of the code contained in the source. The name is a string. The source can be a single string or an array of strings containing individual method lines.

The context allows the created method to inherit class and routine lookup scope from another source. If specified, context can be a Method object, a Routine object, a Package object, or the string "PROGRAMSCOPE". PROGRAMSCOPE is the default, and specifies that the newly created method will inherit the class and routine search scope from the caller of new method.

5.1.4.3. newFile (Class Method)


>>-newFile(filename)-------------------------------------------><

Returns a new instance of method class, which is an executable representation of the code contained in the file filename. The filename is a string.

5.1.4.4. loadExternalMethod (Class Method)


>>-loadExternalMethod(name,descriptor)------------------------><

Resolves a native method in an external library package and returns a Method object instance that can used to call the external method. The descriptor is a string containing blank-delimited tokens that identify the location of the native method. The first token identifies the type of native function and must be "LIBRARY". The second token must identify the name of the external library. The external library is located using platform-specific mechanisms for loading libraries. For Unix-based systems, the library name is case-sensitive. The third token is optional and specifies the name of the method within the library package. If not specified, name is used. The method name is not case sensitive. If the target method cannot be resolved, .nil is returned.

Example 5.106. Method class - loadExternalMethod method

method = .Method~loadExternalMethod("homeAddress=", 'LIBRARY mylib setHomeAddress')

5.1.4.5. isGuarded


>>-isGuarded--------------------------------------------------><

Returns true ("1") if the method is a Guarded method. Returns false ("0") for Unguarded methods.

5.1.4.6. isPrivate


>>-isPrivate--------------------------------------------------><

Returns true ("1") if the method is a Private method. Returns false ("0") for Public methods. See Section 4.2.8, “Public and Private Methods” for details on private method restrictions.

5.1.4.7. isProtected


>>-isProtected--------------------------------------------------><

Returns true ("1") if the method is a Protected method. Returns false ("0") for unprotected methods.

5.1.4.8. package


>>-package-----------------------------------------------------><

Returns the Package class instance that defined the method instance. The package instance controls and defines the search order for classes and routines referenced by the method code.

5.1.4.9. setGuarded


>>-setGuarded--------------------------------------------------><

Specifies that the method is a guarded method that requires exclusive access to its scope variable pool to run. If the receiver is already guarded, a setGuarded message has no effect. Guarded is the default state for method objects.

5.1.4.10. setPrivate


>>-setPrivate--------------------------------------------------><

Specifies that a method is a private method. By default, method objects are created as public methods. See Section 4.2.8, “Public and Private Methods” for details on private method restrictions.

5.1.4.11. setProtected


>>-setProtected------------------------------------------------><

Specifies that a method is a protected method. Method objects are not protected by default. (See Chapter 13, The Security Manager for details.)

5.1.4.12. setSecurityManager


>>-setSecurityManager--+---------------------------+-----------><
                       +-(security_manager_object)-+

Replaces the existing security manager with the specified security_manager_object. If security_manager_object is omitted, any existing security manager is removed.

5.1.4.13. setUnguarded


>>-setUnguarded------------------------------------------------><

Turns off the guard attribute of the method, allowing this method to run on an object even if another method has acquired exclusive access to the scope variable pool. Methods are unguarded by default.

A guarded method can be active for an object only when no other method requiring exclusive access to the object's variable pool is active in the same object. This restriction does not apply if an object sends itself a message to run a method and it already has exclusive use of the same object variable pool. In this case, the method runs immediately regardless of its guarded state.

5.1.4.14. source


>>-source------------------------------------------------------><

Returns the method source code as a single-index array of source lines. If the source code is not available, source returns an array of zero items.

5.1.5. The Routine Class

The Routine class creates routine objects from Rexx source code. It is a subclass of the Object class (Section 5.1.1, “The Object Class”).

Table 5.5. ooRexx Routine Class

Object

↓

Routine

new
newFile
loadExternalRoutine

call
callWith
package
setSecurityManager
source

Note

The Routine class also has available class methods that its metaclass, the Class class, defines.

5.1.5.1. Inherited Methods

Methods inherited from the Object class (Section 5.1.1, “The Object Class”).

new (Class Method)	init	send
= \= == \== <> ><	instanceMethod	sendWith
\|\| '' (abuttal)' ' (blank)	instanceMethods	setMethod
(Operator Methods)	isA	start
class	isInstanceOf	startWith
copy	objectName	string
defaultName	objectName=	unsetMethod
hasMethod	request
identityHash	run

5.1.5.2. new (Class Method)


>>-new(name,source--+-------------+---)-------------------><
                    +--, context--+

Returns a new instance of the routine class, which is an executable representation of the code contained in the source. The name is a string. The source can be a single string or an array of strings containing individual method lines.

The context allows the created routine to inherit class and routine lookup scope from another source. If specified, context can be a Method object, a Routine object, or a Package object. If not specified, the newly created method will inherit the class and routine search scope from the caller of new method.

5.1.5.3. newFile (Class Method)


>>-newFile(filename)-------------------------------------------><

Returns a new instance of the routine class, which is an executable representation of the code contained in the file filename. The filename is a string.

5.1.5.4. loadExternalRoutine (Class method)


>>-loadExternalRoutine(name,descriptor)------------------------><

Resolves a native routine in an external library package and returns a Routine object instance that can used to call the external routine. The descriptor is a string containing blank-delimited tokens that identify the location of the native routine. The first token identifies the type of native routine and must be "LIBRARY". The second token must identify the name of the external library. The external library is located using platform-specific mechanisms for loading libraries. For Unix-based systems, the library name is case-sensitive. The third token is optional and specifies the name of the routine within the library package. If not specified, name is used. The routine name is not case sensitive. If the target routine cannot be resolved, .nil is returned.

Example 5.107. Routine class - loadExternalRoutine method

routine = .Routine~loadExternalRoutine("Pi", "LIBRARY rxmath RxCalcPi")

5.1.5.5. call


>>-call-+--------------------+------------------------------------><
        |    +-,--------+    |
        |    V          |    |
        +-(----argument-+--)-+

Calls the routine object using the provided arguments. The code in the routine object is called as if it was an external routine call. The return value will be any value returned by the executed routine.

5.1.5.6. callWith


>>-call(array)----------------------------------------------------><

Calls the routine object using the arguments provided in array. Each element of array will be mapped to its corresponding call argument. The code in the routine object is called as if it was an external routine call. The return value will be any value returned by the executed routine.

5.1.5.7. package


>>-package-----------------------------------------------------><

Returns the Package class instance that defined the routine instance. The package instance controls and defines the search order for classes and routines referenced by the routine code.

5.1.5.8. setSecurityManager


>>-setSecurityManager--+---------------------------+-----------><
                       +-(security_manager_object)-+

Replaces the existing security manager with the specified security_manager_object. If security_manager_object is omitted, any existing security manager is removed.

5.1.5.9. source


>>-source------------------------------------------------------><

Returns the routine source code as a single-index array of source lines. If the source code is not available, source returns an array of zero items.

5.1.6. The Package Class

The Package class contains the source code for a package of Rexx code. A package instance holds all of the routines, classes, and methods created from a source code unit and also manages external dependencies referenced by ::REQUIRES directives. The files loaded by ::REQUIRES are also contained in Package class instances. It is a subclass of the Object class (Section 5.1.1, “The Object Class”.

Table 5.6. ooRexx Package Class

Object
↓
Package
new
addClass addPackage addPublicClass addPublicRoutine addRoutine classes definedMethods digits findClass findRoutine form fuzz importedClasses importedPackages importedRoutines	loadLibrary loadPackage name publicClasses publicRoutines routines setSecurityManager source sourceLine sourceSize trace

Note

The Package class also has available class methods that its metaclass, the Class class, defines.

5.1.6.1. Inherited Methods

Methods inherited from the Object class (Section 5.1.1, “The Object Class”).

new (Class Method)	init	send
= \= == \== <> ><	instanceMethod	sendWith
\|\| '' (abuttal)' ' (blank)	instanceMethods	setMethod
(Operator Methods)	isA	start
class	isInstanceOf	startWith
copy	objectName	string
defaultName	objectName=	unsetMethod
hasMethod	request
identityHash	run

5.1.6.2. new (Class Method)


>>-new(name,source--+------------------+---)-------------------><
                    +--, methodobject--+

Returns a new instance of the package class, which is a representation of the code contained in the source. The name is a string. The source can be a single string or an array of strings containing individual method lines.

The third parameter influences the scope of the routine. If none is given, the program scope is used. If another method or routine object is specified, the scope of the provided method or routine is used.

5.1.6.3. addClass


>>-addClass(name,class)----------------------------------------><

Adds the class object class to the available classes under the name name. This is added to the package as a non-public class.

5.1.6.4. addPackage


>>-addPackage(package)----------------------------------------><

Adds the package object package to the dependent packages under the name name. The added package is processed as if it had been added using a ::REQUIRES directive in the original package source.

5.1.6.5. addPublicClass


>>-addPublicClass(name,class)----------------------------------><

Adds the class object class to the available public classes under the name name. This is added to the package as a public class.

5.1.6.6. addPublicRoutine


>>-addPublicRoutine(name,routine)----------------------------------------><

Adds the routine object routine to the available routines under the name name. This is added to the package as a public routine.

5.1.6.7. addRoutine


>>-addRoutine(name,routine)----------------------------------------><

Adds the routine object routine to the available routines under the name name. This is added to the package as a non-public routine.

5.1.6.8. classes


>>-classes----------------------------------------------><

Returns a directory containing all classes defined by this package or imported as public classes from another package.

5.1.6.9. definedMethods


>>-definedMethods----------------------------------------------><

Returns a directory containing all unattached methods defined by this package. This is the same directory available to code within the package via the .METHODS environment symbol.

5.1.6.10. digits


>>-digits------------------------------------------------------><

Returns the initial NUMERIC DIGITS (Section 2.16, “NUMERIC”) setting used for all Rexx code contained within the package. The default value is 9. The ::OPTIONS (Section 3.5, “::OPTIONS”) can override the default value.

5.1.6.11. findClass


>>-findClass(name)---------------------------------------------><

Performs the standard environment symbol searches given class name. The search is performed using the same search mechanism used for environment symbols or class names specified on ::CLASS directives. If the name is not found, .nil will be returned.

5.1.6.12. findRoutine


>>-findRoutine(name)---------------------------------------------><

Searches for a routine within the package search order. This includes ::ROUTINE directives within the package, public routines imported from other packages, or routines added using the addRoutine method. The argument name must be a string object. If the name is not found, .nil will be returned.

5.1.6.13. form


>>-form--------------------------------------------------------><

Returns the initial NUMERIC FORM (Section 2.16, “NUMERIC”) setting used for all Rexx code contained within the package. The default value is SCIENTIFIC. The ::OPTIONS directive (Section 3.5, “::OPTIONS”) can override the default value.

5.1.6.14. fuzz


>>-fuzz--------------------------------------------------------><

Returns the initial NUMERIC FUZZ (Section 2.16, “NUMERIC”) setting used for all Rexx code contained within the package. The default value is 0. The ::OPTIONS directive (Section 3.5, “::OPTIONS”) can override the default value.

5.1.6.15. importedClasses


>>-importedClasses--------------------------------------><

Returns a directory containing all public classes imported from other packages.

5.1.6.16. importedPackages


>>-importedPackagess-------------------------------------><

Returns an Array containing all packages imported by the target package.

5.1.6.17. importedRoutines


>>-importedRoutines-------------------------------------><

Returns a directory containing all public routines imported from other packages.

5.1.6.18. loadLibrary


>>-loadLibrary(name)-----------------------------------------><

Loads a native library package and adds it to the list of libraries loaded by the interpreter. The name identifies a native external library file that will be located and loaded as if it had been named on a ::REQUIRES LIBRARY directive. If the library is successfully loaded, loadLibrary will return 1 (true), otherwise it returns 0 (false).

5.1.6.19. loadPackage


>>-loadPackage(name-+---------+-)----------------------------><
                    +-,source-+

Loads a package and adds it to the list of packages loaded by the package manager. If only name is specified, name identifies a file that will be located and loaded as if it had been named on a ::REQUIRES directive. If source is given, it must be an array of strings that is the source for the loaded package. If a package name has already been loaded by the package manager, the previously loaded version will be use. The resolved package object will be added to the receiving package object's dependent packages.

5.1.6.20. name


>>-name-------------------------------------------------><

Returns the string name of the package.

5.1.6.21. publicClasses


>>-publicClasses--------------------------------------><

Returns a directory containing all public classes defined in this package.

5.1.6.22. publicRoutines


>>-publicRoutines-------------------------------------><

Returns a directory containing all public routines defined in this package.

5.1.6.23. routines


>>-routines-------------------------------------><

Returns a directory containing all routines defined in this package.

5.1.6.24. setSecurityManager


>>-setSecurityManager--+---------------------------+-----------><
                       +-(security_manager_object)-+

Replaces the existing security manager with the specified security_manager_object. If security_manager_object is omitted, any existing security manager is removed.

5.1.6.25. source


>>-source------------------------------------------------------><

Returns the package source code as a single-index array of source lines. If the source code is not available, source returns an array of zero items.

5.1.6.26. sourceLine


>>-sourceLine(n)------------------------------------------------------><

Returns the nth source line from the package source. If the source code is not available or the indicated line does not exist, a null string is returned.

5.1.6.27. sourceSize


>>-sourceSize---------------------------------------------------------><

Returns the size of the source code for the package object. If the source code is not available, 0 is returned.

5.1.6.28. trace


>>-trace-------------------------------------------------------><

Returns the initial TRACE (Section 2.29, “TRACE”) setting used for all Rexx code contained within the package. The default value is Normal. The ::OPTIONS directive (Section 3.5, “::OPTIONS”) can override the default value.

5.1.7. The Message Class

A message object provides for the deferred or asynchronous sending of a message. You can create a message object by using the new method of the Message class or the start (Section 5.1.1.22, “start”) method of the Object class.

Table 5.7. ooRexx Message Class

Object
↓
Message
new
arguments completed errorCondition hasError messageName	notify result send start target

Note

The Message class also has available class methods that its metaclass, the Class class (Section 5.1.2, “The Class Class”), defines.

5.1.7.1. Inherited Methods

Methods inherited from the Object class (Section 5.1.1, “The Object Class”).

new (Class Method)	init	send
= \= == \== <> ><	instanceMethod	sendWith
\|\| '' (abuttal)' ' (blank)	instanceMethods	setMethod
(Operator Methods)	isA	start
class	isInstanceOf	startWith
copy	objectName	string
defaultName	objectName=	unsetMethod
hasMethod	request
identityHash	run

5.1.7.2. new (Class Method)


>>-new(target,messagename-+-------------------------------+-)--><
                          |             +---------------+ |
                          |             V               | |
                          +-,Individual---+-----------+-+-+
                          |               +-,argument-+   |
                          +-,Array,argument---------------+

Initializes the message object for sending the message name messagename to object target.

If you specify the Individual or Array option, any remaining arguments are arguments for the message. (You need to specify only the first letter; all characters following the first are ignored.)

Individual: If you specify this option, specifying argument is optional. Any arguments are passed as message arguments to target in the order you specify them.
Array: If you specify this option, you must specify an argument, which is an array object. (See Section 5.3.6, “The Array Class”.) The member items of the array are passed to target as arguments. The first argument is at index 1, the second argument at index 2, and so on. If you omitted any indexes when creating the array, the corresponding message arguments are also omitted.

If you specify neither Individual nor Array, the message sent has no arguments.

Note

This method does not send the message messagename to object target. The SEND or START method (described later) sends the message.

5.1.7.3. arguments


>>-arguments----------------------------------------------><

Returns an array of argument objects used to invoke the message.

5.1.7.4. completed


>>-completed---------------------------------------------------><

Returns 1 if the message object has completed executing its message, or 0. You can use this method to test for completion as an alternative to calling result and waiting for the message to complete.

5.1.7.5. errorCondition


>>-errorCondition----------------------------------------------><

Returns an error condition object from any execution error with the message object's message invocation. If the message completed normally, or is still executing, errorCondition returns the Nil object.

5.1.7.6. hasError


>>-hasError----------------------------------------------------><

Returns 1 if the message object's message was terminated with an error condition. Returns 0 if the message has not completed or completed without error.

5.1.7.7. messageName


>>-messageName----------------------------------------------><

Returns the string message name used to invoke a method.

5.1.7.8. notify


>>-notify(message)---------------------------------------------><

Requests notification about the completion of processing of the message send or start. The message object message is sent as the notification. You can use notify to request any number of notifications. After the notification message, you can use the result method to obtain any result from the messages send or start.

Example 5.108. Message class - notify method

/* Event-driven greetings */

.prompter~new~prompt(.nil)

::class prompter

::method prompt
  expose name
  use arg msg

  if msg \= .nil then do
    name = msg~result
    if name = "quit" then return
    say "Hello," name
  end

  say 'Enter your name ("quit" to quit):'

  /* Send the public default object .INPUT a LINEIN message asynchronously */
  msg=.message~new(.input,"LINEIN")~~start

  /* Sends self~prompt(msg) when data available   */
  msg~notify(.message~new(self,"PROMPT","I",msg))

  /* Don't leave until user has entered "quit"    */
  guard on when name="quit"

5.1.7.9. result


>>-result------------------------------------------------------><

Returns the result of the message send or start. If message processing is not yet complete, this method waits until it completes. If the message send or start raises an error condition, this method also raises an error condition.

Example 5.109. Message class - result method

/* Example using result method */
string="700"                 /* Create a new string object, string   */
bond=string~start("reverse") /* Create a message object, bond, and   */
                             /* start it.  This sends a REVERSE      */
                             /* message to string, giving bond       */
                             /* the result.                          */

/* Ask bond for the result of the message */
say "The result of message was" bond~result     /* Result is 007     */

5.1.7.10. send


>>-send--+----------+------------------------------------------><
         +-(target)-+

Returns the result (if any) of sending the message. If you specify target, this method sends the message to target. Otherwise, this method sends the message to the target you specified when the message object was created. send does not return until message processing is complete.

You can use the notify method to request notification that message processing is complete. You can use the result method to obtain any result from the message.

5.1.7.11. start


>>-start--+----------+-----------------------------------------><
          +-(target)-+

Sends the message to start processing at a specific target whereas the sender continues processing. If you specify target, this method sends the message to target. Otherwise, this method sends the message to the target that you specified when the message object was created. This method returns as soon as possible and does not wait until message processing is complete. When message processing is complete, the message object retains any result and holds it until requested via the result method. You can use the notify method to request notification when message processing completes.

Example 5.110. Message class - start method

/* Using Message class methods */
/* Note: In the following example, ::METHOD directives define class Testclass */
                                                 /* with method SHOWMSG       */

ez=.testclass~new                  /* Creates a new instance of Testclass     */
mymsg=ez~start("SHOWMSG","Hello, Ollie!",5)      /* Creates and starts        */
                                                 /* message mymsg to send     */
                                                 /* SHOWMSG to ez             */

/* Continue with main processing while SHOWMSG runs concurrently              */
do 5
  say "Hello, Stan!"
end

/* Get final result of the SHOWMSG method from the mymsg message object       */
say mymsg~result
say "Goodbye, Stan..."
exit

::class testclass public             /* Directive defines Testclass           */

::method showmsg                     /* Directive creates new method SHOWMSG  */
use arg text,reps                    /* class Testclass                       */
do reps
  say text
end
reply "Bye Bye, Ollie..."
return

The following output is possible:

Hello, Ollie!
Hello, Stan!
Hello, Ollie!
Hello, Stan!
Hello, Ollie!
Hello, Stan!
Hello, Ollie!
Hello, Stan!
Hello, Ollie!
Hello, Stan!
Bye Bye, Ollie...
Goodbye, Stan...

5.1.7.12. target


>>-target---------------------------------------------------><

Returns the object that is the target of the invoked message.