new (Class Method)

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

Returns a new instance of the receiver class.

Operator Methods

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

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

For the Object class, the arguments must match the receiver object. If they do not match the receiver object, you can define subclasses of the Object class which override == to match the arguments.

The comparison operators you can use in a message are:

Concatenation Methods

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

Concatenates the receiver object's string representation with argument. (See String Concatenation.) The concatenation_operator can be:

class

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

Returns the class object that received the message that created the object.

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:

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

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 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 objectName and string. See objectName= for an example using defaultName.

hashCode

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

Returns a string value that is used as a hash value for MapCollection such as Table, Relation, Set, Bag, and Directory. This string value is used by map collections 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 "==" need 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.

hasMethod

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

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

identityHash

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

Returns an identity number for the object. This number is guaranteed to be unique during the run of a program.

init

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

Performs any required object initialization. Subclasses of the Object class can override this method.

instanceMethod

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

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

instanceMethods

>>-instanceMethods(classname)----------------------------------><

Returns an instance of the Supplier class if the classname is the current class or a parent class. Otherwise it returns the Nil object. parent class. The returned Supplier object is a list of the methods available to the classname.

instanceOf

>>-instanceOf(classname)---------------------------------------><

Returns an .True if the receiving object is an instance of the classname. Otherwise it returns .False.

isA

>>-isA(methodname)---------------------------------------------><

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

isInstanceOf

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

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

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

objectName

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

Returns the receiver object's name that the objectName= method sets. If the receiver object does not have a name, this method returns the result of the defaultName method. See Required String Values for more information. See the objectName= method for an example using objectName.

objectName=

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

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

Example:

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                          */

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 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 Required String Values.

run

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

Runs the method object method (see 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; the language processor ignores all characters following it.)

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:

1. The run method is a private method. See the setPrivate method in setPrivate for details.

