3.3. Date and Time Functions

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). Please note that many operating system/hardware combinbations are not capable of reporting time at this resolution; the last 3 or more digits may be zero in this case.

Usage
clock_getmicros()
Example
$time = clock_getmicros();

Table 3.38. Arguments and Return Values for clock_getmicros()

Argument Type

Return Type

Description

n/a

Integer

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

Usage
clock_getmillis()
Example
$time = clock_getmillis();

Table 3.39. Arguments and Return Values for clock_getmillis()

Argument Type

Return Type

Description

n/a

Integer

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

Usage
clock_getnanos()
Example
$time = clock_getnanos();

Table 3.40. Arguments and Return Values for clock_getnanos()

Argument Type

Return Type

Description

n/a

Integer

Returns the number of nanoseconds (1/1000000000 second) since Jan 1, 1970 00:00.


This function does not throw any exceptions.

3.3.4. date_ms()

Synopsis

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

Usage
date_ms(integer)
Example
$date = date_ms(1); # return 1970-01-01T00:00:00.001

Table 3.41. Arguments and Return Values for date_ms()

Argument Type

Return Type

Description

Integer

Date

Returns the date corresponding to the offset in ms given from January 1, 1970.


This function does not throw any exceptions.

3.3.5. days

Synopsis

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

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

Table 3.42. Arguments and Return Values for days()

Argument Type

Return Type

Description

Integer

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.6. format_date()

Synopsis

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

Usage
format_date(format_string, date_value)
Example
$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.43. 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.44. Date Format Arguments

String

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)

u

non zero-padded millisecond number (0 - 999)

uu or ms

zero-padded millisecond number (000 - 999)

P

AM or PM (upper-case)

p

am or pm (lower-case)


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

3.3.7. get_years()

Synopsis

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

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

Table 3.45. Arguments and Return Values for get_years()

Argument Type

Return Type

Description

Date

Integer

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


3.3.8. get_months()

Synopsis

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

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

Table 3.46. Arguments and Return Values for get_months()

Argument Type

Return Type

Description

Date

Integer

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


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

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

Table 3.47. Arguments and Return Values for get_days()

Argument Type

Return Type

Description

Date

Integer

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


3.3.10. get_hours()

Synopsis

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

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

Table 3.48. Arguments and Return Values for get_hours()

Argument Type

Return Type

Description

Date

Integer

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


3.3.11. get_minutes()

Synopsis

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

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

Table 3.49. Arguments and Return Values for get_minutes()

Argument Type

Return Type

Description

Date

Integer

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


3.3.12. get_seconds()

Synopsis

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

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

Table 3.50. Arguments and Return Values for get_seconds()

Argument Type

Return Type

Description

Date

Integer

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


3.3.13. get_milliseconds()

Synopsis

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

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

Table 3.51. Arguments and Return Values for get_milliseconds()

Argument Type

Return Type

Description

Date

Integer

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


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

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

Table 3.52. 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.15. 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). If the weekday is omitted, Monday (1) is assumed.

Usage
getDateFromISOWeek(integer, integer, optional:integer)
Example
$date = getDateFromISOWeek(2007, 3); # returns 2007-01-15T00:00:00.000

Table 3.53. Arguments and Return Values for getDateFromISOWeek()

Argument Type

Return Type

Description

Integer, Integer, Optional:integer

Date

Retuns an absolute date value for the ISO-8601 calendar week information passed (year, week number, optional: day)


3.3.16. getDayOfWeek()

Synopsis

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

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

Table 3.54. Arguments and Return Values for getDayOfWeek()

Argument Type

Return Type

Description

Date

Integer

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


3.3.17. getDayNumber()

Synopsis

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

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

Table 3.55. Arguments and Return Values for getDayNumber()

Argument Type

Return Type

Description

Date

Integer

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


3.3.18. getISODayOfWeek()

Synopsis

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

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

Table 3.56. Arguments and Return Values for getISODayOfWeek()

Argument Type

Return Type

Description

Date

Integer

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


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

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

Table 3.57. Arguments and Return Values for getISOWeekHash()

Argument Type

Return Type

Description

Date

Hash

Returns a hash representing the ISO-8601 calendar week information for the absolute date passed (hash keys: year, week, day)


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

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

