DateTime module

The DateTime module

The DateTime module contains additional functions for creating and consuming date and time values.

Please note that the DateTime module is currently only available in Script Steps.

Note, also, that all the functions in the DateTime module work on textual values as well as date values explicitly created using the Date function; for instance, calling DateTime.GetYear("2018-01-01") returns the same result as calling DateTime.GetYear(Date("2018-01-01")).

IsValidDate(candidate)

Returns a Boolean value indicating whether the candidate value is a valid date (or date and time)

return DateTime.IsValidDate("hello"); 
// Return false; "hello" is not a valid date.

CreateDate(year, month, dayOfMonth)

Creates a date value with the given year, month and day of the month. The timestamp of the created value will be 00:00:00. Please note that the month and day of the month are 1-based.

return DateTime.CreateDate(2018, 03, 23);
// Returns a date value representing the 23rd of March 2018

CreateDateAndTime(year, month, dayOfMonth, hour, minute, second)

Creates a date value with the given year, month, day of the month, hour, minute and second. Please note that the month and day of the month are 1-based and that the hour argument is in 24h time.

return DateTime.CreateDateAndTime(2018, 03, 23, 11, 03, 01);
// Returns a date value representing the 23rd of Match, three minutes
// and one second past eleven.

GetYear(dateValue)

Gets the year of a date.

let d = DateTime.CreateDateAndTime(2018, 03, 23, 11, 03, 01);
return DateTime.GetYear(d);
// Returns 2018.

GetMonth(dateValue)

Gets the month of a date.

let d = DateTime.CreateDateAndTime(2018, 03, 23, 11, 03, 01);
return DateTime.GetMonth(d);
// Returns 3 (the month of March).

GetDayOfMonth(dateValue)

Gets the day of the month of a date.

let d = DateTime.CreateDateAndTime(2018, 03, 23, 11, 03, 01);
return DateTime.GetDayOfMonth(d);
// Returns 23.

GetHour(dateValue)

Gets the hour component of a date.

let d = DateTime.CreateDateAndTime(2018, 03, 23, 11, 03, 01);
return DateTime.GetHour(d);
// Returns 11.

GetMinute(dateValue)

Gets the minute of a valid date.

let d = DateTime.CreateDateAndTime(2018, 03, 23, 11, 03, 01);
return DateTime.GetMinute(d);
// Returns 3.

GetSecond(dateValue)

Gets the second of a date.

let d = DateTime.CreateDateAndTime(2018, 03, 23, 11, 03, 01);
return DateTime.GetYear(d);
// Returns 1.

DifferenceInDays(fromDate, toDate)

Returns a numeric value representing the (possibly fractional) number of days between the fromDate and toDate arguments. If toDate is earlier than fromDate, the resulting value will be negative.

let fromDate = DateTime.CreateDateAndTime(2018, 03, 23, 11, 03, 01);
let toDate = DateTime.CreateDateAndTime(2018, 03, 24, 12, 15, 00);

return DateTime.DifferenceInDays(fromDate, toDate);
// Returns 1.049988

DifferenceInSeconds(fromDate, toDate)

Returns a numeric value representing the number of seconds between the fromDate and toDate arguments. If toDate is earlier than fromDate, the resulting value will be negative.

let fromDate = DateTime.CreateDateAndTime(2018, 03, 23, 11, 03, 01);
let toDate = DateTime.CreateDateAndTime(2018, 03, 24, 12, 15, 00);

return DateTime.DifferenceInSeconds(fromDate, toDate);
// Returns 90719

SetTime(dateValue, hours, minutes, seconds)

Returns a new date value with the same year, month and day as dateValue, but with a new time as specified in the hours, minutes and seconds arguments.

let original = DateTime.CreateDate(2018, 12, 24);
return DateTime.SetTime(original, 14, 25, 00);

// Returns a date representing the 24th of December 2018, 14:25:00

AddYears(dateValue, years)

Returns a new date value with the 'year' component offset by the number of years specified in the years argument. (To subtract, specify a negative number.)

let original = DateTime.CreateDate(2018, 12, 24);
return DateTime.AddYears(original, 1);

// Returns a date representing the 24th of December 2019.

AddMonths(dateValue, months)

Returns a new date value with the 'month' component offset by the number of months specified in the months argument. (To subtract, specify a negative number.)

let original = DateTime.CreateDate(2018, 12, 24);
return DateTime.AddMonths(original, 1);

// Returns a date representing the 24th of January 2019

AddDays(dateValue, days)

Returns a new date value with the 'day' component offset by the number of days specified in the days argument. (To subtract, specify a negative number.)

let original = DateTime.CreateDate(2018, 12, 24);
return DateTime.AddDays(original, 1);

// Returns a date representing the 25th of December 2018

Note: for values which are known to be dates (i.e. created using the Date or Now functions), it is possible to use the addition (+) and subtraction (-) operators as shorthand for the AddDays function.

let original = DateTime.CreateDate(2018, 12, 24);
return original + 1;

// Returns a date representing the 25th of December 2019.

AddHours(dateValue, hours)

Returns a new date value with the 'hour' component offset by the number of hours specified in the hours argument. (To subtract, specify a negative number.)

let original = DateTime.CreateDate(2018, 12, 24);
return DateTime.AddHours(original, -1);

// Returns a date representing the 23rd of December 2018, 11 PM.

AddMinutes(dateValue, minutes)

Returns a new date value with the 'minute' component offset by the number of minutes specified in the minutes argument. (To subtract, specify a negative number.)

let original = DateTime.CreateDate(2018, 12, 24);
return DateTime.AddMinutes(original, -1);

// Returns a date representing the 23rd of December 2018, 11:59:00 PM.

AddSeconds(dateValue, seconds)

Returns a new date value with the 'second' component offset by the number of seconds specified in the seconds argument. (To subtract, specify a negative number.)

let original = DateTime.CreateDate(2018, 12, 24);
return DateTime.AddSeconds(original, -1);

// Returns a date representing the 23rd of December 2018, 11:59:59 PM.

CreateHHMMText(dateValue)

Converts a valid date value into a textual value containing the hour and minute of the day in the HH:MM format. This is the format supported by the Time input element.

let d = DateTime.CreateDateAndTime(2018, 03, 23, 11, 03, 01);
return DateTime.CreateHHMMText(d);
// Returns 11:03 as a text value.

GetHourFromHHMMText(text)

Gets the hour component from a text in the HH:MM format (as created by the Time input element).

return DateTime.GetHourFromHHMMText("13:45");
// Returns 13

GetMinuteFromHHMMText(text)

Gets the minute component from a text in the HH:MM format (as created by the Time input element).

return DateTime.GetMinuteFromHHMMText("13:45");
// Returns 45