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() gives the total days
  gap.hours() gives the total hours
  gap.years() gives the approximate years (30-day months)

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 the day count. See ek9 -h E50060 for details.

Incorrect:

gap <- christmas.daysBetween(newYear)

Correct:

gap <- christmas - newYear

Other ways to ask this

How do I find the number of days between two dates?
How does date subtraction work in EK9?
How do I get a Duration from two dates?
How do I do date calculations in EK9?

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: duration, negative, time, between, days, components, difference, elapsed, timezone, date, calculation, subtract, calculate, gap