Represents a date in an idealized calendar.

Get the current local date. See this page for a full example.

Create a date from a time Zone and a Posix time. This conversion loses the time information associated with the Posix value.

import Date exposing (fromCalendarDate, fromPosix)
import Time exposing (millisToPosix, utc, Month(..))


fromPosix utc (millisToPosix 0)
    == fromCalendarDate 1970 Jan 1

Create a date from a year, month, and day of the month. Out-of-range day values will be clamped.

import Date exposing (fromCalendarDate)
import Time exposing (Month(..))


fromCalendarDate 2018 Sep 26

Create a date from an ISO week date: a week-numbering year, week number, and weekday. Out-of-range week number values will be clamped.

import Date exposing (fromWeekDate)
import Time exposing (Weekday(..))


fromWeekDate 2018 39 Wed

Create a date from an ordinal date: a year and day of the year. Out-of-range day values will be clamped.

import Date exposing (fromOrdinalDate)


fromOrdinalDate 2018 269

Attempt to create a date from a string in ISO 8601 format. Calendar dates, week dates, and ordinal dates are all supported in extended and basic format.

-- calendar date
fromIsoString "2018-09-26"
    == Ok (fromCalendarDate 2018 Sep 26)




-- week date
fromIsoString "2018-W39-3"
    == Ok (fromWeekDate 2018 39 Wed)




-- ordinal date
fromIsoString "2018-269"
    == Ok (fromOrdinalDate 2018 269)

The string must represent a valid date; unlike fromCalendarDate and friends, any out-of-range values will fail to produce a date.

fromIsoString "2018-02-29"
    == Err "Invalid calendar date (2018, 2, 29)"

Rata Die is a system for assigning numbers to calendar days, where the number 1 represents the date 1 January 0001.

You can losslessly convert a Date to and from an Int representing the date in Rata Die. This makes it a convenient representation for transporting dates or using them as comparables. For all date values:

(date |> toRataDie |> fromRataDie)
    == date

Convert a date to a string in ISO 8601 extended format.

toIsoString (fromCalendarDate 2007 Mar 15)
    == "2007-03-15"

Convert a date to its number representation in Rata Die (see fromRataDie). For all date values:

(date |> toRataDie |> fromRataDie)
    == date

The calendar year.

The month as a Month value (Jan–Dec).

The day of the month (1–31).

The ISO week-numbering year. This is not always the same as the calendar year.

The ISO week number of the year (1–53). Most week years have 52 weeks; some have 53.

The weekday as a Weekday value (Mon–Sun).

The day of the year (1–366).

The quarter of the year (1–4).

The month number (1–12).

The weekday number (1–7), beginning with Monday.

Format a date using a string as a template.

format "EEEE, MMMM d, y" (fromCalendarDate 2007 Mar 15)
    == "Thursday, March 15, 2007"

Alphabetic characters in the template represent date information; the number of times a character is repeated specifies the form of a name (e.g. "Tue", "Tuesday") or the padding of a number (e.g. "1", "01").

Alphabetic characters can be escaped within single-quotes; a single-quote can be escaped as a sequence of two single-quotes, whether appearing inside or outside an escaped sequence.

Templates 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 (number or name)


"w" -- week number


"d" -- day


"D" -- ordinal day


"E" -- weekday name


"e" -- weekday number

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.

format "MMMM ddd, y" (fromCalendarDate 2007 Mar 15)
    == "March 15th, 2007"

Get a past or future date by adding some number of units to a date.

add Weeks -2 (fromCalendarDate 2018 Sep 26)
    == fromCalendarDate 2018 Sep 12

When adding Years or Months, day values are clamped to the end of the month if necessary.

add Months 1 (fromCalendarDate 2000 Jan 31)
    == fromCalendarDate 2000 Feb 29

Get the difference, as a number of some units, between two dates.

diff Months (fromCalendarDate 2007 Mar 15) (fromCalendarDate 2007 Sep 1)
    == 5

Round up a date to the beginning of the closest interval. The resulting date will be greater than or equal to the one provided.

ceiling Tuesday (fromCalendarDate 2018 May 11)
    == fromCalendarDate 2018 May 15

Round down a date to the beginning of the closest interval. The resulting date will be less than or equal to the one provided.

floor Tuesday (fromCalendarDate 2018 May 11)
    == fromCalendarDate 2018 May 8

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.

start =
    fromCalendarDate 2018 May 8


until =
    fromCalendarDate 2018 May 14


range Day 2 start until
    == [ fromCalendarDate 2018 May 8
       , fromCalendarDate 2018 May 10
       , fromCalendarDate 2018 May 12
       ]

Maps Jan–Dec to 1–12.

Maps 1–12 to Jan–Dec.

Maps Mon–Sun to 1-7.

Maps 1-7 to Mon–Sun.