The Utility Classes

This section describes the Rexx utility classes.

The DateTime Class

A DateTime object represents a point in between 1 January 0001 at 00:00.000000 and 31 December 9999 at 23:59:59.999999. A DateTime object has methods to allow formatting a date or time in various formats, as well as allowing arithmetic operations between dates.

Figure 5-28. The DateTime class and methods

Note: The DateTime class also has available class methods that its metaclass, the Class class, defines.

minDate (Class Method)

>>-minDate-----------------------------------------------------><

Returns a DateTime instance representing the minimum supported Rexx date, 1 January 0001 at 00:00:00.000000.

maxDate (Class Method)

>>-maxDate-----------------------------------------------------><

Returns a DateTime instance representing the maximum supported Rexx date, 31 December 9999 at 23:59:59.999999.

today (Class Method)

>>-today-------------------------------------------------------><

Returns a DateTime instance for the current day, with a time value of 00:00:00.000000.

fromNormalDate (Class Method)

>>-fromNormalDate(-date-+----------------------------+-)-------------><
                        +-,-+-----------+--+---------+
                            +-separator-+  +-,offset-+

Creates a DateTime object from a string returned by the Normal option of the Date() built-in function. The time component will be set to the beginning of the input day (00:00:00.000000).

If specified, separator identifies the field separator character used in the string. The separator must be a single character or the null string (""). A blank (" ") is the default separator.

If specified, offset is the offset from UTC, in minutes. The offset must be valid whole number value. The default offset is the current system offset timezone offset.

fromEuropeanDate (Class Method)

>>-fromEuropeanDate(-date-+----------------------------+--)------------><
                          +-,-+-----------+--+---------+
                              +-separator-+  +-,offset-+

Creates a DateTime object from a string returned by the European option of the Date() built-in function. The time component will be set to the beginning of the input day (00:00:00.000000).

If specified, separator identifies the field separator character used in the string. The separator must be a single character or the null string (""). A slash ("/") is the default separator. The time component will be set to the beginning of the input day (00:00:00.000000).

If specified, offset is the offset from UTC, in minutes. The offset must be valid whole number value. The default offset is the current system offset timezone offset.

fromOrderedDate (Class Method)

>>-fromOrderedDate(-date-+----------------------------+--)------------><
                         +-,-+-----------+--+---------+
                             +-separator-+  +-,offset-+

Creates a DateTime object from a string returned by the Ordered option of the Date() built-in function. The time component will be set to the beginning of the input day (00:00:00.000000).

If specified, separator identifies the field separator character used in the string. The separator must be a single character or the null string (""). A slash ("/") is the default separator. The time component will be set to the beginning of the input day (00:00:00.000000).

If specified, offset is the offset from UTC, in minutes. The offset must be valid whole number value. The default offset is the current system offset timezone offset.

fromStandardDate (Class Method)

>>-fromStandardDate(-date-+----------------------------+--)------------><
                          +-,-+-----------+--+---------+
                              +-separator-+  +-,offset-+

Creates a DateTime object from a string returned by the Standard option of the Date() built-in function. The time component will be set to the beginning of the input day (00:00:00.000000).

If specified, separator identifies the field separator character used in the string. The separator must be a single character or the null string (""). A null string ("") is the default separator.

If specified, offset is the offset from UTC, in minutes. The offset must be valid whole number value. The default offset is the current system offset timezone offset.

fromUsaDate (Class Method)

>>-fromUsaDate(-date-+----------------------------+--)------------><
                     +-,-+-----------+--+---------+
                         +-separator-+  +-,offset-+

Creates a DateTime object from a string returned by the Usa option of the Date() built-in function. The time component will be set to the beginning of the input day (00:00:00.000000).

If specified, separator identifies the field separator character used in the string. The separator must be a single character or the null string (""). A slash ("/") is the default separator.

If specified, offset is the offset from UTC, in minutes. The offset must be valid whole number value. The default offset is the current system offset timezone offset.

fromNormalTime (Class Method)

>>-fromNormalTime(time--+---------+-)------------------------><
                        +-,offset-+

Creates a DateTime object from a string returned by the Normal option of the Time() built-in function. The date component will be set to 1 January 0001.

If specified, offset is the offset from UTC, in minutes. The offset must be valid whole number value. The default offset is the current system offset timezone offset.

fromCivilTime (Class Method)

>>-fromCivilTime(time--+---------+-)------------------------><
                       +-,offset-+

Creates a DateTime object from a string returned by the Civil option of the Time() built-in function. The date component will be set to 1 January 0001.

If specified, offset is the offset from UTC, in minutes. The offset must be valid whole number value. The default offset is the current system offset timezone offset.

fromLongTime (Class Method)

>>-fromLongTime(time--+---------+-)------------------------><
                      +-,offset-+

Creates a DateTime object from a string returned by the Long option of the Time() built-in function. The date component will be set to 1 January 0001.

If specified, offset is the offset from UTC, in minutes. The offset must be valid whole number value. The default offset is the current system offset timezone offset.

fromBaseDate (Class Method)

>>-fromBaseDate(date--+---------+-)-------------------------------><
                      +-,offset-+

Creates a DateTime object from a string returned by the Basedate option of the Date() built-in function. The time component will be set to the beginning of the input day (00:00:00.000000).

If specified, offset is the offset from UTC, in minutes. The offset must be valid whole number value. The default offset is the current system offset timezone offset.

fromTicks (Class Method)

>>-fromTicks(time--+---------+-)--------------------------><
                   +-,offset-+

Creates a DateTime object from a string returned by the Ticks option of the Date() or Time() built-in functions.

If specified, offset is the offset from UTC, in minutes. The offset must be valid whole number value. The default offset is the current system offset timezone offset.

fromIsoDate (Class Method)

>>-fromIsoDate(date--+---------+-)------------------------><
                     +-,offset-+

Creates a DateTime object from a string in ISO date format (yyyy-mm-ddThh:mm:ss.uuuuuu). The DateTime string method returns the ISO format as the string form of a DateTime object.

If specified, offset is the offset from UTC, in minutes. The offset must be valid whole number value. The default offset is the current system offset timezone offset.

fromUTCIsoDate (Class Method)

>>-fromUTCIsoDate(date)--------------------------------------><

Creates a DateTime object from a string in ISO timezone qualified date format (yyyy-mm-ddThh:mm:ss.uuuuuu+hhmm). The DateTime string method returns the ISO format as the string form of a DateTime object.

init

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

>>-init(fullDate--+---------+-)-------------------------------><
                  +-,offset-+

