Represents a date.

The Month type used in this package is an alias of Month from elm/time. To express literal values, like Jan, you must import them from Time.

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


Date.fromCalendarDate 2020 Jan 1

The Weekday type used in this package is an alias of Weekday from elm/time. To express literal values, like Mon, you must import them from Time.

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


Date.fromWeekDate 2020 1 Mon

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 calendar date: 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.

import Date exposing (fromIsoString, fromCalendarDate, fromWeekDate, fromOrdinalDate)
import Time exposing (Month(..), Weekday(..))


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

import Date exposing (fromOrdinalDate, toIsoString)


toIsoString (fromOrdinalDate 2001 1)
    == "2001-01-01"

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

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.

import Date exposing (fromOrdinalDate, format)


format "EEEE, d MMMM y" (fromOrdinalDate 1970 1)
    == "Thursday, 1 January 1970"

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" (fromOrdinalDate 1970 1)
    == "January 1st, 1970"

Functions to convert date information to strings in a custom language.

Format a date in a custom language using a string as a template.

import Date exposing (fromOrdinalDate, formatWithLanguage)


formatWithLanguage fr "EEEE, ddd MMMM y" (fromOrdinalDate 1970 1)
    == "jeudi, 1er janvier 1970"


-- assuming `fr` is a custom `Date.Language`

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

import Date exposing (Unit(..), add, fromCalendarDate)
import Time exposing (Month(..))


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 whole units, between two dates.

import Date exposing (Unit(..), diff, fromCalendarDate)
import Time exposing (Month(..))


diff Months
    (fromCalendarDate 2020 Jan 2)
    (fromCalendarDate 2020 Apr 1)
    == 2

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

import Date exposing (Interval(..), ceiling, fromCalendarDate)
import Time exposing (Month(..))


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.

import Date exposing (Interval(..), floor, fromCalendarDate)
import Time exposing (Month(..))


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.

import Date exposing (Interval(..), range, fromCalendarDate)
import Time exposing (Month(..))


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
       ]

Compare two dates. This can be used as the compare function for List.sortWith.

import Date exposing (fromOrdinal, compare)


compare (fromOrdinal 1970 1) (fromOrdinal 2038 1)
    == LT

Test if a date is within a range, inclusive of the range values.

import Date exposing (fromOrdinal, isBetween)


minimum = fromOrdinal 1970 1
maximum = fromOrdinal 2038 1


isBetween minimum maximum (fromOrdinal 1969 201)
    == False

Clamp a date within a range.

import Date exposing (fromOrdinal, clamp)


minimum = fromOrdinal 1970 1
maximum = fromOrdinal 2038 1


clamp minimum maximum (fromOrdinal 1969 201)
    == fromOrdinal 1970 1

Maps Jan–Dec to 1–12.

Maps 1–12 to Jan–Dec.

Maps Mon–Sun to 1-7.

Maps 1-7 to Mon–Sun.