const type: time

Describes times and dates. For dates the proleptic Gregorian calendar is used (which assumes that the Gregorian calendar was even in effect at dates preceding its official introduction). This convention is used according to ISO 8601 which also defines that positive and negative years exist and that the year preceding 1 is 0. Time is measured in hours, minutes, seconds and micro seconds. Additionally information about the difference to UTC and a flag indicating daylight saving time is maintained also.

const func time: (attr time) parse (in string: stri)

Convert a string in the ISO 8601 date format to a time. The accepted ISO 8601 date formats are YYYY-MM, YYYY-MM-DD, YYYY-MM-DDTHH, YYYY-MM-DDTHH:MM, YYYY-MM-DDTHH:MM:SS Additionally a space is also allowed to separate the date and the time representations: YYYY-MM-DD HH, YYYY-MM-DD HH:MM, YYYY-MM-DD HH:MM:SS

Returns:

the time result of the conversion.

Raises:

RANGE_ERROR - If stri contains not a valid time value.

const func boolean: (in time: aTime1) = (in time: aTime2)

Check if two time values are equal.

Returns:

TRUE if both times are equal, FALSE otherwise.

const func boolean: (in time: aTime1) <> (in time: aTime2)

Check if two time values are not equal.

Returns:

FALSE if both times are equal, TRUE otherwise.

const func boolean: (in time: aTime1) <= (in time: aTime2)

Check if aTime1 is less than or equal to aTime2.

Returns:

TRUE if aTime1 is less than or equal to aTime2, FALSE otherwise.

const func boolean: (in time: aTime1) >= (in time: aTime2)

Check if aTime1 is greater than or equal to aTime2.

Returns:

TRUE if aTime1 is greater than or equal to aTime2, FALSE otherwise.

const func boolean: (in time: aTime1) < (in time: aTime2)

Check if aTime1 is less than aTime2.

Returns:

TRUE if aTime1 is less than aTime2, FALSE otherwise.

const func boolean: (in time: aTime1) > (in time: aTime2)

Check if aTime1 is greater than aTime2.

Returns:

TRUE if aTime1 is greater than aTime2, FALSE otherwise.

const func boolean: isLeapYear (in integer: year)

Determine if a year is a leap year in the Gregorian calendar.

Returns:

TRUE if the year is a leap year, FALSE otherwise.

const func integer: daysInYear (in integer: year)

Determine the number of days in a 'year'.

Returns:

the number of days in the year.

const func integer: daysInMonth (in integer: year, in integer: month)

Determine the number of days in the 'month' of the given 'year'.

Returns:

the number of days in the month.

const func integer: daysInMonth (in time: date)

Determine the number of days in the month of a given date.

Returns:

the number of days in the month.

const func string: strDate (in time: aTime)

Convert a time to a string with ISO 8601 YYYY-MM-DD date format.

Returns:

the string result of the conversion.

const func string: strTime (in time: aTime)

Convert a time to a string with ISO 8601 hh:mm:ss time format.

Returns:

the string result of the conversion.

const func string: strDateTime (in time: aTime)

Convert a time to a string with ISO 8601 date and time format. The time is converted to the YYYY-MM-DD hh:mm:ss format. Microseconds, time zone and information about the daylight saving time are omitted.

Returns:

the string result of the conversion.

const func string: str (in time: aTime)

Convert a time to a string with ISO 8601 date and time format. The string has the format YYYY-MM-DD hh:mm:ss.uuuuuu followed by a time zone in the format UTC+n and (DST), if it is a daylight saving time. The microseconds (uuuuuu) are omitted, if they are zero. A time zone of UTC+0 is also omitted.

Returns:

the string result of the conversion.

const func string: literal (in time: aTime)

Convert a time to a time literal.

Returns:

the time literal.

const func time: time (in var string: stri)

Convert a string in the ISO 8601 date format to a time. The accepted ISO 8601 date formats are YYYY-MM, YYYY-MM-DD, YYYY-MM-DDTHH, YYYY-MM-DDTHH:MM, YYYY-MM-DDTHH:MM:SS Additionally a space is also allowed to separate the date and the time representations: YYYY-MM-DD HH, YYYY-MM-DD HH:MM, YYYY-MM-DD HH:MM:SS

Returns:

the time result of the conversion.

Raises:

RANGE_ERROR - If stri contains not a valid time value.

const func integer: compare (in time: aTime1, in time: aTime2)

Compares two times.

Returns:

-1, 0 or 1 if the first argument is considered to be respectively less than, equal to, or greater than the second.

const func integer: hashCode (in time: aTime)

Compute the hash value of a time.

Returns:

the hash value.

const func time: truncToSecond (in time: aTime)

Truncate 'aTime' to the beginning of a second.

Returns:

the truncated time.

const func time: truncToMinute (in time: aTime)

Truncate 'aTime' to the beginning of a minute.

Returns:

the truncated time.

const func time: truncToHour (in time: aTime)

Truncate 'aTime' to the beginning of a hour.

Returns:

the truncated time.

const func time: truncToDay (in time: aTime)

Truncate 'aTime' to the beginning of a day.

Returns:

the truncated time.

const func time: truncToMonth (in time: aTime)

Truncate 'aTime' to the beginning of the first day in the month.

Returns:

the truncated time.

const func time: truncToYear (in time: aTime)

Truncate 'aTime' to the beginning of the first day in the year.

Returns:

the truncated time.

