Open Object Rexx™: Reference
Prev	Chapter 5. The Builtin Classes	Next

The Utility Classes

This section describes the miscellaneous classes supplied by ooRexx.

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-25. The DateTime class and methods

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

Inherited Methods

Methods inherited from the Object class.

new (class method)	init	Request
= \= == \== <> ><	instanceMethod	Run
class	instanceMethods	setMethod
copy	isA	start
defaultName	isInstanceOf	string
hasMethod	objectName	unsetMethod
identityHash	objectName=

Methods inherited from the Comparable class.

compareTo

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

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 space (" ") is the default separator.

fromEuropeanDate (Class Method)

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

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

fromOrderedDate (Class Method)

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

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

fromStandardDate (Class Method)

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

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.

fromUsaDate (Class Method)

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

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.

fromNormalTime (Class Method)

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

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.

fromCivilTime (Class Method)

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

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.

fromLongTime (Class Method)

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

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.

fromBaseDate (Class Method)

>>-fromBaseDate(date)---------------------------------------------><

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

fromTicks (Class Method)

>>-fromTicks(time)----------------------------------------><

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

fromIsoDate (Class Method)

>>-fromIsoDate(date)--------------------------------------><

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.

init

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

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

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

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

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)

Comparison Methods

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

Returns 1 (true) or 0 (false), the result of performing the specified comparison operation. The receiver object and the argument are the terms compared. Both must be DateTime objects. If argument is not a DateTime object, a SYNTAX error condition is raised.

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

Examples:

d = .DateTime~new       -- get the current time
midnight = d~date       -- get the start of the day
startTime = midnight~addHours(10)  -- time the bank opens
endTime = startTime~addHours(7)    -- bank closing time

if startTime <= d & d <= endTime then do
    say "The bank is open"
end

All strict comparison operations have one of the characters doubled that define the operator. The DateTime 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

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.

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

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 "1", etc.

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

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.

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-26. 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 blanks are not allowed in the atime. If you do not specify a date, the language processor 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  describes the ::CLASS directive */
/* ::Method  describes the ::METHOD directive */
::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-27. The TimeSpan class and methods

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

Inherited Methods

Methods inherited from the Object class.

new (class method)	init	Request
= \= == \== <> ><	instanceMethod	Run
class	instanceMethods	setMethod
copy	isA	start
defaultName	isInstanceOf	string
hasMethod	objectName	unsetMethod
identityHash	objectName=

Methods inherited from the Comparable class.

compareTo

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)

Comparison Methods

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

Returns 1 (true) or 0 (false), the result of performing the specified comparison operation. The receiver object and the argument are the terms compared. Both must be TimeSpan objects. If argument is not a TimeSpan object, a SYNTAX error condition is raised.

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

Examples:


                                   -- get the current time
currentTime = .DateTime~new~timeOfDay
startTime = .timespan~new(10)
endTime = startTime~addHours(7)    -- bank closing time

if startTime <= currentTime & currentTime <= endTime then do
    say "The bank is open"
end

All strict comparison operations have one of the characters doubled that define the operator. The TimeSpan 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

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-28. 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 Comparator Class

Figure 5-29. 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 .

This method is defined as an abstract method. Inheriting classes are expected to define an implementation specific to the comparison being performed.

The CaselessColumnComparator Class

Figure 5-30. 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.

Inherited Methods

Methods inherited from the Object class.

new (class method)	init	Request
= \= == \== <> ><	instanceMethod	Run
class	instanceMethods	setMethod
copy	isA	start
defaultName	isInstanceOf	string
hasMethod	objectName	unsetMethod
identityHash	objectName=

Methods inherited from the Comparator class.

compare

This method overrides the compare method from the Comparator class.

>>-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 CaselessComparator Class

Figure 5-31. 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.

Inherited Methods

Methods inherited from the Object class.

new (class method)	init	Request
= \= == \== <> ><	instanceMethod	Run
class	instanceMethods	setMethod
copy	isA	start
defaultName	isInstanceOf	string
hasMethod	objectName	unsetMethod
identityHash	objectName=

Methods inherited from the Comparator class.

compare

This method overrides the compare method from the Comparator class.

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

Figure 5-32. 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.

Inherited Methods

Methods inherited from the Object class.

new (class method)	init	Request
= \= == \== <> ><	instanceMethod	Run
class	instanceMethods	setMethod
copy	isA	start
defaultName	isInstanceOf	string
hasMethod	objectName	unsetMethod
identityHash	objectName=

Methods inherited from the Comparator class.

compare

This method overrides the compare method from the Comparator class.

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

init

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

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

The CaselessDescendingComparator Class

Figure 5-33. 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.

Inherited Methods

