kotlinx-datetime/kotlinx.datetime.format/DateTimeComponents

DateTimeComponents

A collection of datetime fields used specifically for parsing and formatting.

Its main purpose is to support complex datetime 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 cannot be represented and parsed as a LocalDate, but it is valid for a DateTimeComponents. See sample 1.

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. See sample 2.

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. See sample 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.

Samples

import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.test.*

fun main() { 
   //sampleStart 
   // Parsing a complex date-time string and extracting all its components
val input = "2020-03-16T23:59:59.999999999+03:00"
val components = DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET.parse(input)
check(components.toLocalDateTime() == LocalDateTime(2020, 3, 16, 23, 59, 59, 999_999_999))
check(components.toInstantUsingOffset() == Instant.parse("2020-03-16T20:59:59.999999999Z"))
check(components.toUtcOffset() == UtcOffset(3, 0)) 
   //sampleEnd
}

import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.test.*

fun main() { 
   //sampleStart 
   // Parsing an invalid input and handling the error
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()
check(time == LocalTime(0, 0))
check(extraDay) 
   //sampleEnd
}

import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.test.*

fun main() { 
   //sampleStart 
   // Formatting a multi-component date-time entity
val formatted = DateTimeComponents.Formats.RFC_1123.format {
    setDateTimeOffset(
        LocalDateTime(2020, 3, 16, 23, 59, 59, 999_999_999),
        UtcOffset(hours = 3)
    )
}
check(formatted == "Mon, 16 Mar 2020 23:59:59 +0300") 
   //sampleEnd
}