3.3. Date and Time Functions

3.3. Date and Time Functions
Prev	Chapter 3. Function Library	Next

3.3.1. clock_getmicros()

Synopsis

Returns an integer representing the system time in microseconds (1/1000000 second intervals) since Jan 1, 1970 00:00:00Z.

Prototype

int clock_getmicros() (CONST)

Example

$time = clock_getmicros();

Table 3.39. Arguments and Return Values for clock_getmicros()

Argument Type	Return Type	Description
n/a	`int`	Returns the number of microseconds (1/1000000 second) since Jan 1, 1970 00:00.

This function does not throw any exceptions.

3.3.2. clock_getmillis()

Synopsis

Returns an integer representing the system time in milliseconds (1/1000 second intervals since Jan 1, 1970 00:00).

Prototype

int clock_getmillis() (CONST)

Example

$time = clock_getmillis();

Table 3.40. Arguments and Return Values for clock_getmillis()

Argument Type	Return Type	Description
n/a	`int`	Returns the number of milliseconds (1/1000 second) since Jan 1, 1970 00:00.

This function does not throw any exceptions.

3.3.3. clock_getnanos()

Synopsis

Returns the system time in nanoseconds (1/1000000000 second intervals) since Jan 1, 1970 00:00:00Z.

Prototype

int clock_getnanos() (CONST)

Example

$time = clock_getnanos();

Table 3.41. Arguments and Return Values for clock_getnanos()

Argument Type	Return Type	Description
n/a	`int`	Returns the number of nanoseconds (1/1000000000 second) since Jan 1, 1970 00:00:00Z.

This function does not throw any exceptions.

3.3.4. date_info()

Synopsis

Returns a hash of broken-down date/time information for the given date argument; if the variant with no argument is used, then the current date/time is assumed.

Prototype

hash date_info(date $date) (CONST)

hash date_info() (CONST)

Example

my hash $h = date_info($date);

Table 3.42. Arguments and Return Values for date_info()

Argument Type	Return Type	Description
`[date $date]`	`hash`	Returns a hash of broken-down date/time information for the given date argument; if the variant with no argument is used, then the current date/time is assumed.

This function does not throw any exceptions.

Table 3.43. Date Info Hash Description

Key	Type	Absolute/Relative	Description
`relative`	bool	Both	True if the date is a relative date, False if it is absolute
`year`	int	Both	The year value of the date
`month`	int	Both	The month value of the date
`day`	int	Both	The day value of the date (day of the month for absolute dates)
`hour`	int	Both	The hour value of the date
`minute`	int	Both	The minute value of the date
`second`	int	Both	The second value of the date
`microsecond`	int	Both	The microsecond value of the date
`dow`	int	Absolute Only	The day of the week, where 0=Sunday, 1=Monday, ... 6=Saturday
`doy`	int	Absolute Only	The ordinal day number in the year.
`utc_secs_east`	int	Absolute Only	Offset from UTC in seconds east; if the time zone is west of UTC then the value will be negative.
`dst`	bool	Absolute Only	A flag if daylight savings time is in effect
`zone`	TimeZone	Absolute Only	The time zone for the time.
`zone_name`	string	Absolute Only	The name of the time zone for the given time (ex: "CEST" for Central European Summer Time for a time during summer time or "CET" for Central European Time for the same time zone while daylight savings time is not active).

3.3.5. date_ms()

Synopsis

Converts an integer argument representing the offset in milliseconds from January 1, 1970 in the local time zone to a date in the local time zone.

See also date(), date_us(), and localtime().

Prototype

date date_ms(softint) (CONST)

date date_ms() (RT_NOOP)

Example

my date $date = date_ms(1); # returns 1970-01-01T00:00:00.001

Table 3.44. Arguments and Return Values for date_ms()

Argument Type	Return Type	Description
`int`	`date`	Returns the date corresponding to the offset in ms given from January 1, 1970 in the local time zone.

This function does not throw any exceptions.

3.3.6. date_us()

Synopsis

Converts an integer argument representing the offset in microseconds from January 1, 1970 in the local time zone to a date in the local time zone.

See also date(), date_ms(), and localtime().

Prototype

date date_us(softint) (CONST)

date date_us() (RT_NOOP)

Example

my date $date = date_us(1); # returns 1970-01-01T00:00:00.000001