2. The RUN method is a protected method.

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. (The language processor translates this name 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:

1. The setMethod method is a private method. See the setPrivate method in setPrivate for details.

2. The setMethod method is a protected method.

start

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

Returns a message object (see 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.

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 Classes and Inheritance.

The language processor passes any arguments 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 start.

Example:

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

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 (OBJECTNAME) and the defaultName method (defaultName).

The distinction between this method, the makeString method (which obtains string values--see makeString) and the request method (see 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.

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:

1. The unsetMethod method is a private method. See the setPrivate method in setPrivate for details.

2. The unsetMethod method is a protected method.

Inherited Methods

Methods inherited from the Object class.

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.

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.

Examples:

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    */

define

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

Incorporates the method object method in the receiver class's collection of instance methods. The language processor translates the method name methodname 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:

1. The classes Rexx provides do not permit changes or additions to their method definitions.

2. The define method is a protected method.

Example:

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

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:

1. The classes Rexx provides do not permit changes or additions to their method definitions.

2. delete deletes only methods the target class defines. You cannot delete inherited methods the target's superclasses define.

3. The delete method is a protected method.

Example:

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 */

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.) 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:

/* 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")

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:

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

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:

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

2. The inherit method is a protected method.

Example:

room~inherit(.location)

isSubClassOf

>>-isSubclassOf(classname)-------------------------------------><

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

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

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). If the receiver class is an object class (see Object Classes), this is also the class used to create the receiver class. The instance methods of the default metaclass are the class methods of the receiver class. For more information about class methods, see Object Classes. See also the description of the subClass method in subClass.

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, the language processor raises an error.

Example:

/* 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 */

methods

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

Returns a supplier object 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. If you send appropriate messages to a supplier object, the supplier enumerates all the instance methods existing at the time of the supplier's creation. (See The Supplier Class for details.)

Example:

objsupp=.object~methods
do while objsupp~available
say objsupp~index           /* Says all instance methods */
objsupp~next                /* of the Object class       */
end

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:

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

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 Initialization.) new also sends an init message. If you specify args, new passes these arguments on the init message.

Example:

/* 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"

queryMixinClass

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

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

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

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

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

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.) The array indexes range from 1 to the number of subclasses.

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:

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

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. The array indexes range from 1 to the number of superclasses.

Example:

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

uninherit

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

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

Example:

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

Inherited Methods

Methods inherited from the Object class.

Methods inherited from the Comparable class.

• compareTo

new (Class Method)

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

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

Arithmetic Methods

>>-arithmetic_operator(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 Numbers). The arithmetic_operator can be:

See 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.

Examples:

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 -  */

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").

The comparison operators you can use in a message are:

Examples:

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 language processor does a numeric comparison (ignoring, for example, leading zeros--see Numeric Comparisons). Otherwise, it treats both terms as character strings, ignoring leading and trailing blanks 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:

Examples:

"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

Logical Methods

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

The logical_operator can be:

Examples:

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

Concatenation Methods

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

Concatenates the receiver object with argument. (See String Concatenation.) The concatenation_operator can be:

Examples:

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

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.

Examples:

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

Example:

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;

(See ABBREV (Abbreviation) for information about the ABBREV built-in function.)

abs

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

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

Examples:

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

(See ABS (Absolute Value) for information about the ABS built-in function.)

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 blanks (at 4-digit boundaries only, not leading or trailing). These are to improve readability; the language processor ignores them.

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

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, the language processor adds up to three 0 digits on the left before the conversion to make a total that is a multiple of four.

Examples:

"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:

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

(See B2X (Binary to Hexadecimal) for information about the B2X built-in function.)

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.

Examples:

"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   */

(See BITAND (Bit by Bit AND) for information about the BITAND built-in function.)

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.

Examples:

"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   */

(See BITOR (Bit by Bit OR) for information about the BITOR built-in function.)

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.

Examples:

"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  */

(See BITXOR (Bit by Bit Exclusive OR) for information about the BITXOR built-in function.)

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.

Examples:

"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.

Examples:

"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

(See C2D (Character to Decimal) for information about the C2D built-in function.)

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 blanks. The receiving string can be of any length. If the receiving string is null, c2x returns a null string.

Examples:

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

(See C2X (Character to Hexadecimal) for information about the C2X built-in function.)

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.

Examples:

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

Example:

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;

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:

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

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.

Examples:

"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

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 ommitted, the comparison will take place to the end of the target string.

Examples:

"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

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:

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

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. Examples:

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

caselessLastPos

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

Returns the position of the last occurrence of a string, needle, in the receiving string. (See also 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. You can override this by specifying start, the point at which the backward scan starts. The start must be a positive whole number and defaults to receiving_string~length if larger than that value or omitted. The search is performed using caseless comparisons.

Examples:

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

(See LASTPOS (Last Position) for information about the LASTPOS built-in function.)

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 efficient string parsing as it does not require new string objects be extracted from the target string.

Examples:

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

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.

Examples:

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

caselessPos

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

Returns the position in the receiving string of another string, needle. (See also 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). You can override this by specifying start (which must be a positive whole number), the point at which the search starts.

Examples:

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

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 blanks 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.

Examples:

"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

center/centre

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

Returns a string of length length with the receiving string centered in it. The language processor adds pad characters 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.

Examples:

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

(See CENTER (or CENTRE) for information about the CENTER built-in function.)

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:

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

(See CHANGESTR for information about the CHANGESTR built-in function.)

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.

Examples:

"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

(See COMPARE for information about the COMPARE built-in function.)

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 ommitted, the comparison will take place to the end of the target string.

Examples:

"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

copies

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

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

Examples:

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

(See COPIES for information about the COPIES built-in function.)

countStr

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

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

Here are some examples:

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

(See COUNTSTR for information about the COUNTSTR built-in function.)

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.

Examples:

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

Implementation maximum: The returned string must not have more than 250 significant characters, although a longer result is possible if it has additional leading sign characters ("00"x and "FF"x).

(See D2C (Decimal to Character) for information about the D2C built-in function.)

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 blanks.

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.

Examples:

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

Implementation maximum: The returned string must not have more than 500 significant hexadecimal characters, although a longer result is possible if it has additional leading sign characters (0 and F).

(See D2X (Decimal to Hexadecimal) for information about the D2X built-in function.)

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.

Examples:

" 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

(See DATATYPE for information about the DATATYPE built-in function.)

decodeBase64

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

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

Examples:

"YWJjZGVm"~decodeBase64       ->    "abcdef"

Please note that there is no corresponding DECODEBASE64 builtin function for this method in ooRexx.

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.

Examples:

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

(See DELSTR (Delete String) for information about the DELSTR built-in function.)

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 blanks following the final word involved but none of the blanks preceding the first word involved.

Examples:

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

(See DELWORD (Delete Word) for information about the DELWORD built-in function.)

encodeBase64

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

Returns the base64 encoded version of the receiving string.

Examples:

"abcdef"~encodeBase64       ->    "YWJjZGVm"

Please note that there is no corresponding ENCODEBASE64 builtin function for this method in ooRexx.

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. Examples:

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

format

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

Returns 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.

Examples:

"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.

Examples:

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

(See FORMAT for information about the FORMAT built-in function.)

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 hashCode Method for details.

insert

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

Inserts the string new, padded or truncated to length length, into the receiving string. 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.

Examples:

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

(See INSERT for information about the INSERT built-in function.)

lastPos

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

Returns the position of the last occurrence of a string, needle, in the receiving string. (See also 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. You can override this by specifying start, the point at which the backward scan starts. The start must be a positive whole number and defaults to receiving_string~length if larger than that value or omitted.

Examples:

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

(See LASTPOS (Last Position) for information about the LASTPOS built-in function.)

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

Examples:

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

(See LEFT for information about the LEFT built-in function.)

length

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

Returns the length of the receiving string.

Examples:

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

(See LENGTH for information about the LENGTH built-in function.)

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 the default is to convert the remainder of the string.

Examples:

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

(See LOWER for information about the LOWER built-in function.)

makeArray

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

This method returns an array of strings containing the single lines that were separated using the separator character. The default separator is the newline character.

Example:

nl = "0d0a"x
string = "hello"nl"world"nl"this is an array."
array = string~makeArray
say "the second line is:" array[2]

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

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 Required String Values.

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.

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 match method is useful efficient string parsing as it does not require new string objects be extracted from the target string.

Examples:

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

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.

Examples:

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

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.

Examples:

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

(See MAX (Maximum) for information about the MAX built-in function.)

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.

Examples:

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

(See MIN (Minimum) for information about the MIN built-in function.)

overlay

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

Returns 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.

Examples:

"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+++"

(See OVERLAY for information about the OVERLAY built-in function.)

pos

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

Returns the position in the receiving string of another string, needle. (See also 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). You can override this by specifying start (which must be a positive whole number), the point at which the search starts.

Examples:

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

(See POS (Position) for information about the POS built-in function.)

reverse

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

Returns the receiving string reversed.

Examples:

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

(See REVERSE for information about the REVERSE built-in function.)

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.

Examples:

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

(See RIGHT for information about the RIGHT built-in function.)

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.

Examples:

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

(See SIGN for information about the SIGN built-in function.)

space

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

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

Examples:

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

(See SPACE for information about the SPACE built-in function.)

strip

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

Returns 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; the language processor ignores all characters following it.)

The char specifies the character to be removed, and the default is a blank. If you specify char, it must be exactly one character long.

Examples:

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

(See STRIP for information about the STRIP built-in function.)

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.

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.

Examples:

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

(See SUBSTR (Substring) for information about the SUBSTR built-in function.)

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 blanks, but includes all blanks between the selected words.

Examples:

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

(See SUBWORD for information about the SUBWORD built-in function.)

translate

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

Returns the receiving string with each character translated to another character or unchanged. You can also use this method to reorder the characters in the receiving string.

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 language processor translates the entire string 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.

Examples:

"abcdef"~translate                     ->    "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")        ->    "dabc"

(See TRANSLATE for information about the TRANSLATE built-in function.)

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.

Examples:

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

(See TRUNC (Truncate) for information about the TRUNC built-in function.)

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 the default is to convert the remainder of the string.

Examples:

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

(See UPPER for information about the UPPER built-in function.)

verify

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

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; the language processor ignores all characters following the first character, which can be in uppercase or lowercase.)

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.

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.

