Time.Date

Gregorian calendar dates from 0001-01-01 through 9999-12-31, independent of timezones. Construction rejects invalid fields. Month and year arithmetic clamp the day; combined periods apply months first, then days. Only construction, parsing, and movement that would leave the calendar fail.

import Time.Date as Date
import Fail
import Result exposing (Result(..))

Fail.attempt { Date.make 2026 1 31 |> Date.addMonths 1 |> Date.toIso } == Ok "2026-02-28"

Date

type DateSource

Re-exported from Time.Internal.

A calendar date. Equality and ordering compare calendar positions.

Instances:

Eq Date
Ord Date
Show Date

addDays

addDays : Int -> Date ->{Fail Error} DateSource

Moves by signed calendar days, failing with OutOfRange when the result leaves the calendar.

addMonths

addMonths : Int -> Date ->{Fail Error} DateSource

Moves by calendar months, clamping the day to the target month’s last day and failing with OutOfRange outside years 1 through 9999.

addWeeks

addWeeks : Int -> Date ->{Fail Error} DateSource

Moves by signed seven-day weeks, failing with OutOfRange.

addYears

addYears : Int -> Date ->{Fail Error} DateSource

Moves by calendar years, clamping February 29 in non-leap target years and failing with OutOfRange.

advance

advance : Period -> Date ->{Fail Error} DateSource

Applies the period’s months with clamping, followed by its days. Fails with OutOfRange.

beginningOfMonth

beginningOfMonth : Date -> DateSource

The first day of this month.

beginningOfQuarter

beginningOfQuarter : Date -> DateSource

The first day of this quarter.

beginningOfWeek

beginningOfWeek : Date -> DateSource

The Monday on or before this date. Never fails: 0001-01-01 is a Monday.

beginningOfWeekOn

beginningOfWeekOn : Weekday -> Date ->{Fail Error} DateSource

The requested weekday on or before this date, failing with OutOfRange only when that day would precede 0001-01-01.

beginningOfYear

beginningOfYear : Date -> DateSource

January 1 of this year.

components

components : Date -> (Int, Int, Int)Source

The year, month, and day, computed with Gregorian 400-year cycles.

day

day : Date -> IntSource

Day within the month, starting at 1.

daysBetween

daysBetween : Date -> Date -> IntSource

Signed day count from the first date to the second.

daysInMonth

daysInMonth : Date -> IntSource

The number of days in this date’s month.

endOfMonth

endOfMonth : Date -> DateSource

The last day of this month.

endOfQuarter

endOfQuarter : Date -> DateSource

The last day of this quarter.

endOfYear

endOfYear : Date -> DateSource

December 31 of this year.

format

format : String -> Date -> StringSource

Output formatting with %Y, %m, %d, %F, and %%. Other tokens are copied verbatim.

fromEpochDays

fromEpochDays : Int ->{Fail Error} DateSource

Constructs a date from signed days since 1970-01-01, failing with OutOfRange outside the calendar.

isLeapYear

isLeapYear : Int -> BoolSource

Whether the year is divisible by 4, except centuries not divisible by 400.

make

make : Int -> Int -> Int ->{Fail Error} DateSource

Validates a year, month, and day. Invalid days are not normalized. Fails with InvalidComponent naming the offending field.

month

month : Date -> IntSource

Calendar month, 1 through 12.

nextWeekday

nextWeekday : Weekday -> Date ->{Fail Error} DateSource

The next occurrence, strictly after this date. Fails with OutOfRange at the end of the calendar.

parse

parse : String ->{Fail Error} DateSource

Strictly parses YYYY-MM-DD, without whitespace or trailing input. Fails with InvalidText, including for a well-formed but nonexistent date.

previousWeekday

previousWeekday : Weekday -> Date ->{Fail Error} DateSource

The previous occurrence, strictly before this date. Fails with OutOfRange at the start of the calendar.

toEpochDays

toEpochDays : Date -> IntSource

Signed days since 1970-01-01.

toIso

toIso : Date -> StringSource

Canonical YYYY-MM-DD text.

weekday

weekday : Date -> WeekdaySource

This date’s ISO weekday.

weekdayNumber

weekdayNumber : Weekday -> IntSource

ISO weekday number, Monday 1 through Sunday 7.

year

year : Date -> IntSource

Calendar year, 1 through 9999.