kotlinx-datetime/kotlinx.datetime/TimeZone/Companion/of

of

actual fun of(zoneId: String): TimeZone(source)
expect fun of(zoneId: String): TimeZone(source)

Returns the time zone identified by the provided zoneId.

The supported variants of time zone identifiers:

  • Z, 'UTC', 'UT' or 'GMT' — identifies the fixed-offset time zone TimeZone.UTC,

  • a string starting with '+', '-', UTC+, UTC-, UT+, UT-, GMT+, GMT- — identifiers the time zone with the fixed offset specified after + or -,

  • all other strings are treated as region-based zone identifiers. In the IANA Time Zone Database (TZDB) which is used as the default source of time zones, these ids are usually in the form area/city, for example, Europe/Berlin or America/Los_Angeles.

It is guaranteed that passing any value from availableZoneIds to this function will return a valid time zone.

How exactly the region-based time zone is acquired is system-dependent. The current implementation:

  • JVM: java.time.ZoneId.of(zoneId) is used.

  • Kotlin/Native:

    • Darwin devices: the timezone database in /var/db/timezone/zoneinfo is used by default, and if it is not a valid timezone database, the same search procedure as on Linux is used.

    • Darwin simulators: the timezone database in /usr/share/zoneinfo.default is used by default, and if it is not a valid timezone database, the same search procedure as on Linux is used.

    • Linux: /usr/share/zoneinfo, /usr/share/lib/zoneinfo, and /etc/zoneinfo are checked in turn for the timezone database. If none of them is a valid timezone database, /etc/localtime is checked. If it is a symlink of the form .../zoneinfo/..., the target of the symlink with the last part stripped is used as the timezone database.

    • Windows: the contents of the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Time Zones registry key are queried to obtain the timezone database. Then, the Windows-specific timezone name is mapped to the corresponding IANA identifier using the information from the CLDR project: https://github.com/unicode-org/cldr/blob/main/common/supplemental/windowsZones.xml

  • JavaScript and Wasm/JS: if the @js-joda/timezone library is loaded, it is used to obtain the timezone rules. Otherwise, the IllegalTimeZoneException is thrown. See https://github.com/Kotlin/kotlinx-datetime/blob/master/README.md#note-about-time-zones-in-js

  • Wasm/WASI: if the kotlinx-datetime-zoneinfo artifact is added to the project as a dependency, it is used to obtain the timezone rules. Otherwise, the IllegalTimeZoneException is thrown.

Throws

if zoneId has an invalid format or a time-zone with the name zoneId is not found.

Samples

import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.test.*
import kotlin.time.Instant
import kotlin.time.Clock

fun main() { 
   //sampleStart 
   // Constructing a time zone using the factory function
val zone = TimeZone.of("America/New_York")
check(zone.id == "America/New_York") 
   //sampleEnd
}
actual fun of(zoneId: String): TimeZone(source)