Table 3.45. Arguments and Return Values for date_us()

Argument Type	Return Type	Description
`int`	`date`	Returns the date corresponding to the offset in microseconds given from January 1, 1970 in the local time zone.

This function does not throw any exceptions.

3.3.7. days

Synopsis

Returns a relative date/time value in days for date arithmetic.

Prototype

date days(softint) (CONST)

date days() (RT_NOOP)

Example

$days = days(5 * 5); # returns 25D

Table 3.46. Arguments and Return Values for days()

Argument Type	Return Type	Description
`int`	`date`	Returns a relative date/time value corresponding to the number of days passed as an argument, to be used in date arithmetic.

This function does not throw any exceptions.

3.3.8. format_date()

Synopsis

Returns a formatting string for a date argument passed. See Date Formatting for information about the formatting string.

Prototype

string format_date(string, date) (CONST)

nothing format_date() (RT_NOOP)

Example

my string $str = format_date("Day, Mon D, YYYY-MM-DD HH:mm:SS", 2004-02-01T12:30:00);
# returns "Sunday, Feb 1, 2004-02-01 12:30:00"

Table 3.47. Arguments and Return Values for format_date()

Argument Type	Return Type	Description
`string`, Date	`string`	Formats the date value using the string as a formatting specification.

This function does not throw any exceptions.

Table 3.48. Date Format Arguments

Format Code	Description
`YY`	last two digits of year
`YYYY`	four-digit year
`M`	non zero-padded month number (1-12)
`MM`	zero-padded two-digit month number (01-12)
`Month`	long month string (ex: January)
`MONTH`	long month string capitalized (ex: JANUARY)
`Mon`	abbreviated month (ex: Jan)
`MON`	abbreviated month, capitalized (ex: JAN)
`D`	non zero-padded day number (1 - 31)
`DD`	zero-padded day number (01 - 31)
`Day`	long day of week string (ex: Monday)
`DAY`	long day of week string, capitalized (ex: MONDAY)
`Dy`	abbreviated day of week string (ex: Mon)
`DY`	abbreviated day of week string capitalised (ex: MON)
`H`	non zero-padded hour number (0 - 23)
`HH`	zero-padded hour number (00 - 23)
`h`	non zero-padded hour number, 12-hour clock (1 - 12)
`hh`	zero-padded hour number, 12-hour clock (01 - 12)
`m`	non zero-padded minute number (0 - 59)
`mm`	zero-padded minute number (00 - 59)
`S`	non zero-padded second number (0 - 59)
`SS`	zero-padded second number (00 - 59)
`P`	AM or PM (upper-case)
`p`	am or pm (lower-case)
`u`	non zero-padded millisecond number (0 - 999)
`uu` or `ms`	zero-padded millisecond number (000 - 999)
`x`	non zero-padded microsecond number (0 - 999999)
`xx` or `ms`	zero-padded microsecond number (000000 - 999999)
`y`	microseconds, with trailing zeros removed (suitable for use after the '.')
`z`	local time zone name (ex: 'EST') if available, otherwise the UTC offset (see 'Z')
`Z`	time zone UTC offset like +HH:mm[:SS], seconds are included if non-zero

All other text is output directly in the output text unchanged.

3.3.9. get_days()

Synopsis

Returns an integer value representing the days value of the date passed (can be either a relative or absolute date).

Prototype

int get_days(date) (CONST)

nothing get_days() (RT_NOOP)

Example

$days = get_days(2007-01-23); # returns 23

Table 3.49. Arguments and Return Values for get_days()

Argument Type	Return Type	Description
`date`	`int`	Returns an integer value representing the days value of the date passed (can be either a relative or absolute date).

3.3.10. get_duration_microseconds()

Synopsis

Returns an integer value representing the the number of microseconds in the value of the date passed (can be either a relative or absolute date).

If the argument is an absolute date/time value, then the resulting number is calculated from the present time. Fixed-time arguments in the past will result in a return value of 0; this function can only return a negative value if passed a relative date/time value.

Prototype

int get_duration_microseconds(date) (CONST)

Example

my int $us = get_duration_microseconds(PT2M15S3u); # returns 135000003

Table 3.50. Arguments and Return Values for get_duration_microseconds()

