How do I calculate the difference between two dates in EK9?

← Date, Time, and Duration · Ref: Q539

Subtract one temporal value from another using the - operator. The result is always a Duration.

DATE SUBTRACTION

  gap <- 2024-12-25 - 2024-01-01

The result is a Duration representing the span between the two dates. Use component accessors to extract parts:

  gap.days()    the span projected onto days
  gap.hours()   the span projected onto hours
  gap.years()   the span projected onto years

These are nominal projections: a Date - Date span is a calendar span (2024-12-25 - 2024-01-01 is P11M24D) and every month counts as 30 days, so days() gives 354 here although the real gap is 359 days (2024 is a leap year). Use them for magnitude, not as an exact day or hour count. See Q543 and Q550.

TIME SUBTRACTION

  workHours <- 17:30 - 09:00

Gives the Duration between two times on the same day.

DATETIME SUBTRACTION

  elapsed <- laterEvent - earlierEvent

Handles timezone differences automatically: the result is the actual elapsed Duration regardless of timezone.

NEGATIVE DURATIONS

If you subtract a later date from an earlier one, the result is a negative Duration:

  negative <- 2024-01-01 - 2024-12-25

Negative durations are valid and useful.

COMPONENT ACCESSORS

Duration provides .years(), .months(), .days(), .hours(), .minutes(), .seconds() to extract individual components from the total.

See Q32 for Duration basics. See Q540 for adding and subtracting time. See Q542 for comparing dates. See Q550 for calendar edge cases.

Example

defines module qa.date.difference

  defines program
    DateDifferenceDemo()
      stdout <- Stdout()

      // Date - Date gives Duration
      christmas <- 2024-12-25
      newYear <- 2024-01-01
      gap <- christmas - newYear
      stdout.println(`Days until Christmas: ${gap}`)
      stdout.println(`As days: ${gap.days()}`)

      // Time - Time gives Duration
      quittingTime <- 17:30
      startTime <- 09:00
      workDay <- quittingTime - startTime
      stdout.println(`Work day: ${workDay}`)
      stdout.println(`Work hours: ${workDay.hours()}`)

      // DateTime - DateTime gives Duration
      eventStart <- 2024-06-15T09:00:00Z
      eventEnd <- 2024-06-15T17:30:00Z
      eventLength <- eventEnd - eventStart
      stdout.println(`Event length: ${eventLength}`)

      // Negative duration when subtracting later from earlier
      backwards <- newYear - christmas
      stdout.println(`Backwards: ${backwards}`)

      // Component accessors on Duration
      longSpan <- 2026-06-15 - 2024-01-01
      stdout.println(`Years: ${longSpan.years()}`)
      stdout.println(`Months: ${longSpan.months()}`)
      stdout.println(`Days: ${longSpan.days()}`)
      stdout.println(`Hours: ${longSpan.hours()}`)
      stdout.println(`Minutes: ${longSpan.minutes()}`)
      stdout.println(`Seconds: ${longSpan.seconds()}`)

      // Cross-timezone DateTime subtraction
      nyMeeting <- 2024-06-15T09:00:00-04:00
      londonMeeting <- 2024-06-15T14:00:00+01:00
      tzGap <- londonMeeting - nyMeeting
      stdout.println(`Cross-timezone gap: ${tzGap}`)

Common mistakes

E50060 — Date has no daysBetween() method. Use the - operator to subtract dates and get a Duration, then call .days() on the result for an approximate day count (30-day months). See ek9 -h E50060 for details.

Incorrect:

gap <- christmas.daysBetween(newYear)

Correct:

gap <- christmas - newYear

Coming from another language?

Java: ChronoUnit.DAYS.between(d1, d2) or Period.between(d1, d2) separate APIs. Python: (date2 - date1).days attribute. JavaScript: manual millisecond subtraction and division. Go: t2.Sub(t1) returns time.Duration. Rust: chrono signed_duration_since(). EK9: simple date2 - date1 gives Duration, component accessors for parts.

Keywords: components, calculation, negative, time span, gap, days, time, calculate, timezone, subtract, difference, elapsed, between, date, duration