Create a Date from the following parts, given in local time:

• year
• month
• day
• hour
• minute
• second
• millisecond

import Date exposing (Month(..))
import Date.Extra as Date

Date.fromParts 1999 Dec 31 23 59 0 0
-- <31 December 1999, 23:59, 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.

Date.fromParts 2007 Feb 29 0 0 0 0
-- <1 March 2007>

Convenience function for creating a Date from only the year, month, and day parts.

Date.fromCalendarDate 2000 Jan 1

Attempt 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"
-- Nothing

When a Date is created with a specified time 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 offset

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

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 -- True

Round 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)
-- 5

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

Create a Date from a specified time offset, 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 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 offset from UTC.

Use no offset.

Use a specific offset from UTC, given in minutes.

Use the local offset.

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