Argument Type	Return Type	Description
`date`	`int`	Returns an integer value representing the the number of microseconds in the value of the date passed; note that the return value will be calculated from the present time if an absolute date/time value argument is passed, but in this case will never be negative; fixed-time arguments in the past will result in a value of 0 being returned.

3.3.11. get_duration_milliseconds()

Synopsis

Returns an integer value representing the the number of milliseconds in the value of the date passed (can be either a relative or absolute date).

If the argument is an absolute date/time value, then the resulting number is calculated from the present time. Fixed-time arguments in the past will result in a return value of 0; this function can only return a negative value if passed a relative date/time value.

Prototype

int get_duration_milliseconds(date) (CONST)

Example

my int $us = get_duration_milliseconds(PT2M15S3u); # returns 135000

Table 3.51. Arguments and Return Values for get_duration_milliseconds()

Argument Type	Return Type	Description
`date`	`int`	Returns an integer value representing the the number of milliseconds in the value of the date passed; note that the return value will be calculated from the present time if an absolute date/time value argument is passed, but in this case will never be negative; fixed-time arguments in the past will result in a value of 0 being returned.

3.3.12. get_duration_seconds()

Synopsis

Returns an integer value representing the the number of seconds in the value of the date passed (can be either a relative or absolute date).

If the argument is an absolute date/time value, then the resulting number is calculated from the present time. Fixed-time arguments in the past will result in a return value of 0; this function can only return a negative value if passed a relative date/time value.

Prototype

int get_duration_seconds(date) (CONST)

Example

my int $us = get_duration_seconds(PT2M15S3u); # returns 135

Table 3.52. Arguments and Return Values for get_duration_seconds()

Argument Type	Return Type	Description
`date`	`int`	Returns an integer value representing the the number of seconds in the value of the date passed; note that the return value will be calculated from the present time if an absolute date/time value argument is passed, but in this case will never be negative; fixed-time arguments in the past will result in a value of 0 being returned.

3.3.13. get_epoch_seconds()

Synopsis

Returns the number of seconds of the date and time in local time passed since Jan 1, 1970, 00:00:00 Z (UTC). Negative values are returned for dates before the epoch.

This function is equivalent to mktime().

Prototype

int get_epoch_seconds(date) (CONST)

nothing get_epoch_seconds() (RT_NOOP)

Example

$secs = get_epoch_seconds(2007-09-23T00:00:01);

Table 3.53. Arguments and Return Values for get_epoch_seconds()

Argument Type	Return Type	Description
`date`	`int`	The date argument should be in local time; the function returns the number of seconds passed since Jan 1, 1970 00:00:00 corresponding to this date.

This function does not throw any exceptions.

3.3.14. get_hours()

Synopsis

Returns an integer value representing the hours value of the date passed (can be either a relative or absolute date).

Prototype

int get_hours(date) (CONST)

nothing get_hours() (RT_NOOP)

Example

$hours = get_hours(2007-01-23T11:24:03); # returns 11

Table 3.54. Arguments and Return Values for get_hours()

Argument Type	Return Type	Description
`date`	`int`	Returns an integer value representing the hours value of the date passed (can be either a relative or absolute date).

3.3.15. get_microseconds()

Synopsis

Returns an integer value representing the microseconds value of the date passed (can be either a relative or absolute date).

Prototype

int get_microseconds(date) (CONST)

nothing get_microseconds() (RT_NOOP)

Example

$ms = get_microseconds(2007-01-23T11:24:03.250); # returns 250

Table 3.55. Arguments and Return Values for get_microseconds()

Argument Type	Return Type	Description
`date`	`int`	Returns an integer value representing the microseconds value of the date passed (can be either a relative or absolute date).

3.3.16. get_midnight()

Synopsis

Returns a date/time value representing midnight on the date passed (strips the time from the date passed and returns the new value)

Prototype

date get_midnight(date) (CONST)

nothing get_midnight() (RT_NOOP)

Example

$date = get_midnight(2007-01-23T11:24:03.250); # returns 2007-01-23T00:00:00.000

Table 3.56. Arguments and Return Values for get_midnight()

Argument Type	Return Type	Description
`date`	`date`	Returns a date/time value representing midnight on the date passed (strips the time from the date passed and returns the new value)

3.3.17. get_milliseconds()

Synopsis

Returns an integer value representing the milliseconds value of the date passed (can be either a relative or absolute date).

Prototype

