Represents a date.
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
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
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
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
year : Date -> Basics.Int
The calendar year.
month : Date -> Month
The month as a Month
value (Jan
–Dec
).
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 (Mon
–Sun
).
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 : 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"
{ 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`
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
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
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
]
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
monthToNumber : Month -> Basics.Int
Maps Jan
–Dec
to 1–12.
numberToMonth : Basics.Int -> Month
Maps 1–12 to Jan
–Dec
.
weekdayToNumber : Weekday -> Basics.Int
Maps Mon
–Sun
to 1-7.
numberToWeekday : Basics.Int -> Weekday
Maps 1-7 to Mon
–Sun
.