How do I extract date and time components from a DateTime in EK9?

← Date, Time, and Duration · Ref: Q554

DateTime provides accessor methods for all date and time components, plus decomposition methods for Date and Time parts.

DATE COMPONENT ACCESSORS

  dt.year() returns the year (e.g., 2024)
  dt.month() returns the month (1-12)
  dt.day() returns the day of month (1-31)
  dt.dayOfMonth() same as day()
  dt.dayOfWeek() returns day of week (1=Monday through 7=Sunday)
  dt.dayOfYear() returns day of year (1-366)

TIME COMPONENT ACCESSORS

  dt.hour() returns the hour (0-23)
  dt.minute() returns the minute (0-59)
  dt.second() returns the second (0-59)

TIMEZONE ACCESSORS

  dt.zone() returns the timezone string ('Z', '-05:00', etc.)
  dt.offSetFromUTC() returns the UTC offset as Duration

DECOMPOSITION METHODS

  dt.date() extracts the Date portion
  dt.time() extracts the Time portion

EXTRACTION OPERATORS

  #< dt extracts Date (the lower/coarser component)
  #> dt extracts Time (the upper/finer component)

DATE AND TIME ACCESSORS

Date has: year(), month(), day(), dayOfMonth(), dayOfWeek(), dayOfYear()
Time has: hour(), minute(), second()
All accessors return Integer values that are set when the source is set, and unset when the source is unset.

See Q31 for Date and Time basics. See Q92 for DateTime. See Q552 for Date-to-DateTime promotion. See Q555 for constructing from components.

Example

defines module qa.extract.components

  defines program
    ExtractComponentsDemo()
      stdout <- Stdout()

      meeting <- 2024-06-15T10:30:45Z

      // Date components
      stdout.println(`Year: ${meeting.year()}`)
      stdout.println(`Month: ${meeting.month()}`)
      stdout.println(`Day: ${meeting.day()}`)
      stdout.println(`Day of month: ${meeting.dayOfMonth()}`)
      stdout.println(`Day of week: ${meeting.dayOfWeek()}`)
      stdout.println(`Day of year: ${meeting.dayOfYear()}`)

      // Time components
      stdout.println(`Hour: ${meeting.hour()}`)
      stdout.println(`Minute: ${meeting.minute()}`)
      stdout.println(`Second: ${meeting.second()}`)

      // Timezone components
      stdout.println(`Zone: ${meeting.zone()}`)
      stdout.println(`UTC offset: ${meeting.offSetFromUTC()}`)

      // Decomposition methods
      datePart <- meeting.date()
      timePart <- meeting.time()
      stdout.println(`Date part: ${datePart}`)
      stdout.println(`Time part: ${timePart}`)

      // Extraction operators
      dateExtract <- #< meeting
      timeExtract <- #> meeting
      require datePart == dateExtract
      require timePart == timeExtract

      // Date accessors
      birthday <- 1971-02-01
      stdout.println(`Birthday year: ${birthday.year()}`)
      stdout.println(`Birthday month: ${birthday.month()}`)
      stdout.println(`Birthday day: ${birthday.day()}`)

      // Time accessors
      alarm <- 07:30:00
      stdout.println(`Alarm hour: ${alarm.hour()}`)
      stdout.println(`Alarm minute: ${alarm.minute()}`)
      stdout.println(`Alarm second: ${alarm.second()}`)

      // Unset propagation
      unsetDT <- DateTime()
      stdout.println(`Unset year isSet: ${unsetDT.year()?}`)
      stdout.println(`Unset hour isSet: ${unsetDT.hour()?}`)

Common mistakes

E50060 — DateTime has no getYear() method (that is the Java naming). EK9 uses year() without the 'get' prefix. See ek9 -h E50060 for details.

Incorrect:

stdout.println(`Year: ${meeting.getYear()}`)

Correct:

stdout.println(`Year: ${meeting.year()}`)

Other ways to ask this

How do I get the year, month, and day from a DateTime?
How do I access individual parts of a DateTime?
What accessor methods does DateTime have?

Coming from another language?

Java: getYear(), getMonthValue(), getDayOfMonth(), etc. Python: .year, .month, .day attributes. JavaScript: getFullYear(), getMonth() (0-indexed!), getDate(). Go: t.Year(), t.Month(), t.Day(). Rust: chrono year(), month(), day(). EK9: year(), month(), day(), hour(), minute(), second() methods, all 1-indexed, plus date()/time() decomposition.

Keywords: date, time, zone, accessor, hour, extract, month, component, year, day, datetime, timezone, duration, second, minute, decompose