int get_milliseconds(date) (CONST)

nothing get_milliseconds() (RT_NOOP)

Example

$ms = get_milliseconds(2007-01-23T11:24:03.250); # returns 250

Table 3.57. Arguments and Return Values for get_milliseconds()

Argument Type	Return Type	Description
`date`	`int`	Returns an integer value representing the milliseconds value of the date passed (can be either a relative or absolute date).

3.3.18. get_minutes()

Synopsis

Returns an integer value representing the minutes value of the date passed (can be either a relative or absolute date).

Prototype

int get_minutes(date) (CONST)

nothing get_minutes() (RT_NOOP)

Examples

$minutes = get_minutes(2007-01-23T11:24:03); # returns 24

Table 3.58. Arguments and Return Values for get_minutes()

Argument Type	Return Type	Description
`date`	`int`	Returns an integer value representing the minutes value of the date passed (can be either a relative or absolute date).

3.3.19. get_months()

Synopsis

Returns an integer value representing the months value of the date passed (can be either a relative or absolute date).

Prototype

int get_months(date) (CONST)

nothing get_months() (RT_NOOP)

Example

$months = get_months(2007-01-23); # returns 1

Table 3.59. Arguments and Return Values for get_months()

Argument Type	Return Type	Description
`date`	`int`	Returns an integer value representing the months value of the date passed (can be either a relative or absolute date).

3.3.20. get_seconds()

Synopsis

Returns an integer value representing the seconds value of the date passed (can be either a relative or absolute date).

Prototype

int get_seconds(date) (CONST)

nothing get_seconds() (RT_NOOP)

Example

$secs = get_seconds(2007-01-23T11:24:03); # returns 3

Table 3.60. Arguments and Return Values for get_seconds()

Argument Type	Return Type	Description
`date`	`int`	Returns an integer value representing the seconds value of the date passed (can be either a relative or absolute date).

3.3.21. get_years()

Synopsis

Returns an integer value representing the years value of the date passed (can be either a relative or absolute date).

Prototype

int get_years(date) (CONST)

nothing get_years() (RT_NOOP)

Example

$years = get_years(2007-01-23); # returns 2007

Table 3.61. Arguments and Return Values for get_years()

Argument Type	Return Type	Description
`date`	`int`	Returns an integer value representing the years value of the date passed (can be either a relative or absolute date).

3.3.22. getDateFromISOWeek()

Synopsis

Retuns an absolute date value for the ISO-8601 calendar week information passed (year, week number, optional: weekday, where 1=Monday, 7=Sunday) in the current time zone. If the weekday is omitted, Monday (1) is assumed; throws an exception if the arguments are invalid.

Prototype

date getDateFromISOWeek(softint $year, softint $month, softint $wday = 1)

Example

$date = getDateFromISOWeek(2007, 3); # returns 2007-01-15T00:00:00

Table 3.62. Arguments and Return Values for getDateFromISOWeek()

Argument Type	Return Type	Description
`softint $year, softint $month, softint $wday = 1`	`date`	Retuns an absolute date value in the local time zone for the ISO-8601 calendar week information passed (year, week number, optional: week day). If the week day is passed, it must be in the range 1 (Monday) - 7 (Sunday) inclusive.

Table 3.63. Exceptions Thrown by getDateFromISOWeek()

err	desc
`ISO-8601-INVALID-WEEK`	The week number is not valid for the given year.
`ISO-8601-INVALID-DAY`	The day number is not between 1 (Monday) and 7 (Sunday) inclusive.

3.3.23. getDayOfWeek()

Synopsis

Returns an integer representing the day of the week for the absolute date passed (0=Sunday, 6=Saturday)

Prototype

int getDayOfWeek(date) (CONST)

nothing getDayOfWeek() (RT_NOOP)

Prototype

$dow = getDayOfWeek(2007-05-15); # returns 2

Table 3.64. Arguments and Return Values for getDayOfWeek()

Argument Type	Return Type	Description
`date`	`int`	Returns an integer representing the day of the week for the absolute date passed (0=Sunday, 6=Saturday)

3.3.24. getDayNumber()

Synopsis

Returns an integer representing the ordinal day number in the year for the absolute date passed

Prototype

int getDayNumber(date) (CONST)

nothing getDayNumber() (RT_NOOP)

Example

