ISO_DATE_TIME_OFFSET

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

For specifying the time zone offset, the format uses the UtcOffset.Formats.ISO format, except that during parsing, specifying the minutes of the offset is optional (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