Time.Period

Calendar adjustments, not elapsed seconds. Years become months and weeks become days. Application adds months with day clamping, then adds days. Combining periods before application can differ from applying each in turn. Construction and combination are total; a component beyond 64 bits wraps like Int, and application to a date checks the calendar range instead.

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

result = Fail.attempt {
    jan = Date.make 2026 1 31
    combined = Date.advance (Period.combine (Period.months 1) (Period.months 1)) jan
    sequential = jan |> Date.addMonths 1 |> Date.addMonths 1
    (Date.toIso combined, Date.toIso sequential)
    }
result == Ok ("2026-03-31", "2026-03-28")

Period

type PeriodSource

Signed months and days. Equality compares these two components; periods have no chronological ordering without a starting date.

Instances:

Eq Period
Show Period

combine

combine : Period -> Period -> PeriodSource

Adds the components, which is not sequential application.

days

days : Int -> PeriodSource

An adjustment by calendar days, which need not last 24 hours.

months

months : Int -> PeriodSource

An adjustment by calendar months.

negate

negate : Period -> PeriodSource

Negates both components.

totalDays

totalDays : Period -> IntSource

The signed day component.

totalMonths

totalMonths : Period -> IntSource

The signed month component.

weeks

weeks : Int -> PeriodSource

An adjustment by seven-day calendar weeks.

years

years : Int -> PeriodSource

An adjustment by calendar years, stored as twelve months each.

zero

zero : PeriodSource

An adjustment that leaves a value unchanged.