$dn = getDayNumber(2007-05-15); # returns 135

Table 3.65. Arguments and Return Values for getDayNumber()

Argument Type	Return Type	Description
`date`	`int`	Returns an integer representing the ordinal day number in the year for the absolute date passed

3.3.25. getISODayOfWeek()

Synopsis

Returns an integer representing the ISO-8601 day of the week for the absolute date passed (1=Monday, 7=Sunday)

Prototype

int getISODayOfWeek(date) (CONST)

nothing getISODayOfWeek() (RT_NOOP)

Example

$dow = getISODayOfWeek(2007-05-15); # returns 2 for Tuesday

Table 3.66. Arguments and Return Values for getISODayOfWeek()

Argument Type	Return Type	Description
`date`	`int`	Returns an integer representing the ISO-8601 day of the week for the absolute date passed (1=Monday, 7=Sunday)

3.3.26. getISOWeekHash()

Synopsis

Returns a hash representing the ISO-8601 calendar week information for the absolute date passed (hash keys: year, week, day). Note that the ISO-8601 year does not always correspond with the calendar year at the end and the begin ning of every year (for example 2006-01-01 is ISO-8601 calendar week format is: year=2005, week=52, day=7)

Prototype

hash getISOWeekHash(date) (CONST)

nothing getISOWeekHash() (RT_NOOP)

Example

$h = getISOWeekHash(2007-05-15); # returns year=2007, week=20, day=2

Table 3.67. Arguments and Return Values for getISOWeekHash()

Argument Type	Return Type	Description
`date`	`hash`	Returns a `hash` of `int` representing the ISO-8601 calendar week information for the absolute date passed (hash keys: `year, week, day`)

3.3.27. getISOWeekString()

Synopsis

Returns a string representing the ISO-8601 calendar week information for the absolute date passed (ex: 2006-01-01 = "2005-W52-7"). Note that the ISO-8601 year does not always correspond with the calendar year at the end and the beginning of every year (for example 2006-01-01 is ISO-8601 calendar week format is: year=2005, week=52, day=7)

Prototype

string getISOWeekString(date) (CONST)

nothing getISOWeekString() (RT_NOOP)

Example

$str = getISOWeekString(2007-05-15); # returns "2007-W20-2"

Table 3.68. Arguments and Return Values for getISOWeekString()

Argument Type	Return Type	Description
`date`	`string`	Returns a string representing the ISO-8601 calendar week information for the absolute date passed (ex: 2006-01-01 = "2005-W52-7")

3.3.28. gmtime()

Synopsis

Returns the date and time in GMT; if no argument is passed, then the current UTC time with a resolution of a second is returned. Otherwise the single argument must be an integer giving the number of seconds since Jan 1, 1970, 00:00:00, or an absolute date/time value that will be returned as the sme time in UTC (GMT).

See also now_utc().

Prototype

date gmtime(date $date) (CONST)

date gmtime(softint $epoch_seconds, softint $microseconds = 0) (CONST)

date gmtime() (CONST)

Example

$date = gmtime(now_us());  # equivalent to now_utc()

$date = gmtime();          # also returns current UTC (GMT)

Table 3.69. Arguments and Return Values for gmtime()

Argument Type	Return Type	Description
`date $date`	`date`	The date argument is converted to UTC and returned.
`softint $epoch_seconds, softint $microseconds = 0`	`date`	`$epoch_seconds` must be the number of seconds passed since Jan 1, 1970, 00:00:00 UTC (see get_epoch_seconds() for a function that returns such a value). `$microseconds` will give the microsecond offset for the resulting time.
n/a	`date`	If no argument is passed, then the current date and time with resolution to the second in GMT is returned. See now_utc() for a similar function that returns the current UTC time with resolution to the microsecond.

This function does not throw any exceptions.

3.3.29. hours()

Synopsis

Returns a relative date/time value in hours to be used in date arithmetic.

Prototype

date hours(softint) (CONST)

date hours() (RT_NOOP)

Example

$h = hours(5 * 5); # returns 25h

Table 3.70. Arguments and Return Values for hours()

Argument Type	Return Type	Description
`int`	`date`	Returns a relative date/time value corresponding to the number of hours passed as an argument, to be used in date arithmetic.

This function does not throw any exceptions.

3.3.30. is_date_absolute()

Synopsis