Methods inherited from the Object class.

new (class method)	init	Request
= \= == \== <> ><	instanceMethod	Run
class	instanceMethods	setMethod
copy	isA	start
defaultName	isInstanceOf	string
hasMethod	objectName	unsetMethod
identityHash	objectName=

Methods inherited from the Comparator class.

compare

This method overrides the compare method from the Comparator class.

>>-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 DescendingComparator Class

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

Figure 5-34. 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.

Inherited Methods

Methods inherited from the Object class.

new (class method)	init	Request
= \= == \== <> ><	instanceMethod	Run
class	instanceMethods	setMethod
copy	isA	start
defaultName	isInstanceOf	string
hasMethod	objectName	unsetMethod
identityHash	objectName=

Methods inherited from the Comparator class.

compare

This method overrides the compare method from the Comparator class.

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

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

Figure 5-35. 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.

Inherited Methods

Methods inherited from the Object class.

new (class method)	init	Request
= \= == \== <> ><	instanceMethod	Run
class	instanceMethods	setMethod
copy	isA	start
defaultName	isInstanceOf	string
hasMethod	objectName	unsetMethod
identityHash	objectName=

Methods inherited from the Comparator class.

compare

This method overrides the compare method from the Comparator class.

>>-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 forwards messages to a destination object. It is a subclass of the Object class.

Figure 5-36. 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 that contains a string on which certain string operations such as concatenation can be performed very efficiently. (Frequent concatenation of long strings without using this class might result in weak performance, large memory allocation, or both.)

Figure 5-37. The MutableBuffer class and methods

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

new

                   +-----,-256------+
>>-new(-+--------+-+----------------+-)--------------------><
        +-string-+ +-,-buffer size--+

This method overrides the new method from the Object class.

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

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.

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()
x1 = "abc def ghi"
x1~lastPos(" ")      ->    8
x1 = "abcdefghi"
x1~lastPos(" ")      ->    0
x1 = "efgxyz"
x1~lastPos("xy")     ->    4
x1 = "abc def ghi"
x1~lastPos(" ",7)    ->    4

length

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

Returns length of data in 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()
x1 = "Saturday"
x1~pos("day")       ->    6
x1 = "abc def ghi"
x1~pos("x")         ->    0
x1 = "abc def ghi"
x1~pos(" ")         ->    4
x1 = "abc def ghi"
x1~pos(" ",5)       ->    8

request

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

Returns an object of the classid class, or the Nil object if the request cannot be satisfied. The MutableBuffer class supports converting to "STRING" and "ARRAY". The "ARRAY" conversion returns the buffer contents as lines split at line end boundaries.

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 (a string).

subchar

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

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

substr

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

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

uninit

>>-uninit------------------------------------------------------><

This method cleans up the object when it is garbage collected. It should not be invoked directly except via an uninit method of a subclass of the MutableBuffer class.

If the MutableBuffer class is subclassed and the subclass provides an uninit method then that method must invoke the superclass uninit method The following example shows how to accomplish this.

::class CustomMutableBuffer subclass MutableBuffer

...

::method uninit
/* the subclass instance cleanup code should be placed here */
super~uninit  -- this should be the last action in the method
return

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 either explicitly call the program file or use a ::requires statement to activate its functionality, as follows:

call "rxregexp.cls"
      or
::requires "rxregexp.cls"

Figure 5-38. 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 the given 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 automation 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 either Parse, Pos or Match ended, depending on what was invoked last.

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

Figure 5-39. 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.

delete

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

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

pull

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

Reads a line from the Rexx external queue. If the queue is currently empty, this method will immediately return .nil 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 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 StreamSupplier Class

A supplier object that will provided stream lines using supplier semantics.

Figure 5-40. The StreamSupplier class and methods

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

Inherited Methods

Methods inherited from the Object class.

new (class method)	init	Request
= \= == \== <> ><	instanceMethod	Run
class	instanceMethods	setMethod
copy	isA	start
defaultName	isInstanceOf	string
hasMethod	objectName	unsetMethod
identityHash	objectName=

Methods inherited from the Supplier class.

new (class method)	available	item
allIndexes	index	next
allItems	init	supplier

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

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

The Supplier Class

You can use a supplier object to enumerate the items a collection contained at the time of the supplier's creation.

Figure 5-41. The Supplier class and methods

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

The following methods return a supplier object:

The supplier methods of the Array, Bag, Directory, List, Queue, Relation, Set, Table, and Stream classes
The methods method of the Class class

new (Class Method)

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

Returns a new supplier object. The values argument must be an array of values 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 values 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---------------------------------------------------><

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

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

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.

Prev	Home	Next
The Collection Classes	Up	The Windows Specific Classes