kotlinx-datetime/kotlinx.datetime.format/DateTimeComponents/Formats/ISO_DATE_TIME_OFFSET

ISO_DATE_TIME_OFFSET

val ISO_DATE_TIME_OFFSET: DateTimeFormat<DateTimeComponents>(source)

ISO 8601 extended format for dates and times with UTC offset.

The format uses the UtcOffset.Formats.ISO format to specify the time zone offset, except that specifying the minutes of the offset is optional during parsing (so offsets like +03 are also allowed).

This format differs from LocalTime.Formats.ISO in its time part in that specifying the seconds is not optional.

Examples of instants in the ISO 8601 format:

2020-08-30T18:43:00Z
2020-08-30T18:43:00.50Z
2020-08-30T18:43:00.123456789Z
2020-08-30T18:40:00+03:00
2020-08-30T18:40:00+03:30:20

2020-01-01T23:59:59.123456789+01
+12020-01-31T23:59:59Z

This format uses the local date, local time, and UTC offset fields of DateTimeComponents.

See ISO-8601-1:2019, 5.4.2.1b), excluding the format without the offset.

Guaranteed to parse all strings that Instant.toString produces.

Typically, to use this format, you can simply call Instant.toString and Instant.parse. However, by accessing this format directly, you can obtain the UTC offset, which is not returned from Instant.parse, or specify the UTC offset to be formatted.

val components = DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET.parse("2020-08-30T18:43:00.123456789+03:00")
val instant = components.toInstantUsingOffset() // 2020-08-30T15:43:00.123456789Z
val localDateTime = components.toLocalDateTime() // 2020-08-30T18:43:00.123456789
val offset = components.toUtcOffset() // UtcOffset(hours = 3)

Samples

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

fun main() { 
   //sampleStart 
   // Using the ISO format for dates, times, and offsets combined
val formatted = DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET.format {
    setDate(LocalDate(2023, 1, 2))
    setTime(LocalTime(3, 46, 58, 530_000_000))
    setOffset(UtcOffset(3, 30))
}
check(formatted == "2023-01-02T03:46:58.53+03:30")
val parsed = DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET.parse("2023-01-02T03:46:58.53+03:30")
check(parsed.toLocalDate() == LocalDate(2023, 1, 2))
check(parsed.toLocalTime() == LocalTime(3, 46, 58, 530_000_000))
check(parsed.toUtcOffset() == UtcOffset(3, 30)) 
   //sampleEnd
}