kotlinx-datetime/kotlinx.datetime.format/DateTimeComponents

DateTimeComponents

class DateTimeComponents(source)

A collection of date-time fields, used specifically for parsing and formatting.

Its main purpose is to provide support for complex date-time formats that don't correspond to any of the standard entities in the library. For example, a format that includes only the month and the day of the month, but not the year, can not be represented and parsed as a LocalDate, but it is valid for a DateTimeComponents.

Example:

val input = "2020-03-16T23:59:59.999999999+03:00"
val components = DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET.parse(input)
val localDateTime = components.toLocalDateTime() // LocalDateTime(2020, 3, 16, 23, 59, 59, 999_999_999)
val instant = components.toInstantUsingOffset() // Instant.parse("2020-03-16T20:59:59.999999999Z")
val offset = components.toUtcOffset() // UtcOffset(hours = 3)

Another purpose is to support parsing and formatting data with out-of-bounds values. For example, parsing 23:59:60 as a LocalTime is not possible, but it is possible to parse it as a DateTimeComponents, adjust the value by setting second to 59, and then convert it to a LocalTime via toLocalTime.

Example:

val input = "23:59:60"
val extraDay: Boolean
val time = DateTimeComponents.Format {
  time(LocalTime.Formats.ISO)
}.parse(input).apply {
  if (hour == 23 && minute == 59 && second == 60) {
    hour = 0; minute = 0; second = 0; extraDay = true
  } else {
    extraDay = false
  }
}.toLocalTime()

Because this class has limited applications, constructing it directly is not possible. For formatting, use the format overload that accepts a lambda with a DateTimeComponents receiver.

Example:

// Mon, 16 Mar 2020 23:59:59 +0300
DateTimeComponents.Formats.RFC_1123.format {
   setDateTimeOffset(LocalDateTime(2020, 3, 16, 23, 59, 59, 999_999_999))
   setDateTimeOffset(UtcOffset(hours = 3))
}

Accessing the fields of this class is not thread-safe. Make sure to apply proper synchronization if you are using a single instance from multiple threads.

Types

object Companion

object Formats

A collection of formats for parsing and formatting DateTimeComponents values.

Properties

var amPm: AmPmMarker?

The AM/PM state of the time component.

var dayOfMonth: Int?

The day-of-month component of the date.

var dayOfWeek: DayOfWeek?

The day-of-week component of the date.

var hour: Int?

The hour-of-day (0..23) time component.

var hourOfAmPm: Int?

The 12-hour (1..12) time component.

var minute: Int?

The minute-of-hour component.

var month: Month?

The month (Month) component of the date.

var monthNumber: Int?

The number-of-month (1..12) component of the date.

var nanosecond: Int?

The nanosecond-of-second component.

var offsetHours: Int?

The total amount of full hours in the UTC offset, in the range 0; 18.

offsetIsNegative

var offsetIsNegative: Boolean?

True if the offset is negative.

offsetMinutesOfHour

var offsetMinutesOfHour: Int?

The amount of minutes that don't add to a whole hour in the UTC offset, in the range 0; 59.

offsetSecondsOfMinute

var offsetSecondsOfMinute: Int?

The amount of seconds that don't add to a whole minute in the UTC offset, in the range 0; 59.

var second: Int?

The second-of-minute component.

var timeZoneId: String?

The timezone identifier, for example, "Europe/Berlin".

var year: Int?

The year component of the date.

Functions

fun setDate(localDate: LocalDate)

Writes the contents of the specified localDate to this DateTimeComponents. The localDate is written to the year, monthNumber, dayOfMonth, and dayOfWeek fields.

fun setDateTime(localDateTime: LocalDateTime)

Writes the contents of the specified localDateTime to this DateTimeComponents. The localDateTime is written to the year, monthNumber, dayOfMonth, dayOfWeek, hour, hourOfAmPm, amPm, minute, second and nanosecond fields.

setDateTimeOffset

fun setDateTimeOffset(instant: Instant, utcOffset: UtcOffset)

Writes the contents of the specified instant to this DateTimeComponents.

fun setDateTimeOffset(localDateTime: LocalDateTime, utcOffset: UtcOffset)

Writes the contents of the specified localDateTime and utcOffset to this DateTimeComponents.

fun setOffset(utcOffset: UtcOffset)

Writes the contents of the specified utcOffset to this DateTimeComponents. The utcOffset is written to the offsetHours, offsetMinutesOfHour, offsetSecondsOfMinute, and offsetIsNegative fields.

fun setTime(localTime: LocalTime)

Writes the contents of the specified localTime to this DateTimeComponents. The localTime is written to the hour, hourOfAmPm, amPm, minute, second and nanosecond fields.

toInstantUsingOffset

fun toInstantUsingOffset(): Instant

Builds an Instant from the fields in this DateTimeComponents.

fun toLocalDate(): LocalDate

Builds a LocalDate from the fields in this DateTimeComponents.

toLocalDateTime

fun toLocalDateTime(): LocalDateTime

Builds a LocalDateTime from the fields in this DateTimeComponents.

fun toLocalTime(): LocalTime

Builds a LocalTime from the fields in this DateTimeComponents.

fun toUtcOffset(): UtcOffset

Builds a UtcOffset from the fields in this DateTimeComponents.