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 59 999
-- <31 December 1999, 23:59:59.999, local time>

Out-of-range parts are clamped.

Date.fromParts 2001 Feb 29 24 60 60 1000
-- <28 February 2001, 23:59:59.999>

Convenience function for creating a Date from only the year, month, and day parts. As with fromParts, the day is clamped within the range of days in the given month.

Date.fromCalendarDate 2001 Feb 29
-- <28 February 2001>

Attempt to create a Date from a string representing a date/time in ISO 8601 format.

Date.fromIsoString "2000-01-01T00:00:00.000Z"
-- Ok <1 January 2000, UTC>


Date.fromIsoString "2000-01-01"
-- Ok <1 January 2000, local time>


Date.fromIsoString "1/1/2000"
-- Err "Invalid ISO 8601 format"

The given string must represent a valid date/time; unlike the fromParts constructor, any out-of-range parts will fail to produce a Date.

Date.fromIsoString "2001-02-29"
-- Err "Invalid calendar date"

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.

Date.fromIsoString "2000-01-01T20:00-03:00"
-- Ok <1 January 2000, 23:00, UTC>

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; 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 the 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 min max x tests if x is between min and max.

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

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

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>

Create a list of dates, at rounded intervals, increasing by a step value, between two dates. The list will start on 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 day, time of day, and time offset.

Date.fromSpec
    (calendarDate 2000 Jan 1)
    (time 20 0 0 0)
    local
-- <1 January 2000, 20:00, local time>


Date.fromSpec
    (weekDate 2009 1 Mon)
    midnight
    utc
-- <29 December 2008, UTC>


Date.fromSpec
    (ordinalDate 2016 218)
    (time 20 0 0 0)
    (offset -180)
-- <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 day.

Create a DateSpec from calendar-date parts (year, month, day).

Create a DateSpec from week-date parts (weekYear, weekNumber, weekday).

Create a DateSpec from ordinal-date parts (year, ordinalDay).

Represents a time of day.

Create a TimeSpec from time parts (hour, minute, second, millisecond).

Convenience value for time 0 0 0 0.

Represents a time offset from UTC.

Use UTC (i.e. no offset).

Use a specific offset from UTC, given in minutes.

Use the local offset.

monthToNumber Jan -- 1

Numbers outside the range [1, 12] are clamped.

numberToMonth -2 -- Jan
numberToMonth 15 -- Dec

weekdayToNumber Mon -- 1

Numbers outside the range [1, 7] are clamped.

numberToWeekday -2 -- Mon
numberToWeekday 10 -- Sun