Returns True if the argument is an absolute date/time value, False if not.

Prototype

bool is_date_absolute(date) (CONST)

bool is_date_absolute(any) (RT_NOOP)

Example

my bool $b = is_date_absolute($date);

Table 3.71. Arguments and Return Values for is_date_absolute()

Argument Type	Return Type	Description
`date`	`bool`	Returns `True` if the argument is an absolute date/time value, `False` if not.

This function does not throw any exceptions.

3.3.31. is_date_relative()

Synopsis

Returns True if the argument is an relative date/time value, False if not.

Prototype

bool is_date_relative(date) (CONST)

bool is_date_relative(any) (RT_NOOP)

Example

my bool $b = is_date_relative($date);

Table 3.72. Arguments and Return Values for is_date_relative()

Argument Type	Return Type	Description
`date`	`bool`	Returns `True` if the argument is an relative date/time value, `False` if not.

This function does not throw any exceptions.

3.3.32. localtime()

Synopsis

Returns the date and time in local time corresponding to the integer argument passed, which must be the number of seconds since Jan 1, 1970, 00:00:00 Z (UTC). If no argument is passed, then the current local date and time are returned.

Prototype

date localtime(date $date) (CONST)

date localtime(softint $epoch_seconds, softint $microseconds = 0) (CONST)

date localtime() (CONST)

Example

$time = localtime(10);

Table 3.73. Arguments and Return Values for localtime()

Argument Type	Return Type	Description
`date $date`	`date`	The date argument is converted to the local time zone and returned.
`softint $epoch_seconds, softint $microseconds = 0`	`date`	`$epoch_seconds` must be the number of seconds passed since Jan 1, 1970, 00:00:00 UTC (see get_epoch_seconds() for a function that returns such a value). `$microseconds` will give the microsecond offset for the resulting time.
n/a	`date`	If no argument is passed, then the current date and time with resolution to the second in the local time zone is returned. See now_us() for a similar function that returns the current local time with resolution to the microsecond.

This function does not throw any exceptions.

3.3.33. microseconds()

Synopsis

Returns a relative date/time value in microseconds to be used in date arithmetic.

Prototype

date microseconds(softint) (CONST)

date microseconds() (RT_NOOP)

Example

$ms = millseconds(5 * 5); # returns 25ms

Table 3.74. Arguments and Return Values for microseconds()

Argument Type	Return Type	Description
`softint`	`date`	Returns a relative date/time value corresponding to the number of microseconds passed as an argument, to be used in date arithmetic.

This function does not throw any exceptions.

3.3.34. milliseconds()

Synopsis

Returns a relative date/time value in milliseconds to be used in date arithmetic.

Prototype

date milliseconds(softint) (CONST)

date milliseconds() (RT_NOOP)

Example

$ms = millseconds(5 * 5); # returns 25ms

Table 3.75. Arguments and Return Values for milliseconds()

Argument Type	Return Type	Description
`softint`	`date`	Returns a relative date/time value corresponding to the number of milliseconds passed as an argument, to be used in date arithmetic.

This function does not throw any exceptions.

3.3.35. minutes()

Synopsis

Returns a relative date/time value in minutes to be used in date arithmetic.

Prototype

date minutes(softint) (CONST)

date minutes() (RT_NOOP)

Example

$m = minutes(5 * 5); # returns 25m

Table 3.76. Arguments and Return Values for minutes()

Argument Type	Return Type	Description
`softint`	`date`	Returns a relative date/time value corresponding to the number of minutes passed as an argument, to be used in date arithmetic.

This function does not throw any exceptions.

3.3.36. mktime()

Synopsis

Returns the number of seconds passed since Jan 1, 1970, 00:00:00 Z (UTC) for the date/time argument passed.

Without the RT_NOOP variant, this function is equivalent to get_epoch_seconds().

Prototype

int mktime(date) (CONST)

nothing mktime() (RT_NOOP)

Example

$secs = mktime(2007-09-23T00:00:01);

Table 3.77. Arguments and Return Values for mktime()

Argument Type	Return Type	Description
`date`	`int`	This function returns the number of seconds passed since Jan 1, 1970 00:00:00Z corresponding to the date/time argument.

This function does not throw any exceptions.

3.3.37. months()

Synopsis

Returns a relative date/time value in months to be used in date arithmetic.

Prototype

