justinmimbs / date / Date


type Date

Represents a date.


type alias Month =
Time.Month

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


type alias Weekday =
Time.Weekday

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

Create

today : Task x Date

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

fromPosix : Time.Zone -> Time.Posix -> Date

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

fromCalendarDate : Basics.Int -> Month -> Basics.Int -> Date

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

fromWeekDate : Basics.Int -> Basics.Int -> Weekday -> Date

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

fromOrdinalDate : Basics.Int -> Basics.Int -> Date

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

fromIsoString : String -> Result String Date

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

fromRataDie : Basics.Int -> Date

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

toIsoString : Date -> String

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

import Date exposing (fromOrdinalDate, toIsoString)

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

toRataDie : Date -> Basics.Int

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

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

Extract

year : Date -> Basics.Int

The calendar year.

month : Date -> Month

The month as a Month value (JanDec).

day : Date -> Basics.Int

The day of the month (1–31).

weekYear : Date -> Basics.Int

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

weekNumber : Date -> Basics.Int

The ISO week number of the year (1–53).

weekday : Date -> Weekday

The weekday as a Weekday value (MonSun).

ordinalDay : Date -> Basics.Int

The day of the year (1–366).

quarter : Date -> Basics.Int

The quarter of the year (1–4).

monthNumber : Date -> Basics.Int

The month number (1–12).

weekdayNumber : Date -> Basics.Int

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

Format

format : String -> Date -> String

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"

withOrdinalSuffix : Basics.Int -> String

Convert an integer into an English ordinal number string (like "4th").

import Date exposing (withOrdinalSuffix)

withOrdinalSuffix 21 == "21st"
withOrdinalSuffix 42 == "42nd"
withOrdinalSuffix 0 == "0th"
withOrdinalSuffix 23 == "23rd"
withOrdinalSuffix -1 == "-1st"

Custom Languages


type alias Language =
{ monthName : Month -> String
, monthNameShort : Month -> String
, weekdayName : Weekday -> String
, weekdayNameShort : Weekday -> String
, dayWithSuffix : Basics.Int -> String 
}

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

formatWithLanguage : Language -> String -> Date -> String

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`

Arithmetic


type Unit
    = Years
    | Months
    | Weeks
    | Days

add : Unit -> Basics.Int -> Date -> Date

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

diff : Unit -> Date -> Date -> Basics.Int

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

Rounding


type Interval
    = Year
    | Quarter
    | Month
    | Week
    | Monday
    | Tuesday
    | Wednesday
    | Thursday
    | Friday
    | Saturday
    | Sunday
    | Day

ceiling : Interval -> Date -> Date

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

floor : Interval -> Date -> Date

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

Lists

range : Interval -> Basics.Int -> Date -> Date -> List Date

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
       ]

Ordering

compare : Date -> Date -> Basics.Order

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

import Date exposing (fromOrdinalDate, compare)

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

isBetween : Date -> Date -> Date -> Basics.Bool

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

import Date exposing (fromOrdinalDate, isBetween)

minimum = fromOrdinalDate 1970 1
maximum = fromOrdinalDate 2038 1

isBetween minimum maximum (fromOrdinalDate 1969 201)
    == False

min : Date -> Date -> Date

Find the lesser of two dates.

import Date exposing (fromOrdinalDate, min)

min (fromOrdinalDate 1970 1) (fromOrdinalDate 2038 1)
    == (fromOrdinalDate 1970 1)

max : Date -> Date -> Date

Find the greater of two dates.

import Date exposing (fromOrdinalDate, max)

max (fromOrdinalDate 1970 1) (fromOrdinalDate 2038 1)
    == (fromOrdinalDate 2038 1)

clamp : Date -> Date -> Date -> Date

Clamp a date within a range.

import Date exposing (fromOrdinalDate, clamp)

minimum = fromOrdinalDate 1970 1
maximum = fromOrdinalDate 2038 1

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

Month and Weekday helpers

monthToNumber : Month -> Basics.Int

Maps JanDec to 1–12.

numberToMonth : Basics.Int -> Month

Maps 1–12 to JanDec.

weekdayToNumber : Weekday -> Basics.Int

Maps MonSun to 1-7.

numberToWeekday : Basics.Int -> Weekday

Maps 1-7 to MonSun.