5.4. The Utility Classes

This section describes the Rexx utility classes.

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

Table 5.28. ooRexx DateTime Class

Object
↓
DateTime
+ Comparable
+ Orderable
fromBaseDate fromCivilTime fromEuropeandate fromIsoDate fromLongTime fromNormalDate fromNormalTime fromOrderedDate	fromStandardDate fromTicks fromUsaDate fromUTCIsoDate maxDate minDate today
+ - addDays addHours addMicroseconds addMinutes addSeconds addWeeks addYears baseDate civilTime compareTo date day dayMicroseconds dayMinutes dayName daySeconds	daysInMonth daysInYear elapsed europeanDate fullDate hashCode hours init isLeapYear isoDate languageDate longTime microseconds minutes month monthName normalDate	normalTime offset orderedDate seconds standardDate string ticks timeOfDay toLocalTime toTimeZone toUtcTime usaDate utcDate utcIsoDate weekDay year yearDay

Note

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

5.4.1.1. Inherited Methods

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

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

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

compareTo

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

=, \=, ==, \==, <>, ><, >, <, >=, \<, <=, \>, >>, <<, >>=, \<<, <<=, \>> (Comparison Methods)

5.4.1.2. minDate (Class Method)


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

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

5.4.1.3. maxDate (Class Method)


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

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

5.4.1.4. today (Class Method)


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

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

5.4.1.5. fromNormalDate (Class Method)


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

Creates a DateTime object from a string returned by the Normal option of the Date() (Section 7.4.24, “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.

5.4.1.6. fromEuropeanDate (Class Method)


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

Creates a DateTime object from a string returned by the European option of the Date() (Section 7.4.24, “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.

5.4.1.7. fromOrderedDate (Class Method)


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

Creates a DateTime object from a string returned by the Ordered option of the Date() (Section 7.4.24, “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.

5.4.1.8. fromStandardDate (Class Method)


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

Creates a DateTime object from a string returned by the Standard option of the Date() (Section 7.4.24, “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.

5.4.1.9. fromUsaDate (Class Method)


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

Creates a DateTime object from a string returned by the Usa option of the Date() (Section 7.4.24, “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.

5.4.1.10. fromNormalTime (Class Method)


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

Creates a DateTime object from a string returned by the Normal option of the Time() (Section 7.4.65, “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.

5.4.1.11. fromCivilTime (Class Method)


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

Creates a DateTime object from a string returned by the Civil option of the Time() (Section 7.4.65, “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.

5.4.1.12. fromLongTime (Class Method)


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

Creates a DateTime object from a string returned by the Long option of the Time() (Section 7.4.65, “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.

5.4.1.13. fromBaseDate (Class Method)


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

Creates a DateTime object from a string returned by the Basedate option of the Date() (Section 7.4.24, “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.

5.4.1.14. fromTicks (Class Method)


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

Creates a DateTime object from a string returned by the Ticks option of the Date() (Section 7.4.24, “DATE”) or Time() (Section 7.4.65, “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.

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

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

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

Example 5.182. Class DATETIME


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)

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

Example 5.183. Class DATETIME - arithmetic


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)

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

5.4.1.20. year


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

Returns the year represented by this DateTime instance.

5.4.1.21. month


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

Returns the month represented by this DateTime instance.

5.4.1.22. day


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

Returns the day represented by this DateTime instance.

5.4.1.23. hours


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

Returns number of whole hours since midnight.

5.4.1.24. minutes


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

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

5.4.1.25. seconds


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

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

5.4.1.26. microseconds


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

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

5.4.1.27. dayMinutes


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

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

5.4.1.28. daySeconds


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

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

5.4.1.29. dayMicroseconds


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

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

5.4.1.30. hashCode


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

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

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

Example 5.184. Class DATETIME - addYears method


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"

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

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

Example 5.185. Class DATETIME - addDays method


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"

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

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

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

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

5.4.1.38. isoDate


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

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

5.4.1.39. utcIsoDate


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

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

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

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

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

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

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

5.4.1.45. monthName


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

Returns the name of the DateTime month, in English.

5.4.1.46. dayName


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

Returns the name of the DateTime day, in English.

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

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

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

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

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

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

5.4.1.53. longTime


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

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

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

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

5.4.1.56. toLocalTime


>>-toLocalTime-------------------------------------------><

Returns a new DateTime object representing the time for the local timezone.

5.4.1.57. toUtcTime


>>-toUtcTime-------------------------------------------><

Returns a new DateTime object representing the time for the UTC timezone (offset 0).

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

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

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

5.4.1.61. date


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

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

5.4.1.62. timeOfDay


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

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

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

5.4.1.64. isLeapYear


>>-isLeapYear---------------------------------------------><

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

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

5.4.1.66. daysInYear


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

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

5.4.1.67. string


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

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