Examples:

"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

(See VERIFY for information about the VERIFY built-in function.)

word

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

Returns the nth blank-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).

Examples:

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

(See WORD for information about the WORD built-in function.)

wordIndex

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

Returns the position of the first character in the nth blank-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.

Examples:

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

(See WORDINDEX for information about the WORDINDEX built-in function.)

wordLength

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

Returns the length of the nth blank-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.

Examples:

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

(See WORDLENGTH for information about the WORDLENGTH built-in function.)

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 blanks 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.

Examples:

"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

(See WORDPOS (Word Position) for information about the WORDPOS built-in function.)

words

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

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

Examples:

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

(See WORDS for information about the WORDS built-in function.)

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 blanks (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 blanks.

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

Examples:

"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.

Examples:

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

(See X2B (Hexadecimal to Binary) for information about the X2B built-in function.)

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 blanks 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.

Examples:

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

(See X2C (Hexadecimal to Character) for information about the X2C built-in function.)

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 blanks 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.

Examples:

"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.

Examples:

"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

(See X2D (Hexadecimal to Decimal) for information about the X2D built-in function.)

Inherited Methods

Methods inherited from the Object class.

new (Class Method)

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

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 third parameter influences the scope of the method. If none is given, the program scope is used. If another method object is given, its scope is used.

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.

For an example of the use of this method, see the code example Server implements Security Manager.

isGuarded

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

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

isPrivate

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

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

isProtected

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

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

setGuarded

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

Reverses any previous setUnguarded messages, restoring the receiver to the default guarded status. If the receiver is already guarded, a setGuarded message has no effect.

setPrivate

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

Specifies that a method is a private method. Only a message that an object sends to itself can run a private method. If a method object does not receive a setPrivate message, the method is a public method. (Any object can send a message to run a public method. See Public and Private Methods for details.)

setProtected

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

Specifies that a method is a protected method. If a method object does not receive a setProtected message, the method is not protected. (See The Security Manager for details.)

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.

setUnguarded

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

Lets an object run a method even when another method is active on the same object. If a method object does not receive a setUnguarded message, it requires exclusive use of its object variable pool. A 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 and has exclusive use of its object variable pool, regardless of whether it received a setUnguarded message.

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.

Inherited Methods

Methods inherited from the Object class.

new (Class Method)

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

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

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 Classes and Inheritance.

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

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

arguments

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

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

completed

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

Returns 1 if the message object has completed its message, or 0. You can use this method instead of sending result and waiting for the message to complete.

errorCondition

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

Returns an error condition object from an execution error in the message object's message. If the message completed normally, or is still executing, errorCondition returns the .nil object.

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.

messageName

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

Returns the string message name used to invoke a method.

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:

/* 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"
  

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:

/* 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     */

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.

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 the sender requests it by sending a result message. You can use the notify method to request notification that message processing is complete.

Example

/* 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...

target

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

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