kotlinx-datetime/kotlinx.datetime.format/DateTimeFormatBuilder/WithDateTimeComponents/timeZoneId

timeZoneId

A timezone identifier, either offset-based or a region-based IANA timezone ID.

Offset-based timezones:

Z or z - UTC
Optional prefix (UTC, GMT, UT) followed by offset
Offset in one of the formats: +H, +HH, +HHMM, +HHMMSS, +HH:MM, +HH:MM:SS

Region-based IANA timezone IDs: Parsed according to RFC 9557 grammar (section 4.1 of https://datatracker.ietf.org/doc/rfc9557/):

time-zone-initial = ALPHA / "." / "_"
time-zone-char    = time-zone-initial / DIGIT / "-" / "+"
time-zone-part    = time-zone-initial *time-zone-char
time-zone-name    = time-zone-part *("/" time-zone-part)

Note: This implementation doesn't follow the RFC 9557 grammar fully and allows "." and ".." as the time-zone-part.

When formatting, outputs the identifier as-is. When parsing, validates syntax only; actual timezone validation is deferred until creating a TimeZone object.

If more than one way to read a valid timezone ID matches the string, we always take the longest one.

Samples

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

fun main() { 
   //sampleStart 
   // Defining a custom format that includes a time zone ID
val format = DateTimeComponents.Format {
    dateTime(LocalDateTime.Formats.ISO)
    char('[')
    timeZoneId()
    char(']')
}
val formatted = format.format {
    setDateTime(LocalDate(2021, 1, 13).atTime(9, 34, 58, 120_000_000))
    timeZoneId = "Europe/Paris"
}
check(formatted == "2021-01-13T09:34:58.12[Europe/Paris]")
val parsed = format.parse("2021-01-13T09:34:58.12[Europe/Paris]")
check(parsed.toLocalDateTime() == LocalDate(2021, 1, 13).atTime(9, 34, 58, 120_000_000))
check(parsed.timeZoneId == "Europe/Paris") 
   //sampleEnd
}