Table 3.58. 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.21. gmtime()

Synopsis

Returns the date and time in GMT; if no argument is passed, then the current GMT time is returned. Otherwise the single argument must be an integer giving the number of seconds since Jan 1, 1970, 00:00:00.

Usage
gmtime([int_value])
Example
$date = gmtime(mktime(now())); # returns current GMT
$date = gmtime();              # also returns current GMT

Table 3.59. Arguments and Return Values for gmtime()

Argument Type

Return Type

Description

Integer

Date

The optional integer argument must be the number of seconds passed since Jan 1, 1970, 00:00:00 (see mktime() for a function that returns such a value). Qore uses the C library function gmtime() to calculate the return value, which is returned as a Qore Date type. If no argument is passed, then the current date and time in GMT are returned. If an argument is passed that is not a date/time value, then NOTHING is returned.


This function does not throw any exceptions.

3.3.22. hours()

Synopsis

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

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

Table 3.60. Arguments and Return Values for hours()

Argument Type

Return Type

Description

Integer

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.23. 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. If no argument is passed, then the current local date and time are returned.

Usage
localtime([int_value])
Example
$time = localtime(10);

Table 3.61. Arguments and Return Values for localtime()

Argument Type

Return Type

Description

Integer

Date

The optional integer argument must be the number of seconds passed since Jan 1, 1970, 00:00:00 (see mktime() for a function that returns such a value). Qore uses the C library function localtime() to calculate the return value, which is returned as a Qore Date type. If no argument is passed, then the current date and time in the current time zone are returned. If an argument is passed that is not a date/time value, then NOTHING is returned.


This function does not throw any exceptions.

3.3.24. milliseconds()

Synopsis

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

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

Table 3.62. Arguments and Return Values for milliseconds()

Argument Type

Return Type

Description

Integer

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.25. minutes()

Synopsis

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

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

Table 3.63. Arguments and Return Values for minutes()

Argument Type

Return Type

Description

Integer

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.26. mktime()

Synopsis

Returns the number of seconds of the date and time in local time passed since Jan 1, 1970, 00:00:00 GMT.

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

Synopsis

Usage

Table 3.64. Arguments and Return Values for mktime()

Argument Type

Return Type

Description

Date

Integer

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. Qore uses the C library function mktime() to return the value.


This function does not throw any exceptions.

3.3.27. months()

Synopsis

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

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

Table 3.65. Arguments and Return Values for months()

Argument Type

Return Type

Description

Integer

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.28. now()

Synopsis

Returns the current date and time with resolution to the second. For a similar function returning the current date and time with millisecond resolution, see now_ms().

Usage
now()
Example
$now = now();

Table 3.66. Arguments and Return Values for now()

Argument Type

Return Type

Description

n/a

Date

Returns the current date and time with resolution to the second.


This function does not throw any exceptions.

3.3.29. now_ms()

Synopsis

Returns the current date and time with resolution to the millisecond. For a similar function returning the current date and time with courser granularity, when resolution only to the second is needed, see now().

Usage
now_ms()
Example
$now_ms = now_ms();

Table 3.67. Arguments and Return Values for now_ms()

Argument Type

Return Type

Description

n/a

Date

Returns the current date and time with resolution to the millisecond.


This function does not throw any exceptions.

3.3.30. seconds()

Synopsis

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

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

Table 3.68. Arguments and Return Values for seconds()

Argument Type

Return Type

Description

Integer

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.31. timegm()

Synopsis

Returns the number of seconds since January 1, 1970 00:00 for a given date in GMT. The availabilty of this function depends on the system's underlying C-library; the Qore function is only available if the constant HAVE_TIMEGM is True. See Library Option Constants for a list of all option constants.

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

Table 3.69. Arguments and Return Values for timegm()

Argument Type

Return Type

Description

Date

Integer

Returns the number of seconds since January 1, 1970 00:00 for a given date in GMT.


Table 3.70. Exceptions Thrown by timegm()

err

desc

MISSING-FEATURE-ERROR

This exception is thrown when the function is not available; for maximum portability, check the constant HAVE_TIMEGM before calling this function.


3.3.32. years()

Synopsis

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

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

Table 3.71. Arguments and Return Values for years()

Argument Type

Return Type

Description

Integer

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.