A Date represents a moment in time, encoded by two essential pieces of
information: the number of milliseconds since 1 January 1970 UTC, and the
offset between UTC and the current machine's local time. Extractions of a
Date (e.g. Date.month, Date.hour) return representations of the date in
local time, while Date.toTime returns the UTC representation.
Convenience function for creating a Date from only the year, month, and
day parts.
Date.fromCalendarDate 2000 Jan 1Attempt to create a Date from a string representing a date in
ISO 8601 format.
Date.fromIsoString "2000-01-01"
-- Just <1 January 2000, local time>
Date.fromIsoString "2009-W01-1T00Z"
-- Just <29 December 2008, UTC>
Date.fromIsoString "2016-218T20:00-03:00"
-- Just <5 August 2016, 23:00, UTC>
Date.fromIsoString "1/1/2000"
-- NothingWhen a Date is created with a specified time zone offset (e.g. "-03:00"),
its extractions still reflect the current machine's local time, and
Date.toTime still reflects its UTC time.
Convert a date to a string using a pattern as a template.
Date.toFormattedString
"EEEE, MMMM d, y 'at' h:mm a"
(Date.fromParts 2007 Mar 15 13 45 56 67)
-- "Thursday, March 15, 2007 at 1:45 PM"Each alphabetic character in the pattern represents date or time information; the number of times a character is repeated specifies the form of the name to use (e.g. "Tue", "Tuesday") or the padding of numbers (e.g. "1", "01"). Formatting characters are escaped within single-quotes, and a single-quote is escaped as a sequence of two single-quotes, whether appearing inside or outside an escaped sequence.
Patterns are based on Date Format Patterns in Unicode Technical Standard #35. Only the following subset of formatting characters are available:
"y" -- year
"Y" -- week-numbering year
"Q" -- quarter
"M" -- month
"w" -- week number
"d" -- day
"D" -- ordinal day
"E" -- day of week
"e" -- weekday number / day of week
"a" -- day period (AM, PM)
"b" -- day period (am, pm, noon, midnight)
"h" -- hour (12-hour clock)
"H" -- hour (24-hour clock)
"m" -- minute
"s" -- second
"S" -- fractional second
"X" -- time offset, using "Z" when offset is 0
"x" -- time offsetThe non-standard pattern field "ddd" is available to indicate the day of the month with an ordinal suffix (e.g. "1st", "15th"), as the current standard does not include such a field.
Date.toFormattedString
"MMMM ddd, y"
(Date.fromParts 2007 Mar 15 13 45 56 67)
-- "March 15th, 2007"Convert a date to a string just like toFormattedString, but using the UTC
representation instead of the local representation of the date.
Convenience function for formatting a date to ISO 8601 (extended date and time format with local time offset).
Date.toIsoString (Date.fromParts 2007 Mar 15 13 45 56 67)
-- "2007-03-15T13:45:56.067-04:00"
-- (example has a local offset of UTC-04:00)Convenience function for formatting a date, in UTC representation, to ISO 8601 (extended date and time format with "Z" for time offset).
Date.toUtcIsoString (Date.fromParts 2007 Mar 15 13 45 56 67)
-- "2007-03-15T17:45:56.067Z"
-- (example has a local offset of UTC-04:00)Test equality of two dates.
Compare two dates. This can be used as the compare function for
List.sortWith.
Test if a date is within a given range, inclusive of the range values. The
expression Date.isBetween a b x tests if x is between a and b.
Clamp a date within a given range. The expression Date.clamp min max x
returns one of min, max, or x, ensuring the returned date is not before
min and not after max.
These functions work on dates within the context of a given interval of time.
Represents an interval of time.
Test if two dates fall within the same interval.
dec31 = Date.fromCalendarDate 1999 Dec 31
jan1 = Date.fromCalendarDate 2000 Jan 1
Date.equalBy Month dec31 jan1 -- False
Date.equalBy Week dec31 jan1 -- TrueRound down a date to the beginning of the closest interval. The resulting date will be less than or equal to the one provided.
Date.floor Hour (Date.fromParts 1999 Dec 31 23 59 59 999)
-- <31 December 1999, 23:00>Round up a date to the beginning of the closest interval. The resulting date will be greater than or equal to the one provided.
Date.ceiling Monday (Date.fromParts 1999 Dec 31 23 59 59 999)
-- <3 January 2000>Add a number of whole intervals to a date.
Date.add Week 2 (Date.fromParts 2007 Mar 15 11 55 0 0)
-- <29 March 2007, 11:55>When adding Month, Quarter, or Year intervals, day values are clamped at the end of the month if necessary.
Date.add Month 1 (Date.fromParts 2000 Jan 31 0 0 0 0)
-- <29 February 2000>Find the difference, as a number of whole intervals, between two dates.
Date.diff Month
(Date.fromParts 2007 Mar 15 11 55 0 0)
(Date.fromParts 2007 Sep 1 0 0 0 0)
-- 5Create a list of dates, at rounded intervals, increasing by a step value, between two dates. The list will start at or after the first date, and end before the second date.
Date.range Day 2
(Date.fromParts 2007 Mar 15 11 55 0 0)
(Date.fromParts 2007 Mar 22 0 0 0 0)
-- [<16 March 2007>, <18 March 2007>, <20 March 2007>]Extract the month number of a date. Given the date 23 June 1990 at 11:45 a.m. this returns the integer 6.
Extract the quarter of a date. Given the date 23 June 1990 at 11:45 a.m. this returns the integer 2.
Extract the ordinal day of a date. Given the date 23 June 1990 at 11:45 a.m. this returns the integer 174.
Extract the fractional day of a date. Given the date 23 June 1990 at 11:45 a.m. this returns the float 0.4895833333333333.
Extract the weekday number (beginning at 1 for Monday) of a date. Given the date 23 June 1990 at 11:45 a.m. this returns the integer 6.
Extract the week number of a date. Given the date 23 June 1990 at 11:45 a.m. this returns the integer 25.
Extract the week-numbering year of a date. Given the date 23 June 1990 at 11:45 a.m. this returns the integer 1990.
Extract the local offset from UTC time, in minutes, of a date. Given a date with a local offset of UTC-05:00 this returns the integer -300.
In some cases you may want to specify a date with a time zone offset or from
week-date or ordinal-date parts. The fromSpec function provides a way to
do this.
Create a Date from a specified time zone, time of day, and day.
Date.fromSpec
local
noTime
(calendarDate 2000 Jan 1)
-- <1 January 2000, local time>
Date.fromSpec
utc
noTime
(weekDate 2009 1 1)
-- <29 December 2008, UTC>
Date.fromSpec
(offset -180)
(atTime 20 0 0 0)
(ordinalDate 2016 218)
-- <5 August 2016, 23:00, UTC>When a Date is created with a specified time zone offset (e.g. offset -180),
its extractions still reflect the current machine's local time, and
Date.toTime still reflects its UTC time.
Represents a time zone.
UTC time zone.
Create a TimeZone with a specific offset from UTC time, given in minutes.
Do not specify a time zone, but use the local offset instead.
Represents a time of day.
Do not specify a time of day (default to 00:00).
Create a TimeSpec from time parts (hour, minute, second, millisecond).
Represents a day.
Create a DateSpec from calendar-date parts (year, month, day).
Create a DateSpec from week-date parts (weekYear, weekNumber, weekdayNumber).
Create a DateSpec from ordinal-date parts (year, ordinalDay).
Create a
Datefrom the following parts, given in local time:The values of the parts are not checked to ensure a valid date representation, nor are they clamped to a valid range; instead, providing values outside a valid range results in underflow or overflow.