date months(softint) (CONST)

date months() (RT_NOOP)

Example

$m = months(5 * 5); # returns 25M

Table 3.78. Arguments and Return Values for months()

Argument Type	Return Type	Description
`int`	`date`	Returns a relative date/time value corresponding to the number of months passed as an argument, to be used in date arithmetic.

This function does not throw any exceptions.

3.3.38. now()

Synopsis

Returns the current date and time in the local time zone with resolution to the second.

For similar functions returning the current date and time in the local time zone with millisecond and microsecond resolution, see now_ms() and now_us(). Note that there is no performance penalty for using now_ms() and now_us() versus this function, this function and now_ms() are kept for backwards-compatibility.

See also now_utc().

Prototype

date now() (CONST)

Example

my date $now = now();

Table 3.79. Arguments and Return Values for now()

Argument Type	Return Type	Description
n/a	`date`	Returns the current date and time in the local time zone with resolution to the second.

This function does not throw any exceptions.

3.3.39. now_ms()

Synopsis

Returns the current date and time in the local time zone with resolution to the millisecond.

For a similar function returning the current date and time in the local time zone with coarser granularity, when resolution only to the second is needed, see now(); for a similar function returning the current date and time with a resolution to the microsecond, see now_us(). Note that there is no performance penalty for using now_ms() and now_us() versus now(), now() and now_ms() are kept for backwards-compatibility.

See also now_utc().

Prototype

date now_ms() (CONST)

Example

my date $now_ms = now_ms();

Table 3.80. Arguments and Return Values for now_ms()

Argument Type	Return Type	Description
n/a	`date`	Returns the current date and time in the local time zone with resolution to the millisecond.

This function does not throw any exceptions.

3.3.40. now_us()

Synopsis

Returns the current date and time in the local time zone with resolution to the microsecond.

For similar functions returning the current date and time with coarser granularity, see now() and now_ms(). Note that there is no performance impact for using now_us() versus now() and now_ms(); now() and now_ms() are kept for backwards-compatibility.

See also now_utc().

Prototype

date now_us() (CONST)

Example

my date $now_us = now_us();

Table 3.81. Arguments and Return Values for now_us()

Argument Type	Return Type	Description
n/a	`date`	Returns the current date and time with resolution to the microsecond.

This function does not throw any exceptions.

3.3.41. now_utc()

Synopsis

Returns the current UTC date and time with resolution to the microsecond.

See also now_us() for a similar function that returns the current date and time in the local time zone.

Prototype

date now_utc() (CONST)

Example

my date $now_utc = now_utc();

Table 3.82. Arguments and Return Values for now_utc()

Argument Type	Return Type	Description
n/a	`date`	Returns the current UTC date and time with resolution to the microsecond.

This function does not throw any exceptions.

3.3.42. seconds()

Synopsis

Returns a relative date/time value in seconds to be used in date arithmetic.

Prototype

date seconds(softint) (CONST)

date seconds() (RT_NOOP)

Example

$time = now() + seconds(5 * 5); # 25 seconds from now

Table 3.83. Arguments and Return Values for seconds()

Argument Type	Return Type	Description
`softint`	`date`	Returns a relative date/time value corresponding to the number of seconds passed as an argument, to be used in date arithmetic.

This function does not throw any exceptions.

3.3.43. timegm()

Synopsis

Returns the number of seconds since January 1, 1970 00:00:00 in the local time zone for the given date.

Prototype

int timegm(date) (CONST)

nothing timegm() (RT_NOOP)

Example

$secs = timegm(2007-05-01T11:34:01);

Table 3.84. Arguments and Return Values for timegm()

Argument Type	Return Type	Description
`date`	`int`	Returns the number of seconds since January 1, 1970 00:00:00 in the local time zone for the given date.

3.3.44. years()

Synopsis

Returns a relative date/time value in years to be used in date arithmetic.

Prototype

date years(softint) (CONST)

date years() (RT_NOOP)

Example

$years = years(5 * 5); # returns 25Y

Table 3.85. Arguments and Return Values for years()

Argument Type	Return Type	Description
`int`	`date`	Returns a relative date/time value corresponding to the number of years passed as an argument, to be used in date arithmetic.

This function does not throw any exceptions.

Prev	Up	Next
3.2. Output Functions	Home	3.4. Qore Type Functions