const func integer: dayOfWeek (in time: aDate)

Return the weekday number of 'aDate'.

Returns:

1 for monday, 2 for tuesday, and so on up to 7 for sunday.

const func integer: dayOfYear (in time: aDate)

Return the day number in the year of 'aDate'.

Returns:

1 for the 1. of january and successive values up to 366.

const func integer: weekOfYear (in var integer: year, in integer: dayOfYear)

Return the week number of the 'year' for the 'dayOfYear'. According to ISO 8601: Week number 1 of every year contains the 4. of january. Since 1st to 3rd of january might be in the previous week there can be also a week number 0.

Returns:

a week number from 0 to 53 for weeks belonging to the year of the given date.

const func integer: weekOfYear (in time: aDate)

Return the week number of the year for 'aDate'. According to ISO 8601: Week number 1 of every year contains the 4. of january. Since 1st to 3rd of january might be in the previous week there can be also a week number 0.

Returns:

a week number from 0 to 53 for weeks belonging to the year of the given date.

const func integer: weekDateYear (in time: aDate)

Return the year of the ISO 8601 week date for 'aDate'. At the beginning and the end of an Gregorian calendar year there might be days which belong to a week of the previous or next year. For example 2005-01-01 is 2004-W53-6 and 2007-12-31 is 2008-W01-1.

Returns:

the year in the range 'pred(aDate.year)' to 'succ(aDate.year)'.

const func integer: weekDateWeek (in time: aDate)

Return the week number of the ISO 8601 week date for 'aDate'. At the beginning and the end of an Gregorian calendar year there might be days which belong to a week of the previous or next year. For example 2005-01-01 is 2004-W53-6 and 2007-12-31 is 2008-W01-1.

Returns:

the week number in the range 1 to 53.

const func time: toUTC (in time: aTime)

Convert a time to Coordinated Universal Time (UTC).

Returns:

the time in UTC.

const func time: toLocalTZ (in time: aTime)

Convert the time aTime to a time in the local time zone. In the result year, month, day, hour, minute, secand and micro_second from aTime are adjusted to the local time zone. In the time zone of Central European Time (CET) the following holds:

str(toLocalTZ(time("2000-1-1")))  returns "2000-01-01 01:00:00 UTC+1"

Returns:

the time in the local time zone.

const func time: setLocalTZ (in time: aTime)

Sets timeZone and daylightSavingTime for a given time. In the result year, month, day, hour, minute, secand and micro_second from aTime are returned unchanged. In the time zone of Central European Time (CET) the following holds:

str(setLocalTZ(time("2000-1-1")))  returns "2000-01-01 00:00:00 UTC+1"

Returns:

the time where the local time zone has been set.

const func integer: julianDayNumber (in time: aDate)

Compute the julian day number of 'aDate'. The julian day number is the number of days that have elapsed since January 1, 4713 BC in the proleptic Julian calendar.

Returns:

the julian day number.

const func time: julianDayNumToTime (in integer: julianDayNumber)

Return the time of a 'julianDayNumber'. The julian day number is the number of days that have elapsed since January 1, 4713 BC in the proleptic Julian calendar.

Returns:

the time 0:00:00 at the day with the 'julianDayNumber'.

const func integer: timestamp1970 (in time: aTime)

Return a time expressed in seconds since the Unix epoch. The Unix epoch (1970-01-01 00:00:00 UTC) corresponds to 0.

Returns:

the seconds since the Unix epoch.

const func time: timestamp1970ToTime (in integer: timestamp)

Convert a Unix timestamp into a time from the local time zone. The timestamp is expressed in seconds since the Unix epoch. The Unix epoch (1970-01-01 00:00:00 UTC) corresponds to 0.

Returns:

the local time that corresponds to the timestamp.

const func integer: timestamp1601 (in time: aTime)

Return a time expressed as Windows FILETIME. A FILETIME is expressed in 100-nanosecond intervals since the Windows epoch. The Windows epoch (1601-01-01 00:00:00 UTC) corresponds to 0.

Returns:

the number of 100-nanosecond intervals since the Windows epoch.

const func time: timestamp1601ToTime (in integer: timestamp)

Convert a Windows FILETIME into a time from the local time zone. A FILETIME is expressed in 100-nanosecond intervals since the Windows epoch. The Windows epoch (1601-01-01 00:00:00 UTC) corresponds to 0.

Returns:

the local time that corresponds to the FILETIME.

const func time: rand (in time: low, in time: high)

Compute pseudo-random time in the range [low, high]. The random values are uniform distributed.

Returns:

a random time such that low <= rand(low, high) and rand(low, high) <= high holds.

Raises:

RANGE_ERROR - The range is empty (low > high holds).

const func time: time (NOW)

Determine the current local time.

Returns:

the current local time.

const func time: time (in integer: year, in integer: month, in integer: day, in integer: hour, in integer: minute, in integer: second)

Return the specified UTC time.

const func time: time (in integer: year, in integer: month, in integer: day, in integer: hour, in integer: minute, in integer: second, in integer: micro_second)

Return the specified UTC time.

const func time: timeInTimeZone (in integer: year, in integer: month, in integer: day, in integer: hour, in integer: minute, in integer: second, in integer: timeZone)

Return the specified time in the specified timeZone.

const func time: date (in integer: year, in integer: month, in integer: day)

Return the specified UTC date.

const proc: await (ref time: aTime)

Wait until 'aTime' is reached