Date and Time Functions

Date(year?, month = 1, day = 1, hour = 0, minute = 0, second = 0, fromTimeZone?) : DateTime

Returns current date (if no arguments), or specific date (3 arguments), or specific date and time in UTC.

Date Parameters

year? : Integer

month : Integer = 1

day : Integer = 1

hour : Integer = 0

minute : Integer = 0

second : Integer = 0

fromTimeZone? : TimeZone?
Time zone to convert from to UTC.
Can be ‘user’ to use current user’s time zone.
Can be integer number to find time zone by minutes offset.
Can be textual time zone ID to find by ID (see TimeZones function).

Date Examples

var now = Date();

var dt = Date(2024, 3, 18); // returns Date object without time part

var dt = Date(2024, 3, 18, 10, 0, 0); // returns DateTime object in UTC time zone

var dt = Date(2024, 3, 18, 4, 0, 0, 'Central Standard Time'); // converts time from CST to UTC

var dt = dateTimeObject.Date(); // special case to get date part from DateTime object

DateAdd(date, add1?, …) : DateTime

Adds/subtracts time span to/from specified date and returns new DateTime object.

DateAdd Parameters

date : DateTime

add1? : String
Should be ‘y’ or ‘m’ followed by integer number to add years or months respectively.
Should be ‘d’, ‘h’, ‘mm’ or ‘s’ followed by floating point number to add days, hours, minutes or seconds respectively.

…? : ?

DateAdd Examples

var dt = Date().DateAdd('y1'); // adds one year

var dt = Date().DateAdd('m-5'); // subtracts 5 months

var dt = Date().DateAdd('mm+10'); // adds 10 minutes

var dt = Date().DateAdd('d+0.5'); // adds half a day (12 hours)

var dt = Date().DateAdd('y1', 'm1'); // adds one year and one month

DaysInMonth(year, month) : Integer

Returns number of days in specified month.

DaysInMonth Parameters

year : Integer

month : Integer

DaysInMonth Examples

var ok = DaysInMonth(2024, 2) == 29;

var ok = DaysInMonth(2023, 2) == 28;

Duration(seconds, minutes = 0, hours = 0, days = 0) : Duration

Creates duration object (time span).

Duration Parameters

seconds : Integer

minutes : Integer = 0

hours : Integer = 0

days : Integer = 0

Duration Examples

var ts = Duration(30); // 30 seconds

var ts = Duration(0, 30); // 30 minutes

var ts = Duration(0, 0, 30); // 30 hours

var ts = Duration(0, 0, 0, 30); // 30 days

FromTimeZone(value, timeZone) : DateTime

Converts DateTime from specified time zone to UTC.

FromTimeZone Parameters

value : DateTime

timeZone : TimeZone?
Can be ‘user’ to use current user’s time zone.
Can be integer number to find time zone by minutes offset.
Can be textual time zone ID to find by ID (see TimeZones function).
Can be null to return new DateTime object in UTC time zone ignoring original time zone.

FromTimeZone Examples

var dt = Date().FromTimeZone('user'); // converts from user's time zone to UTC.

var dt = Date().FromTimeZone(-300); // converts from UTC-5 to UTC.

var dt = Date().FromTimeZone('Central Standard Time'); // converts from CST to UTC.

var dt = dateTimeObject.FromTimeZone(null); // ignores original time zone and interprets it in UTC.

IsLeapYear(year) : Boolean

Checks if the specified year is a leap year.

IsLeapYear Parameters

year : Integer

IsLeapYear Examples

var ok = IsLeapYear(2024) == true;

var ok = IsLeapYear(2023) == false;

TestDate(value, callback) : DateTime

Call the callback function with the specified date set to be current (so Date() returns the specified date instead of current one).
Returns the value returned by the callback

TestDate Parameters

value : DateTime

callback : Function

TestDate Examples

var dt = Date(2024, 3, 18, 11, 0, 0);
var ok = TestDate(dt, () => Date()) == dt;

Time(hour, minute = 0, second = 0, millisecond = 0) : Time

Returns specific time of day.

Time Parameters

hour : Integer

minute : Integer = 0

second : Integer = 0

millisecond : Integer = 0

Time Examples

var tm = Time(3); // returns Time object of 3:00am

var tm = Time(15, 30, 0); // returns Time object of 3:30pm

var tm = Date().Time(); // special case to get time part from DateTime object

TimeZone(id) : TimeZone

Returns time zone by its ID.

TimeZone Parameters

id : String
Can be ‘utc’ or empty to get UTC time zone.
Can be ‘user’ to get current user’s time zone.
Can be integer number to find time zone by minutes offset.
Can be textual time zone ID to find by ID (see TimeZones function).

TimeZone Examples

var ok = TimeZone('').Id == 'UTC';

var ok = TimeZone('utc').Id == 'UTC';

var ok = TimeZone(-360).Abbreviation == 'CST';

var ok = TimeZone('Central America Standard Time').Abbreviation == 'CST';

TimeZoneAbbr(id, daylight?) : String?

Returns time zone abbreviation.

TimeZoneAbbr Parameters

id : String
Can be empty, ‘utc’, ‘user’ or integer offset in minutes (1st match is this case).

daylight? : ?
Boolean to indicate daylight, Date to test for the daylight (if timezone supports it).

TimeZones() : TimeZone[]

Returns array of all supported time zones.

ToDate(value) : Date

Converts value to Date if possible.

ToDate Parameters

value : ?

ToDate Examples

var ok = ToDate('2024-03-18') == Date(2024, 3, 18);

var ok = ToDate('2024/03/18') == Date(2024, 3, 18);

var ok = Date().ToDate() == Date().Date();

ToDateTime(value) : DateTime

Converts value to DateTime if possible.

ToDateTime Parameters

value : ?

ToDateTime Examples

var ok = ToDateTime('2024-03-18') == Date(2024, 3, 18, 0, 0, 0);

var ok = ToDateTime('2024-03-18 3:00') == Date(2024, 3, 18, 3, 0, 0);

var ok = ToDateTime('2024-03-18 3:00am') == Date(2024, 3, 18, 3, 0, 0);

var ok = ToDateTime('2024-03-18 3:00pm') == Date(2024, 3, 18, 15, 0, 0);

TotalDays(fromDate, toDate) : Float

Calculates difference between two dates in days (can be negative).

TotalDays Parameters

fromDate : DateTime

toDate : DateTime

TotalDays Examples

var ok = TotalDays('2024-03-18', '2024-03-20') == 2;

var ok = TotalDays(Date(), Date().DateAdd('h24')) == 1;

var ok = TotalDays('2024-03-20', '2024-03-18') == -2;

ToTime(value) : Time

Converts value to Time if possible.

ToTime Parameters

value : ?

ToTime Examples

var ok = ToTime('3:00') == Time(3, 0, 0);

var ok = ToTime(3.5) == Time(3, 30);

var ok = Duration(0, 30, 3).ToTime() == Time(3, 30);

ToTimeZone(value, timeZone) : DateTime

Converts DateTime from UTC to specified time zone.

ToTimeZone Parameters

value : DateTime

timeZone : TimeZone?
Can be ‘user’ to use current user’s time zone.
Can be integer number to find time zone by minutes offset.
Can be textual time zone ID to find by ID (see TimeZones function).

ToTimeZone Examples

var dt = Date().ToTimeZone('user'); // converts from UTC to user's time zone.

var dt = Date().ToTimeZone(-300); // converts from UTC to UTC-5.

var dt = Date().ToTimeZone('Central Standard Time'); // converts from UTC to CST.