>>-init(year,month,day-+---------+--------------------------------+----><
                       +-,offset-+

>>-init(year,month,day,hours,minutes,seconds--+--------------------------------+-)-><
                                              +-,-+--------------+-+---------+-+
                                                  +-microseconds-+ +-,offset-+

Initializes a new DateTime instance. If no arguments are specified, the DateTime instance is set to the current date and time. If the single fullDate argument is used, the DateTime argument is initialized to the date and time calculated by adding fullDate microseconds to 0001-01-01T00:00:00.000000. If the year, month, day, form is used, the DateTime instance is initialized to 00:00:00.000000 on the indicated date. Otherwise, the DateTime instance is initialized to the year, month, day, hours, minutes, seconds, and microseconds components. Each of these components must be a valid whole number within the acceptable range for the given component. For example, year must be in the range 1-9999, while minutes must be in the range 0-59.

If specified, offset is the offset from UTC, in minutes. The offset must be valid whole number value. The default offset is the current system offset timezone offset.

Examples:

today = .DateTime~new    -- initializes to current date and time
                         -- initializes to 9 Sep 2007 at 00:00:00.000000
day = .DateTime~new(date('F', "20070930", "S"))
                         -- also initializes to 9 Sep 2007 at 00:00:00.000000
day = .DateTime~new(2007, 9, 30)
                         -- initializes to 9 Sep 2007 at 10:33:00.000000
day = .DateTime~new(2007, 9, 30, 10, 33, 00)

Arithmetic Methods

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

Note: For the prefix + operators, omit the parentheses and argument.

Returns the result of performing the specified arithmetic operation on the receiver DateTime object. Depending on the operation, the argument be either a TimeSpan object or a DateTime object. See the description of the individual operations for details. The arithmetic_operator can be:

+

Addition. Adds a TimeSpan to the DateTime object, returning a new DateTime instance. The receiver DateTime object is not changed. The TimeSpan may be either positive or negative.

-

Subtraction. If argument is a DateTime object, the two times are subtracted, and a TimeSpan object representing the interval between the two times is returned. If the receiver DateTime is less than the argument argument DateTime, a negative TimeSpan interval is returned. The receiver DateTime object is not changed.

If argument is a TimeSpan object, subtracts the TimeSpan from the DateTime object, returning a new DateTime instance. The receiver DateTime object is not changed. The TimeSpan may be either positive or negative.

Prefix -

A prefix - operation on a DateTime object will raise a SYNTAX error condition.

Prefix +

Returns a new instance of the DateTime object with the same time value.

Examples:

t = .dateTime~new~timeOfDay  -- returns TimeSpan for current time.
say t                        -- displays "11:27:12.437000", perhaps
d = .dateTime~new(2010, 4, 11)  -- creates new date

future = d + t               -- adds timespan to d
say future                   -- displays "2010-04-11T11:27:12.437000"
                             -- "real" start of next century
nextCentury = .dateTime~new(2101, 1, 1)
                             -- displays "34060.12:25:49.922000", perhaps
say "The next century starts in" (nextCentury - .dateTime~new)

compareTo

>>-compareTo(other)------------------------------------------------><

This method returns "-1" if the other is larger than the receiving object, "0" if the two objects are equal, and "1" if other is smaller than the receiving object.

year

>>-year------------------------------------------------><

Returns the year represented by this DateTime instance.

month

>>-month------------------------------------------------><

Returns the month represented by this DateTime instance.

day

>>-day------------------------------------------------><

Returns the day represented by this DateTime instance.

hours

>>-hours----------------------------------------------><

Returns number of whole hours since midnight.

minutes

>>-minutes--------------------------------------------><

Returns minutes portion of the timestamp time-of-day.

seconds

>>-seconds--------------------------------------------><

Returns seconds portion of the timestamp time-of-day.

microseconds

>>-microseconds-----------------------------------------><

Returns microseconds portion of the timestamp time-of-day.

dayMinutes

>>-dayMinutes-------------------------------------------><

Returns the number of minutes since midnight in the time-of-day.

daySeconds

>>-daySeconds-------------------------------------------><

Returns the number of seconds since midnight in the time-of-day.

dayMicroseconds

>>-dayMicroseconds-------------------------------------------><

Returns the number of microseconds since midnight in the time-of-day.

hashCode

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

Returns a string value that is used as a hash value for a MapCollection such as Table, Relation, Set, Bag, and Directory.

addYears

>>-addYears(years)--------------------------------------------><

Add a number of years to the DateTime object, returning a new DateTime instance. The receiver DateTime object is unchanged. The years value must be a valid whole number. Negative values result in years being subtracted from the DateTime value.

The addYears method will take leap years into account. If the addition result would fall on February 29th of a non-leap year, the day will be rolled back to the 28th.

date = .DateTime~new(2008, 2, 29)
say date              -- Displays "2008-02-29T00:00:00.000000"
say date~addYears(1)  -- Displays "2009-02-29T00:00:00.000000"

addWeeks

>>-addWeeks(weeks)------------------------------------------><

Adds weeks to the DateTime object, returning a new DateTime instance. The receiver DateTime object is unchanged. The weeks value must be a valid number, including fractional values. Negative values result in week being subtracted from the DateTime value.

addDays

>>-addDays(days)--------------------------------------------><

Adds days to the DateTime object, returning a new DateTime instance. The receiver DateTime object is unchanged. The days value must be a valid number, including fractional values. Negative values result in days being subtracted from the DateTime value.

date = .DateTime~new(2008, 2, 29)
say date              -- Displays "2008-02-29T00:00:00.000000"
say date~addDays(1.5) -- Displays "2008-03-01T12:00:00.000000"

addHours

>>-addHours(hours)------------------------------------------><

Adds hours to the DateTime object, returning a new DateTime instance. The receiver DateTime object is unchanged. The hours value must be a valid number, including fractional values. Negative values result in hours being subtracted from the DateTime value.

addMinutes

>>-addMinutes(minutes)--------------------------------------><

Adds minutes to the DateTime object, returning a new DateTime instance. The receiver DateTime object is unchanged. The minutes value must be a valid number, including fractional values. Negative values result in minutes being subtracted from the DateTime value.

addSeconds

>>-addSeconds(seconds)--------------------------------------><

Adds seconds to the DateTime object, returning a new DateTime instance. The receiver DateTime object is unchanged. The seconds value must be a valid number, including fractional values. Negative values result in seconds being subtracted from the DateTime value.

addMicroseconds

>>-addMicroseconds(microseconds)----------------------------><

Adds microseconds to the DateTime object, returning a new DateTime instance. The receiver DateTime object is unchanged. The microseconds value must be a valid whole number. Negative values result in microseconds being subtracted from the DateTime value.

isoDate

>>-isoDate--------------------------------------------------><

Returns a String formatted into ISO date format, yyyy-dd-mmThh:mm:ss.uuuuuu.

utcIsoDate

>>-utcIsoDate-----------------------------------------------><

Returns a String formatted into a fully qualified ISO date format. If the timezone offiset is 0, the format is yyyy-dd-mmThh:mm:ss.uuuuuuZ. If the offset is positive, the date is formatted as yyyy-dd-mmThh:mm:ss.uuuuuu+hhmm. If the offset is negative, the result will be in the format yyyy-dd-mmThh:mm:ss.uuuuuu-hhmm.

baseDate

>>-baseDate-------------------------------------------------><

Returns the number of complete days (that is, not including the current day) since and including the base date, 1 January 0001, in the format: dddddd (no leading zeros or whitespace characters).

The base date of 1 January 1970 is determined by extending the current Gregorian calendar backward (365 days each year, with an extra day every year that is divisible by 4 except century years that are not divisible by 400. It does not take into account any errors in the calendar system that created the Gregorian calendar originally.

yearDay

>>-yearDay--------------------------------------------------><

Returns the number of days, including the current day, that have passed in the DateTime year in the format ddd (no leading zeros or blanks).

weekDay

>>-weekDay--------------------------------------------------><

Returns the day of the week, as an integer. The values returned use the ISO convention for day numbering. Monday is "1", Tuesday is "2", running through "7" for Sunday.

europeanDate

>>-europeanDate(-+-----------+-)-------------------------------><
                 +-separator-+

Returns the date in the format dd/mm/yy. If specified, separator identifies the field separator character used in the returned date. The separator must be a single character or the null string (""). A slash ("/") is the default separator.

languageDate

>>-languageDate---------------------------------------------><

Returns the date in an implementation- and language-dependent, or local, date format. The format is dd month yyyy. The name of the month is according to the national language installed on the system. If no local date format is available, the default format is returned.

Note: This format is intended to be used as a whole; Rexx programs must not make any assumptions about the form or content of the returned string.

monthName

>>-monthName------------------------------------------------><

Returns the name of the DateTime month, in English.

dayName

>>-dayName------------------------------------------------><

Returns the name of the DateTime day, in English.

normalDate

>>-normalDate(-+-----------+-)-------------------------------><
               +-separator-+

Returns the date in the format dd mon yyyy. If specified, separator identifies the field separator character used in the returned date. The separator must be a single character or the null string (""). A blank (" ") is the default separator.

orderedDate

>>-orderedDate(-+-----------+-)-------------------------------><
                +-separator-+

Returns the date in the format yy/mm/dd. If specified, separator identifies the field separator character used in the returned date. The separator must be a single character or the null string (""). A slash ("/") is the default separator.

standardDate

>>-standardDate(-+-----------+-)-------------------------------><
                 +-separator-+

Returns the date in the format yyyymmdd. If specified, separator identifies the field separator character used in the returned date. The separator must be a single character or the null string (""). A null string ("") is the default separator.

usaDate

>>-usaDate(-+-----------+-)-------------------------------><
            +-separator-+

Returns the date in the format mm/dd/yy. If specified, separator identifies the field separator character used in the returned date. The separator must be a single character or the null string (""). A slash ("/") is the default separator.

civilTime

>>-civilTime-----------------------------------------------><

Returns the time in Civil format hh:mmxx. The hours can take the values 1 through 12, and the minutes the values 00 through 59. The minutes are followed immediately by the letters am or pm. This distinguishes times in the morning (12 midnight through 11:59 a.m.--appearing as 12:00am through 11:59am) from noon and afternoon (12 noon through 11:59 p.m.--appearing as 12:00pm through 11:59pm). The hour has no leading zero. The minute field shows the current minute (rather than the nearest minute) for consistency with other TIME results.

normalTime

>>-normalTime-----------------------------------------------><

Returns the time in the default format hh:mm:ss. The hours can have the values 00 through 23, and minutes and seconds, 00 through 59. There are always two digits. Any fractions of seconds are ignored (times are never rounded). This is the default.

longTime

>>-longTime-----------------------------------------------><

Returns time in the format hh:mm:ss.uuuuuu (where uuuuuu are microseconds).

fullDate

>>-fullDate-----------------------------------------------><

Returns the number of microseconds since 00:00:00.000000 on 1 January 0001, in the format: dddddddddddddddddd (no leading zeros or blanks).

utcDate

>>-utcDate-----------------------------------------------><

Returns the date converted to UTC time as the number of microseconds since 00:00:00.000000 on 1 January 0001, in the format: dddddddddddddddddd (no leading zeros or blanks).

toTimeZone

>>-toTimeZone(-+--------+-)------------------------------><
               +-offset-+

Returns a new DateTime object representing the time for the timezone indicated by offset. If specified, offset is the offset from UTC, in minutes. The offset must be valid whole number value. The default offset 0, which creates a DateTime object for UTC.

ticks

>>-ticks--------------------------------------------------><

returns the number of seconds since 00:00:00.000000 on 1 January 1970, in the format: dddddddddddd (no leading zeros or blanks). Times prior to 1 January 1970 are returned as a negative value.

offset

>>-offset-------------------------------------------------><

Returns the timezone for the DateTime instance as the offset in minutes from UTC. Timezones east of UTC will return a positive offset. Timezones west of UTC will return a negative offset.

date

>>-date---------------------------------------------------><

Returns a new DateTime object instance for the current date, with the time component set to 00:00:00.000000.

timeOfDay

>>-timeOfDay-----------------------------------------------><

Returns the interval since 00:00:00.000000 of the current day as a TimeSpan object.

elapsed

>>-elapsed-------------------------------------------------><

Returns the difference between current time and the receiver DateTime as a TimeSpan object. The TimeSpan will be negative if the receiver DateTime represents a time in the future.

isLeapyear

>>-isLeapyear---------------------------------------------><

Returns true ("1") if the current year is leap year. Returns false ("0") if the current year is not a leap year.

daysInMonth

>>-daysInMonth--------------------------------------------><

Returns the number of days in the current month. For example, for dates in January, 31 is returned. The daysInMonth method takes leap years into account, returning 28 days for February in non-leap years, and 29 days for leap years.

daysInYear

>>-daysInYear---------------------------------------------><

Returns the number of days in the current year. For leap years, 366 is returned. For non-leap years, this returns 365.

string

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

Returns DateTime formatted as a string. The string value is returned in ISO format.

The Alarm Class

An alarm object provides timing and notification capability by supplying a facility to send any message to any object at a given time. You can cancel an alarm before it sends its message.

Figure 5-29. The Alarm class and methods

Note: The Alarm class also has available class methods that its metaclass, the Class class, defines.

cancel

>>-cancel------------------------------------------------------><

Cancels the pending alarm request represented by the receiver. This method takes no action if the specified time has already been reached.

init

>>-init(atime,message)-----------------------------------------><

Sets up an alarm for a future time atime. At this time, the alarm object sends the message that message, a message object, specifies. (See The Message Class.) The atime can a String, DateTime object, or TimeSpan object.

If atime is a DateTime object, the DateTime specifies a time when the alarm will be triggered. The DateTime must be greater than the current time.

If atime is a TimeSpan, the Alarm will be set to the current time plus the TimeSpan. The TimeSpan must not be a negative interval.

If atime is a String, you can specify this as a date and time ('hh:mm:ss') or as a number of seconds starting at the present time. If you use the date and time format, you can specify a date in the default format ('dd Mmm yyyy') after the time with a single blank separating the time and date. Leading and trailing whitespace characters are not allowed in the atime. If you do not specify a date, the Alarm uses the first future occurrence of the specified time. You can use the cancel() method to cancel a pending alarm. See Initialization for more information.

Examples

The following code sets up an alarm at 5:10 p.m. on December 15, 2007. (Assume today's date/time is prior to December 15, 2007.)

/* Alarm Examples */

PersonalMessage=.MyMessageClass~new("Call the Bank")
msg=.message~new(PersonalMessage,"RemindMe")

time = .DateTime~fromIsoDate("2007-12-15T17:10:00.000000")

a=.alarm~new(time, msg)
exit
::class MyMessageClass public
::method init
expose inmsg
use arg inmsg
::method RemindMe
expose inmsg
say "It is now" "TIME"("C")".Please "inmsg
/* On the specified data and time, displays the following message: */
/* "It is now 5:10pm. Please Call the Bank" */

For the following example, the user uses the same code as in the preceding example to define msg, a message object to run at the specified time. The following code sets up an alarm to run the msg message object in 30 seconds from the current time:

a=.alarm~new(30,msg)

The TimeSpan Class

A TimeSpan object represents a point in between 1 January 0001 at 00:00.000000 and 31 December 9999 at 23:59:59.999999. A TimeSpan object has methods to allow formatting a date or time in various formats, as well as allowing arithmetic operations between dates.

Figure 5-30. The TimeSpan class and methods

Note: The TimeSpan class also has available class methods that its metaclass, the Class class, defines.

fromDays (Class Method)

>>-fromDays(days)--------------------------------------------><

Creates a TimeSpan object from a number of days. The days argument must be a valid Rexx number.

fromHours (Class Method)

>>-fromHours(hours)------------------------------------------><

Creates a TimeSpan object from a number of hours. The hours argument must be a valid Rexx number.

fromMinutes (Class Method)

>>-fromMinutes(minutes)--------------------------------------><

Creates a TimeSpan object from a number of minutes. The minutes argument must be a valid Rexx number.

fromSeconds (Class Method)

>>-fromSeconds(seconds)--------------------------------------><

Creates a TimeSpan object from a number of seconds. The seconds argument must be a valid Rexx number.

fromMicroseconds (Class Method)

>>-fromMicroseconds(microseconds)---------------------------------><

Creates a TimeSpan object from a number of microseconds. The microseconds argument must be a valid Rexx number.

fromNormalTime (Class Method)

>>-fromNormalTime(time)----------------------------------------------><

Creates a TimeSpan object from a string returned by the Normal option of the Time() built-in function. The TimeSpan will contain an interval equal to the time of day represented by the string.

fromCivilTime (Class Method)

>>-fromCivilTime(time)----------------------------------------><

Creates a TimeSpan object from a string returned by the Civil option of the Time() built-in function. The TimeSpan will contain an interval equal to the time of day represented by the string.

fromLongTime (Class Method)

>>-fromLongTime(time)----------------------------------------><

Creates a TimeSpan object from a string returned by the Long option of the Time() built-in function. The TimeSpan will contain an interval equal to the time of day represented by the string.

fromStringFormat (Class Method)

>>-fromStringFormat(time)------------------------------------><

Creates a TimeSpan object from a string in the format returned by the TimeSpan string method.

init

>>-init(fullDate)---------------------------------------------><

>>-init(hours, minutes, seconds)------------------------------><

>>-init(day, hours, minutes, second, microseconds)------------><

Initializes a new TimeSpan instance. If the single fullDate argument is used, the TimeSpan argument is initialized to the time span fullDate microseconds. Otherwise, the TimeSpan instance is initialized to either the hours, minutes, and seconds or the days, hours, minutes, seconds, and microseconds components. Each of these components must be a valid whole number within the acceptable range for the given component. For example, hours must be in the range 0-23, while minutes must be in the range 0-59.

Examples:

                         -- initializes to 15 hours, 37 minutes and 30 seconds
                         -- (15:37:30.000000)
span = .TimeSpan~new(time('F', "15:37:30", "N))
                         -- also initializes to 15:37:30.000000
span = .TimeSpan~new(15, 37, 30)
                         -- initializes to 6.04:33:15.000100
span = .TimeSpan~new(6, 4, 33, 15, 100)

Arithmetic Methods

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

Note: For the prefix + operators, omit the parentheses and argument.

Returns the result of performing the specified arithmetic operation on the receiver TimeSpan object. Depending on the operation, the argument be either a TimeSpan object, a DateTime object, or a number. See the description of the individual operations for details. The arithmetic_operator can be:

+

Addition. If argument is a DateTime object, the TimeSpan is added to the DateTime object, returning a new DateTime instance. Neither the receiver TimeSpan or the argument DateTime object is altered by this operation. The TimeSpan may be either positive or negative.

If argument is a TimeSpan object, the two TimeSpans are added together, and a new TimeSpan instance is returned. Neither the TimeSpan object is altered by this operation.

-

Subtraction. The argument must be a TimeSpan object. The argument TimeSpan is subtracted from the receiver TimeSpan and a new TimeSpan instance is returned. Neither the TimeSpan object is altered by this operation.

*

Multiplication. The argument must be a valid Rexx number. The TimeSpan is multiplied by the argument value, and a new TimeSpan instance is returned. The receiver TimeSpan object is not altered by this operation.

/

Division. The argument must be a valid Rexx number. The TimeSpan is divided by the argument value, and a new TimeSpan instance is returned. The receiver TimeSpan object is not altered by this operation. The / operator and % produce the same result.

%

Integer Division. The argument must be a valid Rexx number. The TimeSpan is divided by the argument value, and a new TimeSpan instance is returned. The receiver TimeSpan object is not altered by this operation. The / operator and % produce the same result.

//

Remainder Division. The argument must be a valid Rexx number. The TimeSpan is divided by the argument value and the division remainder is returned as a new TimeSpan instance. The receiver TimeSpan object is not altered by this operation.

Prefix -

The TimeSpan is negated, returning a new TimeSpan instance. The receiver TimeSpan is not altered by this operation.

Prefix +

Returns a new instance of the TimeSpan object with the same time value.

Examples:

t1 = .timespan~fromHours(1)
t2 = t1 * 2
-- displays "01:00:00.000000 01:30:00.000000 02:30:00.000000"
say t1 t2 (t1 + t2)

compareTo

>>-compareTo(other)------------------------------------------------><

This method returns "-1" if the other is larger than the receiving object, "0" if the two objects are equal, and "1" if other is smaller than the receiving object.

duration

>>-duration--------------------------------------------------------><

Returns a new TimeSpan object containing the absolute value of the receiver TimeSpan object.

days

>>-days------------------------------------------------------------><

Returns the number of whole days in the TimeSpan, as a positive number.

hours

>>-hours-----------------------------------------------------------><

Returns the hours component of the TimeSpan, as a positive number.

minutes

>>-minutes---------------------------------------------------------><

Returns the minutes component of the TimeSpan, as a positive number.

seconds

>>-seconds---------------------------------------------------------><

Returns the seconds component of the TimeSpan, as a positive number.

microseconds

>>-microseconds--------------------------------------------------><

Returns the microseconds component of the TimeSpan, as a positive number.

totalDays

>>-totalDays-------------------------------------------------------><

Returns the time span expressed as a number of days. The result includes any fractional part and retains the sign of the receiver TimeSpan.

totalHours

>>-totalHours------------------------------------------------------><

Returns the time span expressed as a number of hours. The result includes any fractional part and retains the sign of the receiver TimeSpan.

totalMinutes

>>-totalMinutes----------------------------------------------------><

Returns the time span expressed as a number of minutes. The result includes any fractional part and retains the sign of the receiver TimeSpan.

totalSeconds

>>-totalSeconds----------------------------------------------------><

Returns the time span expressed as a number of seconds. The result includes any fractional part and retains the sign of the receiver TimeSpan.

totalMicroseconds

>>-totalMicroseconds-----------------------------------------------><

Returns the time span expressed as a number of microseconds. The result retains the sign of the receiver TimeSpan.

hashCode

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

Returns a string value that is used as a hash value for MapCollection such as Table, Relation, Set, Bag, and Directory.

addWeeks

>>-addWeeks(weeks)------------------------------------------><

Adds weeks to the TimeSpan object, returning a new TimeSpan instance. The receiver TimeSpan object is unchanged. The weeks value must be a valid number, including fractional values. Negative values result in week being subtracted from the TimeSpan value.

addDays

>>-addDays(days)--------------------------------------------><

Adds days to the TimeSpan object, returning a new TimeSpan instance. The receiver TimeSpan object is unchanged. The days value must be a valid number, including fractional values. Negative values result in days being subtracted from the TimeSpan value.

addHours

>>-addHours(hours)------------------------------------------><

Adds hours to the TimeSpan object, returning a new TimeSpan instance. The receiver TimeSpan object is unchanged. The hours value must be a valid number, including fractional values. Negative values result in hours being subtracted from the TimeSpan value.

addMinutes

>>-addMinutes(minutes)--------------------------------------><

Adds minutes to the TimeSpan object, returning a new TimeSpan instance. The receiver TimeSpan object is unchanged. The minutes value must be a valid number, including fractional values. Negative values result in minutes being subtracted from the TimeSpan value.

addSeconds

>>-addSeconds(seconds)--------------------------------------><

Adds seconds to the TimeSpan object, returning a new TimeSpan instance. The receiver TimeSpan object is unchanged. The seconds value must be a valid number, including fractional values. Negative values result in seconds being subtracted from the TimeSpan value.

addMicroseconds

>>-addMicroseconds(microseconds)----------------------------><

Adds microseconds to the TimeSpan object, returning a new TimeSpan instance. The receiver TimeSpan object is unchanged. The microseconds value must be a valid whole number. Negative values result in microseconds being subtracted from the TimeSpan value.

sign

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

Returns "-1" if the TimeSpan is negative, "1" if the TimeSpan is positive, and "0" if the TimeSpan duration is zero.

string

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

Returns TimeSpan formatted as a string. The string value is in the format "-dddddddd.hh:mm:ss.uuuuuu". If the TimeSpan is positive or zero, the sign is omitted. The days field will be formatted without leading zeros or blanks. If the TimeSpan duration is less than a day, the days field and the period separator will be omitted.

The Comparable Class

This class is defined as a mixin class.

Figure 5-31. The Comparable class and methods

Note: The Comparable class also has available class methods that its metaclass, the Class class, defines.

compareTo

This method compares the receiving object to the object supplied in the comparable argument.

>>-compareTo(other)---------------------------------------><

This method returns "-1" if the other is larger than the receiving object, "0" if the two objects are equal, and "1" if other is smaller than the receiving object.

The Orderable Class

The Orderable class can be inherited by classes which wish to provide each of the comparison operator methods without needing to implement each of the individual methods. The inheriting class need only implement the Comparable compareTo() method. See This class is defined as a mixin class.

Figure 5-32. The Orderable class and methods

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.

The comparison operators you can use in a message are:

=

True if the terms are equal

\=, ><, <>

True if the terms are not equal (inverse of =)

>

Greater than

<

Less than

>=

Greater than or equal to

\<

Not less than

<=

Less than or equal to

\>

Not greater than

All strict comparison operations have one of the characters doubled that define the operator. The Orderable strict comparison operators produce the same results as the non-strict comparisons.

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

==

True if terms are strictly equal

\==

True if the terms are NOT strictly equal (inverse of ==)

>>

Strictly greater than

<<

Strictly less than

>>=

Strictly greater than or equal to

\<<

Strictly NOT less than

<<=

Strictly less than or equal to

\>>

Strictly NOT greater than

The Comparator Class

The Comparator class is the base class for implementing Comparator objects that can be used with the Array sortWith() or stableSortWith() method. The compare() method implements some form of comparison that determines the relative ordering of two objects. Many Comparator implementations are specific to particilar object types.

Figure 5-33. The Comparator class and methods

Note: The Comparator class also has available class methods that its metaclass, the Class class, defines.

This class is defined as a mixin class.

compare

>>-compare(first,second)--------------------------------><

This method returns "-1" if the second is larger than first object, "0" if the two objects are equal, and "1" second is smaller than first .

The default Comparator compare() method assumes that first is an object that implements the Comparable compareTo() method. Subclasses may override this to implement more specific comparisons.

The CaselessComparator Class

The CaselessComparator class performs caseless orderings of String objects.

Figure 5-34. The CaselessComparator class and methods

Note: The CaselessComparator class also has available class methods that its metaclass, the Class class, defines.

This class is defined as a mixin class.

compare

>>-compare(first,second)--------------------------------><

This method returns "-1" if the second is larger than first object, "0" if the two objects are equal, and "1" second is smaller than first. The two strings are compared using a caseless comparison.

The ColumnComparator Class

The CaselessColumnComparator class performs orderings based on specific substrings of String objects.

Figure 5-35. The ColumnComparator class and methods

Note: The ColumnComparator class also has available class methods that its metaclass, the Class class, defines.

This class is defined as a mixin class.

compare

>>-compare(first,second)--------------------------------><

This method returns "-1" if the second is larger than first object, "0" if the two objects are equal, and "1" second is smaller than first. Only the defined columns of the strings are compared.

init

>>-init(start, length)----------------------------------><

Initializes a comparator to sort strings starting at position start for length characters.

The CaselessColumnComparator Class

The CaselessColumnComparator class performs caseless orderings of specific substrings of String objects.

Figure 5-36. The CaselessColumnComparator class and methods

Note: The CaselessColumnComparator class also has available class methods that its metaclass, the Class class, defines.

This class is defined as a mixin class.

compare

>>-compare(first,second)--------------------------------><

This method returns "-1" if the second is larger than first object, "0" if the two objects are equal, and "1" second is smaller than first. Only the defined columns of the strings are compared, using a caseless comparison.

init

>>-init(start, length)----------------------------------><

Initializes a comparator to sort strings starting at position start for length characters.

The DescendingComparator Class

The DescendingComparator class performs sort orderings in descending order. This is the inverse of a Comparator sort order.

This class is defined as a mixin class. It must be used by inheriting from it as a mixin.

Figure 5-37. The DescendingComparator class and methods

Note: The DescendingComparator class also has available class methods that its metaclass, the Class class, defines.

This class is defined as a mixin class.

compare

>>-compare(first,second)--------------------------------><

This method returns "1" if the second is larger than first object, "0" if the two objects are equal, and "-1" second is smaller than first, resulting in a descending sort sequence. The DescendingComparator assumes the first object implements the Comparable compareTo() method.

The CaselessDescendingComparator Class

The CaselessDescendingComparator class performs caseless string sort orderings in descending order. This is the inverse of a CaselessComparator sort order.

Figure 5-38. The CaselessDescendingComparator class and methods

Note: The CaselessDescendingComparator class also has available class methods that its metaclass, the Class class, defines.

This class is defined as a mixin class.

compare

>>-compare(first,second)--------------------------------><

This method returns "1" if the second is larger than first object, "0" if the two objects are equal, and "-1" second is smaller than first. The two strings are compared using a caseless comparison.

The InvertingComparator Class

The InvertingComparator class inverts the comparison results of another Comparator object to reverse the resulting sort order.

Figure 5-39. The InvertingComparator class and methods

Note: The InvertingComparator class also has available class methods that its metaclass, the Class class, defines.

This class is defined as a mixin class.

compare

>>-compare(first,second)--------------------------------><

This method returns "1" if the second is larger than first object, "0" if the two objects are equal, and "-1" second is smaller than first, resulting in a descending sort sequence. The InvertingComparator will invert the ordering returned by the provided Comparator.

init

>>-init(comparator)----------------------------------><

Initializes an inverting comparator to sort strings using an inversion of the result from the comparator compare() method.

The Monitor Class

The Monitor class acts as a proxy for other objects. Messages sent to the Monitor object are forwarded to a different target object. The message target can be changed dynamically.

Figure 5-40. The Monitor class and methods

Note: The Monitor class also has available class methods that its metaclass, the Class class, defines.

current

>>-current-----------------------------------------------------><

Returns the current destination object.

destination

>>-destination--+---------------+------------------------------><
                +-(destination)-+

Returns a new destination object. If you specify destination, this becomes the new destination for any forwarded messages. If you omit destination, the previous destination object becomes the new destination for any forwarded messages.

init

>>-init--+---------------+-------------------------------------><
         +-(destination)-+

Initializes the newly created monitor object.

unknown

>>-unknown(messagename,messageargs)----------------------------><

Reissues or forwards to the current monitor destination all unknown messages sent to a monitor object. For additional information, see Defining an unknown Method.

Examples

.local~setentry("output",.monitor~new(.stream~new("my.new")~~command("open nobuffer")))

/* The following sets the destination */
previous_destination=.output~destination(.stream~new("my.out")~~command("open write"))
/* The following resets the destination */
.output~destination

.output~destination(.Stdout)
current_output_destination_stream_object=.output~current

The MutableBuffer Class

The MutableBuffer class is a buffer on which certain string operations such as concatenation can be performed very efficiently. Unlike String objects, MutableBuffers can be altered without requiring a new object allocation. A MutableBuffer object can provide better performance for algorithms that involve frequent concatenations to build up longer string objects because it creates fewer intermediate objects.

Figure 5-41. The MutableBuffer class and methods

Note: The MutableBuffer class also has available class methods that its metaclass, the Class class, defines.

new

>>-new(-+--------+-+---------------+-)--------------------><
        +-string-+ +-,-buffersize--+

Initialize the buffer, optionally assign a buffer content and a starting buffer size. The default size is 256; the buffer size increases to the length of string if the string does not fit into the buffer.

append

>>-append(string)------------------------------------------><

Appends string to the buffer content. The buffer size is increased if necessary.

caselessChangeStr

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

Returns the receiver MutableBuffer newneedle replacing 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.

caselessCountStr

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

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

caselessLastPos

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

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

caselessMatch

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

Returns .true ("1") if the characters of the other match the characters of the target buffer 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 buffer.

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

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

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

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

caselessPos

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

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

caselessWordPos

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

Returns the word number of the first word of phrase found in the receiving buffer, or 0 if phrase contains no words or if phrase is not found. Word matches are made independent of case. Multiple whitespace characters between words in either phrase or the receiving buffer 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.

changeStr

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

Returns the receiver MutableBuffer with newneedle replacing 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.

countStr

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

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

delete

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

Deletes length characters from the buffer beginning at the n'th character. If length is omitted, or if length is greater than the number of characters from n to the end of the buffer, the method deletes the remaining buffer contents (including the n'th character). The length must be a positive integer or zero. The n must be a positive integer. If n is greater than the length of the buffer or zero, the method does not modify the buffer content.

delstr

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

Deletes length characters from the buffer beginning at the n'th character. If length is omitted, or if length is greater than the number of characters from n to the end of the buffer, the method deletes the remaining buffer contents (including the n'th character). The length must be a positive integer or zero. The n must be a positive integer. If n is greater than the length of the buffer or zero, the method does not modify the buffer content. The delstr() method is the same as the delete() method. It is provided for polymorphism with the String class.

delWord

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

Deletes a substring from the MutableBuffer the substring that starts at the nth word and is of length whitespace-delimited words. If you omit length, or if length is greater than the number of words from n to the end of the receiving bufffer, the method deletes the remaining words in the receiving buffer (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 buffer, the method returns the receiving buffer unchanged. The portion deleted includes any whitespace characters following the final word involved but none of the whitespace characters preceding the first word involved.

getBufferSize

>>-getBufferSize-------------------------------------------><

Retrieves the current buffer size.

insert

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

Inserts the string new, padded or truncated to length length, into the mutable buffer after the n'th 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 integers or zeros. If n is greater than the length of the buffer contents, 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 string new, insert truncates new to length length. The default pad character is a blank.

lastPos

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

Returns the position of the last occurrence of a string, needle, in the receiving buffer. (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 buffer 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_buffer~length if larger than that value or omitted.

Examples:

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

length

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

Returns length of data in buffer.

lower

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

Returns the receiving buffer 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 buffer.

makeArray

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

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

match

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

Returns .true ("1") if the characters of the other match the characters of the target buffer 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 buffer.

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

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

overlay

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

Modifies the buffer content by overlaying it, starting at the n'th character, with the string new, padded or truncated to length length. The overlay can extend beyond the end of the buffer. In this case the buffer size will be increased. If you specify length, it must be a positive integer or zero. The default value for length is the length of new. If n is greater than the length of the buffer content, 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 integer.

pos

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

Returns the position in the receiving buffer 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 buffer. By default, the search starts at the first character of the receiving buffer (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:

x1 = .mutablebuffer~new("Saturday")
x1~pos("day")       ->    6
x1 = .mutablebuffer~new("abc def ghi")
x1~pos("x")         ->    0
x1~pos(" ")         ->    4
x1~pos(" ",5)       ->    8

replaceAt

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

Returns the receiving buffer with the characters from the nth character for length characters replaced with new. The replacement position and length can extend beyond the end of the receiving string. The starting position, n, must be a positive whole number, and the length must be a positive whole number or zero. 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.

setBufferSize

>>-setBufferSize(n)----------------------------------------><

Sets the buffer size. If n is less than the length of buffer content, the content is truncated. If n is 0, the entire contents is erased and the new buffer size is the value given in the init method.

string

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

Retrieves the content of the buffer as a string.

subchar

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

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

substr

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

Returns a substring from the buffer content that begins at the n'th character and is of length length, padded with pad if necessary. The n must be a positive integer. If n is greater than receiving_string~length, only pad characters are returned. If you omit length, the remaining buffer content is returned. The default pad character is a blank.

subWord

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

Returns the substring of the receiving buffer that starts at the nth word and is up to length whitespace-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 buffer. The returned string never has leading or trailing whitespace characters, but includes all whitespace characters between the selected words.

translate

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

Returns the receiving buffer with each character translated to another character or unchanged.

The output table is tableo and the input translation table is tablei. translate searches tablei for each character in the receiving buffer. If the character is found, the corresponding character in tableo is replaces the character in the buffer. If there are duplicates in tablei, the first (leftmost) occurrence is used. If the character is not found, the original character in the receiving buffer is unchanged.

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

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

upper

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

Returns the receiving buffer 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 buffer.

verify

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

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

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

If you specify Match, the method returns the position of the first character in the receiving buffer 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 buffer. You can override this by specifying a different start point, which must be a positive whole number.

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

If the receiving string is null, the method returns 0, regardless of the value of the option. Similarly, if start is greater than receiving_buffer~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:

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

word

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

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

wordIndex

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

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

wordLength

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

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

wordPos

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

Returns the word number of the first word of phrase found in the receiving buffer, or 0 if phrase contains no words or if phrase is not found. Multiple whitespace characters between words in either phrase or the receiving buffer 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 buffer. You can override this by specifying start (which must be positive), the word at which the search is to be started.

words

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

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

The RegularExpression Class

This class provides support for regular expressions. A regular expression is a pattern you can use to match strings.

Note: The RegularExpression class is not a built-in class and is NOT preloaded. It is defined in the rxregexp.cls file. This means you must use a ::requires statement to activate its functionality, as follows:

::requires "rxregexp.cls"

Figure 5-42. The RegularExpression class and methods

Note: The RegularExpression class also has available class methods that its metaclass, the Class class, defines.

Here is a description of the syntax:

|

OR operator between the left and right expression

?

Matches any single character

*

Matches the previous expression zero or more times

+

Matches the previous expression one or more times

\

"Escape" symbol: use the next character literally

()

Expression in parenthesis (use where needed)

{n}

Matches previous expression n times (n>1)

[]

Set definition: matches any single character out of the defined set.

A '^' right after the opening bracket means that none of the following characters should be matched.

A '-' (if not used with '\') defines a range between the last specified character and the one following '-'. If it is the first character in the set definition, it is used literally.

The following symbolic names (they must start and end with ':') can be used to abbreviate common sets:

:ALPHA:

Characters in the range A-Z and a-z

:LOWER:

Characters in the range a-z

:UPPER:

Characters in the range A-Z

:DIGIT:

Characters in the range 0-9

:ALNUM:

Characters in :DIGIT: and :ALPHA:

:XDIGIT:

Characters in :DIGIT:, A-F and a-f

:BLANK:

Space and tab characters

:SPACE:

Characters "09"x to "0D"x and space

:CNTRL:

Characters "00"x to "1F"x and "7F"x

:PRINT:

Characters in the range "20"x to "7E"x

:GRAPH:

Characters in :PRINT: without space

:PUNCT:

All :PRINT: characters without space and not in :ALNUM:

Examples:

::requires "rxregexp.cls"

     "(Hi|Hello) World"      Matches "Hi World" and
                             "Hello World".
     "file.???"              Matches any file with three
                             characters after "."
     "file.?{3}"             Same as above.
     "a *b"                  Matches all strings that begin with
                             "a" and end with "b" and have an
                             arbitrary number of spaces in between
                             both.
     "a +b"                  Same as above, but at least one space
                             must be present.
     "file.[bd]at"           Matches "file.bat" and "file.dat".
     "[A-Za-z]+"             Matches any string containing only
                             letters.
     "[:ALPHA:]+"            Same as above, using symbolic names.
     "[^0-9]*"               Matches any string containing no
                             numbers, including the empty string.
     "[:DIGIT::LOWER:]"      A single character, either a digit or
                             a lower case character.
     "This is (very )+nice." Matches all strings with one or more
                             occurrences of "very " between
                             "This is " and "nice.".

init

                     +-,-"MAXIMAL"--+
>>-init(-+---------+-+--------------+-)--------------------><
         +-Pattern-+ +-,-"MINIMAL"--+

Instantiates a RegularExpression object. Use the optional parameter Pattern to define a pattern that is used to match strings. See the introductory text below for a description of the syntax. If the strings match, you can decide whether you want to apply "greedy" matching (a maximum-length match) or "non-greedy" matching (a minimum-length match).

Examples:

myRE1 = .RegularExpression~new
myRE2 = .RegularExpression~new("Hello?*")

match

>>-match(-string-)-----------------------------------------><

This method tries to match string to the regular expression that was defined on the "new" invocation or on the "parse" invocation. It returns 0 on an unsuccessful match and 1 on a successful match. For an example see Parse.

parse

                  +-,-"CURRENT"--+
>>-parse(-Pattern-+--------------+-------------------------><
                  +-,-"MAXIMAL"--+
                  +-,-"MINIMAL"--+

This method creates the matcher used to match a string from the regular expression specified with Pattern. The RegularExpression object uses this regular expression until a new invocation of Parse takes place. The second (optional) parameter specifies whether to use minimal or maximal matching. The default is to use the current matching behavior.

Return values:

0

Regular expression was parsed successfully.

1

An unexpected symbol was met during parsing.

2

A missing ')' was found.

3

An illegal set was defined.

4

The regular expression ended unexpectedly.

5

An illegal number was specified.

Example 1:

a.0 = "does not match regular expression"
a.1 = "matches regular expression"
b = .array~of("This is a nice flower.",
              "This is a yellow flower.", ,
              "This is a blue flower.",
              "Hi there!")

myRE = .RegularExpression~new
e = myRE~parse("This is a ???? flower.")
if e == 0 then do
  do i over b
    j = myRE~match(i)
    say i~left(24) ">>" a.j
  end
end
else
  say "Error" e "occurred!"
exit

::requires "rxregexp.cls"

Output:

This is a nice flower.   >> Does match regular expression
This is a yellow flower. >> Does not match regular expression
This is a blue flower.   >> Does match regular expression
Hi there!                >> Does not match regular expression

Example 2:

a.0 = "an invalid number!"
a.1 = "a valid number."
b = .array~of("1","42","0","5436412","1a","f43g")
myRE = .RegularExpression~new("[1-9][0-9]*")
do i over b
  j = myRE~match(i)
  say i "is" a.j
end
say

/* Now allow "hex" numbers and a single 0 */
if myRE~parse("0|([1-9a-f][0-9a-f]*)") == 0 then do
  do i over b
    j = myRE~match(i)
    say i "is" a.j
  end
end
else
  say "invalid regular expression!"

exit

::requires "rxregexp.cls"

Example 3:

str = "<p>Paragraph 1</p><p>Paragraph 2</p>"
myRE1 = .RegularExpression~new("<p>?*</p>","MINIMAL")
myRE1~match(str)
myRE2 = .RegularExpression~new("<p>?*</p>","MAXIMAL")
myRE2~match(str)

say "myRE1 (minimal) matched" str~substr(1,myRE1~position)
say "myRE2 (maximal) matched" str~substr(1,myRE2~position)

::requires "rxregexp.cls"

Output:

myRE1 (minimal) matched <p>Paragraph 1</p>
myRE2 (maximal) matched <p>Paragraph 1</p><p>Paragraph 2</p>

pos

>>-pos-(-haystack-)----------------------------------------><

This method tries to locate a string defined by the regular expression on the "new" invocation or on the "parse" invocation in the given haystack string. It returns 0 on an unsuccessful match or the starting position on a successful match. The end position of the match can be retrieved with the position method.

Example:

str = "It is the year 2002!"
myRE = .RegularExpression~new("[1-9][0-9]*")
begin = myRE~pos(str)
if begin > 0 then do
  year = str~substr(begin, myRE~position - begin + 1)
  say "Found the number" year "in this sentence."
end

::requires "rxregexp.cls"

Output:

Found the number 2002 in this sentence.

position

>>-position------------------------------------------------><

Returns the character position at which the last parse(), pos(), or match() method ended.

Example:

myRE = .RegularExpression~new
myRE~parse("[abc")                    -- illegal set definition
say myRE~position                     -- will be 4

myRE = .RegularExpression~new("[abc]12")
myRE~match("c12")
say myRE~position                     -- will be 3

myRE~match("a13")
say myRE~position                     -- will be 2 (failure to match)

::requires "rxregexp.cls"

The RexxQueue Class

The RexxQueue class provides object-style access to Rexx external data queues.

Figure 5-43. The RexxQueue class and methods

Note: The RexxQueue class also has available class methods that its metaclass, the Class class, defines.

create (Class Method)

>>-create(name)--------------------------------------------><

Attempts to create an external Rexx named queue using name. If a name queue already exists, a new queue with a Rexx-generated name will be created. This method returns the name of the created queue, which will be either name, or a generated name if there is a conflict.

delete (Class Method)

>>-delete(name)--------------------------------------------><

Attempts to delete an external Rexx named queue named name. This method returns "0" if the queue was successfully deleted. Non-zero results are the error codes from the RexxDeleteQueue() programming interface.

exists (Class Method)

>>-exists(name)--------------------------------------------><

Tests if an external Rexx queue name currently exists, returning 1 (true) if it does and 0 (false) otherwise.

open (Class Method)

>>-open(name)--------------------------------------------><

Tests if the external Rexx named queue nameexists and creates the queue if it does not.

delete

>>-delete------------------------------------------------><

Deletes the Rexx external queue associated with this RexxQueue instance.

empty

>>-empty-------------------------------------------------><

Removes all items from the Rexx external queue associated with this RexxQueue instance.

get

>>-get------------------------------------------------><

Returns the name of the Rexx external queue associated with this instance.

init

>>-init(-+------+-)----------------------------------><
         +-name-+

Initializes a new RexxQueue instance associated with the named Rexx external queue. If name is not specified, the SESSION queue is used. If the named queue does not exist, one will be created.

lineIn

>>-lineIn--------------------------------------------------><

Reads a single line from the Rexx external queue. If the queue is empty, lineIn will wait until a line is added to the queue.

lineOut

>>-lineOut(-+------+-)----------------------------------><
            +-line-+

Adds a line to the Rexx external queue in first-in-first-out (FIFO) order. If line is not specified, a null string ("") is added.

makeArray

>>-makeArray---------------------------------------------><

Returns a single-index array with the same number of items as the receiver object. Items in the new array will have the same order as the items in the external queue. The external queue is emptied.

pull

>>-pull--------------------------------------------------><

Reads a line from the Rexx external queue. If the queue is currently empty, this method will immediately return the Nil Object without waiting for lines to be added to the queue.

push

>>-push(-+------+-)----------------------------------><
         +-line-+

Adds a line to the Rexx external queue in last-in-last-out (LIFO) order. If line is not specified, a null string ("") is added.

queue

>>-queue(-+------+-)----------------------------------><
          +-line-+

Adds a line to the Rexx external queue in first-in-first-out (FIFO) order. If line is not specified, a null string ("") is added.

queued

>>-queued---------------------------------------------><

Returns the count of lines currently in the Rexx external queue.

say

>>-say(-+------+-)----------------------------------><
        +-line-+

Adds a line to the Rexx external queue in first-in-first-out (FIFO) order. If line is not specified, a null string ("") is added.

set

>>-set(name)----------------------------------><

Switches the Rexx external queue associated with the RexxQueue instance. The new queue must have been previously created. The method return value is the name of current queue being used by the instance.

The Supplier Class

You can use a supplier object to iterate over items of a collection. Supplier objects are created from a snapshot of a collection. The iteration results are not affected by later changes to the source collection object.

Figure 5-44. The Supplier class and methods

Note: The Supplier class also has available class methods that its metaclass, the Class class, defines.

new (Class Method)

>>-new(items,indexes)-----------------------------------------><

Returns a new supplier object. The items argument must be an array of objects over which the supplier iterates. The indexes argument is an array of index values with a one-to-one correspondence to the objects contained in the items array. The created supplier iterates over the arrays, returning elements of the values array in response to items messages, and elements of the indexes array in response to index messages. The supplier iterates for the number of items contained in the values array, returning the Nil object for any nonexistent items in either array.

allIndexes

>>-allItems--------------------------------------------------------><

Returns an array of all index values from the current supplier position to the end of the supplier. Once allIndexes is called, no additional items can be retrieved from the supplier. Calls to available will return "0" (false).

allItems

>>-allItems--------------------------------------------------------><

Returns an array of all items from the current supplier position to the end of the supplier. Once allItems is called, no additional items can be retrieved from the supplier. Calls to available will return "0" (false).

available

>>-available---------------------------------------------------><

Returns 1 (true) if an item is available from the supplier (that is, if the item method would return a value). It returns 0 (false) if the collection is empty or the supplier has already enumerated the entire collection.

index

>>-index-------------------------------------------------------><

Returns the index of the current item in the collection. If no item is available, that is, if available would return false, the supplier raises an error.

init

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

Initializes the object instance.

item

>>-item--------------------------------------------------------><

Returns the current item in the collection. If no item is available, that is, if available would return false, the supplier raises an error.

next

>>-next--------------------------------------------------------><

Moves to the next item in the collection. By repeatedly sending next to the supplier (as long as available returns true), you can enumerate all items in the collection. If no item is available, that is, if available would return false, the supplier raises an error.

Examples

desserts=.array~of(apples, peaches, pumpkins, 3.14159) /* Creates array */
say "The desserts we have are:"
baker=desserts~supplier             /* Creates supplier object named BAKER */
do while baker~available            /* Array suppliers are sequenced       */
  if baker~index=4
  then say baker~item "is pi, not pie!!!"
  else say baker~item
  baker~next
end

/* Produces: */
/* The desserts we have are: */
/* APPLES                    */
/* PEACHES                   */
/* PUMPKINS                  */
/* 3.14159 is pi, not pie!!! */

supplier

>>-supplier------------------------------------------------------><

Returns the target supplier as a result. This method allows an existing supplier to be passed to methods that expect an object that implements a supplier method as an argument.

The StreamSupplier Class

A subclass of the Supplier class that will provided stream lines using supplier semantics. This allows the programmer to iterate over the remaining lines in a stream. A StreamSupplier object provides a snapshot of the stream at the point in time it is created, including the current line read position. In general, the iteration is not effected by later changes to the read and write positioning of the stream. However, forces external to the iteration may change the content of the remaining lines as the itertion progresses.

Figure 5-45. The StreamSupplier class and methods

Note: The StreamSupplier class also has available class methods that its metaclass, the Class class, defines.

available

>>-available---------------------------------------------------><

Returns 1 (true) if an item is available from the supplier (that is, if the item method would return a value). It returns 0 (false) if the collection is empty or the supplier has already enumerated the entire collection.

index

>>-index-------------------------------------------------------><

Returns the index of the current item in the collection. If no item is available, that is, if available would return false, the supplier raises an error.

init

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

Initializes the object instance.

item

>>-item--------------------------------------------------------><

Returns the current item in the collection. If no item is available, that is, if available would return false, the supplier raises an error.

next

>>-next--------------------------------------------------------><

Moves to the next item in the collection. By repeatedly sending next to the supplier (as long as available returns true), you can enumerate all items in the collection. If no item is available, that is, if available would return false, the supplier raises an error.

The RexxContext Class

The RexxContext class gives access to context information about the currently executing Rexx code. Instances of the RexxContext class can only be obtained via the .CONTEXT environment symbol. They cannot be directly created by the user. It is a subclass of the Object class.

Figure 5-46. The RexxContext class and methods

args

>>-args---------------------------------------------------------><

Returns the arguments used to invoke the current context as an array. This is equivalent to using the Arg(1, 'A') built-in function.

condition

>>-condition----------------------------------------------------><

Returns the current context condition object, or the Nil object if the context does not currently have a trapped condition. This is equivalent to using the Condition('O') built-in function.

digits

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

Returns the current context digits setting. This is equivalent to using the digits() built-in function.

executable

>>-executable-------------------------------------------------><

Returns the current executable object for the current context. The executable will be either a Routine or Method object, depending on the type of the active context.

form

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

Returns the current context form setting. This is equivalent to using the form() built-in function.

fuzz

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

Returns the current context fuzz setting. This is equivalent to using the fuzz() built-in function.

line

>>-line-------------------------------------------------------><

Returns the context current execution line. This is equivalent to using the .LINE environment symbol.

package

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

Returns the Package object associated with the current executable object.

rs

>>-rs-------------------------------------------------------><

Returns the context current return status value. If no host commands have been issued in the current context, the Nil object is returned. This is equivalent to using the .RS environment symbol.

variables

>>-variables--------------------------------------------------><

Returns a directory object containing all of the variables in the current execution context. The directory keys will be the variable names and the mapped values are the values of the variables. The directory will only contain simple variables and stem variables. Compound variable values may be accessed by using the stem objects that are returned for the stem variable names.

The WeakReference Class

A WeakReference instance maintains a non-pinning reference to another object. A non-pinning reference does not prevent an object from getting garbage collected or having its uninit method run when there are no longer normal references maintained to the object. Once the referenced object is eligible for garbage collection, the reference inside the WeakReference instance will be cleared and the VALUE method will return .nil on all subsequent calls. WeakReferences are useful for maintaining caches of objects without preventing the objects from being reclaimed by the garbage collector when needed.

Figure 5-47. The WeakReference class and methods

Note: The WeakReference class also has available class methods that its metaclass, the Class class, defines.

new (Class Method)

>>-new-(object)------------------------------------------------><

Returns a new WeakReference instance containing a reference to object.

value

>>-value------------------------------------------------><

This method returns the referenced object. If the object has been garbage collected, then the Nil object is returned.

The Pointer Class

Figure 5-48. The Pointer class and methods

A Pointer instance is a wrapper around a native pointer value. This class is designed primarily for writing methods and functions in native code and can only be created using the native code application programming interfaces. The Pointer class new method will raise an error if invoked.

Note: The Pointer class also has available class methods that its metaclass, the Class class, defines.

new (Class Method)

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

Creating Pointer object instances directly from Rexx code is not supported. The Pointer class new method will raise an error if invoked.

Operator Methods

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

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

For the Pointer class, the argument object must be a pointer object instance and the wrappered pointer value must be the same.

The comparison operators you can use in a message are:

=, ==

True if the wrappered pointer values are the same.

\=, ><, <>, \==

True if the wrappered pointer values are not the same.

isNull

>>-isNull-----------------------------------------------><

Returns 1 (true) if the wrappered pointer value is a NULL pointer (0) value. Returns 0 (false) if the pointer value is non-zero.

The Buffer Class

Figure 5-49. The Buffer class and methods

A Buffer instance is a Rexx interpreter managed block of storage. This class is designed primarily for writing methods and functions in native code and can only be created using the native code application programming interfaces. The Buffer class new method will raise an error if invoked.

Note: The Buffer also has available class methods that its metaclass, the Class class, defines.

new (Class Method)

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

Creating Buffer object instances directly from Rexx code is not supported. The Buffer class new method will raise an error if invoked.