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
Last updated
Was this helpful?