Implement the timezone database for Linux in Kotlin

Author: dkhalanskyjb

core/build.gradle.kts

@@ -37,42 +37,44 @@ kotlin {
     explicitApi()
 
     infra {
-        // Tiers are in accordance with <https://kotlinlang.org/docs/native-target-support.html>
-        // Tier 1
-        target("linuxX64")
-        // Tier 2
-        target("linuxArm64")
+        common("nix") {
+            // Tiers are in accordance with <https://kotlinlang.org/docs/native-target-support.html>
+            common("linux") {
+                // Tier 1
+                target("linuxX64")
+                // Tier 2
+                target("linuxArm64")
+                // Tier 4 (deprecated, but still in demand)
+                target("linuxArm32Hfp")
+            }
+            // the following targets are not supported, as we don't have timezone database implementations for them:
+            /*
+            target("androidNativeArm32")
+            target("androidNativeArm64")
+            target("androidNativeX86")
+            target("androidNativeX64")
+             */
+            common("darwin") {
+                // Tier 1
+                target("macosX64")
+                target("macosArm64")
+                target("iosSimulatorArm64")
+                target("iosX64")
+                // Tier 2
+                target("watchosSimulatorArm64")
+                target("watchosX64")
+                target("watchosArm32")
+                target("watchosArm64")
+                target("tvosSimulatorArm64")
+                target("tvosX64")
+                target("tvosArm64")
+                target("iosArm64")
+                // Tier 3
+                target("watchosDeviceArm64")
+            }
+        }
         // Tier 3
         target("mingwX64")
-        // the following targets are not supported by kotlinx.serialization:
-        /*
-        target("androidNativeArm32")
-        target("androidNativeArm64")
-        target("androidNativeX86")
-        target("androidNativeX64")
-         */
-        // Tier 4 (deprecated, but still in demand)
-        target("linuxArm32Hfp")
-
-        // Darwin targets are listed separately
-        common("darwin") {
-            // Tier 1
-            target("macosX64")
-            target("macosArm64")
-            target("iosSimulatorArm64")
-            target("iosX64")
-            // Tier 2
-            target("watchosSimulatorArm64")
-            target("watchosX64")
-            target("watchosArm32")
-            target("watchosArm64")
-            target("tvosSimulatorArm64")
-            target("tvosX64")
-            target("tvosArm64")
-            target("iosArm64")
-            // Tier 3
-            target("watchosDeviceArm64")
-        }
     }
 
     jvm {
@@ -138,46 +140,37 @@ kotlin {
         compilations["test"].kotlinOptions {
             freeCompilerArgs += listOf("-trw")
         }
-        if (konanTarget.family.isAppleFamily) {
-            return@withType
-        }
-        compilations["main"].cinterops {
-            create("date") {
-                val cinteropDir = "$projectDir/native/cinterop"
-                val dateLibDir = "${project(":").projectDir}/thirdparty/date"
-                headers("$cinteropDir/public/cdate.h")
-                defFile("native/cinterop/date.def")
-                extraOpts("-Xsource-compiler-option", "-I$cinteropDir/public")
-                extraOpts("-Xsource-compiler-option", "-DONLY_C_LOCALE=1")
-                when {
-                    konanTarget.family == org.jetbrains.kotlin.konan.target.Family.LINUX -> {
-                        // needed for the date library so that it does not try to download the timezone database
-                        extraOpts("-Xsource-compiler-option", "-DUSE_OS_TZDB=1")
-                        /* using a more modern C++ version causes the date library to use features that are not
-                    * present in the currently outdated GCC root shipped with Kotlin/Native for Linux. */
-                        extraOpts("-Xsource-compiler-option", "-std=c++11")
-                        // the date library and its headers
-                        extraOpts("-Xcompile-source", "$dateLibDir/src/tz.cpp")
-                        extraOpts("-Xsource-compiler-option", "-I$dateLibDir/include")
-                        // the main source for the platform bindings.
-                        extraOpts("-Xcompile-source", "$cinteropDir/cpp/cdate.cpp")
-                    }
-                    konanTarget.family == org.jetbrains.kotlin.konan.target.Family.MINGW -> {
+        when {
+            konanTarget.family == org.jetbrains.kotlin.konan.target.Family.MINGW -> {
+                compilations["main"].cinterops {
+                    create("date") {
+                        val cinteropDir = "$projectDir/native/cinterop"
+                        val dateLibDir = "${project(":").projectDir}/thirdparty/date"
+                        headers("$cinteropDir/public/cdate.h")
+                        defFile("native/cinterop/date.def")
+                        extraOpts("-Xsource-compiler-option", "-I$cinteropDir/public")
+                        extraOpts("-Xsource-compiler-option", "-DONLY_C_LOCALE=1")
                         // needed to be able to use std::shared_mutex to implement caching.
                         extraOpts("-Xsource-compiler-option", "-std=c++17")
                         // the date library headers, needed for some pure calculations.
                         extraOpts("-Xsource-compiler-option", "-I$dateLibDir/include")
                         // the main source for the platform bindings.
                         extraOpts("-Xcompile-source", "$cinteropDir/cpp/windows.cpp")
                     }
-                    else -> {
-                        throw IllegalArgumentException("Unknown native target ${this@withType}")
-                    }
+                }
+                compilations["main"].defaultSourceSet {
+                    kotlin.srcDir("native/cinterop_actuals")
                 }
             }
-        }
-        compilations["main"].defaultSourceSet {
-            kotlin.srcDir("native/cinterop_actuals")
+            konanTarget.family == org.jetbrains.kotlin.konan.target.Family.LINUX -> {
+                // do nothing special
+            }
+            konanTarget.family.isAppleFamily -> {
+                // do nothing special
+            }
+            else -> {
+                throw IllegalArgumentException("Unknown native target ${this@withType}")
+            }
         }
     }
 
@@ -427,4 +420,4 @@ tasks.configureEach {
 with(org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsRootPlugin.apply(rootProject)) {
     nodeVersion = "21.0.0-v8-canary202309167e82ab1fa2"
     nodeDownloadBaseUrl = "https://nodejs.org/download/v8-canary"
-}
+}

core/common/src/internal/BinaryDataReader.kt

@@ -0,0 +1,51 @@
+/*
+ * Copyright 2019-2023 JetBrains s.r.o. and contributors.
+ * Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
+ */
+
+package kotlinx.datetime.internal
+
+/**
+ * A helper for reading binary data.
+ */
+internal class BinaryDataReader(private val bytes: ByteArray, private var position: Int = 0) {
+    /**
+     * Reads a byte.
+     */
+    fun readByte(): Byte = bytes[position++]
+
+    /**
+     * Reads an unsigned byte.
+     */
+    fun readUnsignedByte(): UByte =
+        readByte().toUByte()
+
+    /**
+     * Reads a big-endian (network byte order) 32-bit integer.
+     */
+    fun readInt(): Int =
+        (bytes[position].toInt() and 0xFF shl 24) or
+            (bytes[position + 1].toInt() and 0xFF shl 16) or
+            (bytes[position + 2].toInt() and 0xFF shl 8) or
+            (bytes[position + 3].toInt() and 0xFF).also { position += 4 }
+
+    /**
+     * Reads a big-endian (network byte order) 64-bit integer.
+     */
+    fun readLong(): Long =
+        (bytes[position].toLong() and 0xFF shl 56) or
+            (bytes[position + 1].toLong() and 0xFF shl 48) or
+            (bytes[position + 2].toLong() and 0xFF shl 40) or
+            (bytes[position + 3].toLong() and 0xFF shl 32) or
+            (bytes[position + 4].toLong() and 0xFF shl 24) or
+            (bytes[position + 5].toLong() and 0xFF shl 16) or
+            (bytes[position + 6].toLong() and 0xFF shl 8) or
+            (bytes[position + 7].toLong() and 0xFF).also { position += 8 }
+
+    fun readUtf8String(length: Int) =
+        bytes.decodeToString(position, position + length).also { position += length }
+
+    fun readAsciiChar(): Char = readByte().toInt().toChar()
+
+    fun skip(length: Int) { position += length }
+}

core/common/test/TimeZoneTest.kt

@@ -35,8 +35,9 @@ class TimeZoneTest {
     @Test
     fun available() {
         val allTzIds = TimeZone.availableZoneIds
-        println("Available TZs:")
-        allTzIds.forEach(::println)
+        assertContains(allTzIds, "Europe/Berlin")
+        assertContains(allTzIds, "Europe/Moscow")
+        assertContains(allTzIds, "America/New_York")
 
         assertNotEquals(0, allTzIds.size)
         assertTrue(TimeZone.currentSystemDefault().id in allTzIds)
@@ -46,7 +47,13 @@ class TimeZoneTest {
     @Test
     fun availableZonesAreAvailable() {
         for (zoneName in TimeZone.availableZoneIds) {
-            TimeZone.of(zoneName)
+            val timezone = try {
+                TimeZone.of(zoneName)
+            } catch (e: Exception) {
+                throw Exception("Zone $zoneName is not available", e)
+            }
+            Instant.DISTANT_FUTURE.toLocalDateTime(timezone).toInstant(timezone)
+            Instant.DISTANT_PAST.toLocalDateTime(timezone).toInstant(timezone)
         }
     }
 
@@ -198,6 +205,103 @@ class TimeZoneTest {
         check("-5", LocalDateTime(2008, 11, 2, 2, 0, 0, 0))
     }
 
+    @Test
+    fun checkKnownTimezoneDatabaseRecords() {
+        with(TimeZone.of("America/New_York")) {
+            checkRegular(this, LocalDateTime(2019, 3, 8, 23, 0), UtcOffset(hours = -5))
+            checkGap(this, LocalDateTime(2019, 3, 10, 2, 0))
+            checkRegular(this, LocalDateTime(2019, 6, 2, 23, 0), UtcOffset(hours = -4))
+            checkOverlap(this, LocalDateTime(2019, 11, 3, 2, 0))
+            checkRegular(this, LocalDateTime(2019, 12, 5, 23, 0), UtcOffset(hours = -5))
+        }
+        with(TimeZone.of("Europe/Berlin")) {
+            checkRegular(this, LocalDateTime(2019, 1, 31, 1, 0), UtcOffset(hours = 1))
+            checkGap(this, LocalDateTime(2019, 3, 31, 2, 0))
+            checkRegular(this, LocalDateTime(2019, 6, 27, 1, 0), UtcOffset(hours = 2))
+            checkOverlap(this, LocalDateTime(2019, 10, 27, 3, 0))
+            checkRegular(this, LocalDateTime(2019, 12, 5, 23, 0), UtcOffset(hours = 1))
+        }
+        with(TimeZone.of("Europe/Moscow")) {
+            checkRegular(this, LocalDateTime(2019, 1, 31, 1, 0), UtcOffset(hours = 3))
+            checkRegular(this, LocalDateTime(2011, 1, 31, 1, 0), UtcOffset(hours = 3))
+            checkGap(this, LocalDateTime(2011, 3, 27, 2, 0))
+            checkRegular(this, LocalDateTime(2011, 5, 3, 1, 0), UtcOffset(hours = 4))
+        }
+        with(TimeZone.of("Australia/Sydney")) {
+            checkRegular(this, LocalDateTime(2019, 1, 31, 1, 0), UtcOffset(hours = 11))
+            checkOverlap(this, LocalDateTime(2019, 4, 7, 3, 0))
+            checkRegular(this, LocalDateTime(2019, 10, 6, 1, 0), UtcOffset(hours = 10))
+            checkGap(this, LocalDateTime(2019, 10, 6, 2, 0))
+            checkRegular(this, LocalDateTime(2019, 12, 5, 23, 0), UtcOffset(hours = 11))
+        }
+    }
+
     private fun LocalDateTime(year: Int, monthNumber: Int, dayOfMonth: Int) = LocalDateTime(year, monthNumber, dayOfMonth, 0, 0)
 
 }
+
+/**
+ * [gapStart] is the first non-existent moment.
+ */
+private fun checkGap(timeZone: TimeZone, gapStart: LocalDateTime) {
+    val instant = gapStart.toInstant(timeZone)
+    /** the first [LocalDateTime] after the gap */
+    val adjusted = instant.toLocalDateTime(timeZone)
+    try {
+        // there is at least a one-second gap
+        assertNotEquals(gapStart, adjusted)
+        // the offsets before the gap are equal
+        assertEquals(
+            instant.offsetIn(timeZone),
+            instant.plus(1, DateTimeUnit.SECOND).offsetIn(timeZone))
+        // the offsets after the gap are equal
+        assertEquals(
+            instant.minus(1, DateTimeUnit.SECOND).offsetIn(timeZone),
+            instant.minus(2, DateTimeUnit.SECOND).offsetIn(timeZone)
+        )
+    } catch (e: Throwable) {
+        throw Exception("Didn't find a gap at $gapStart for $timeZone", e)
+    }
+}
+
+/**
+ * [overlapStart] is the first non-ambiguous date-time.
+ */
+private fun checkOverlap(timeZone: TimeZone, overlapStart: LocalDateTime) {
+    // the earlier occurrence of the overlap
+    val instantStart = overlapStart.plusNominalSeconds(-1).toInstant(timeZone).plus(1, DateTimeUnit.SECOND)
+    // the later occurrence of the overlap
+    val instantEnd = overlapStart.plusNominalSeconds(1).toInstant(timeZone).minus(1, DateTimeUnit.SECOND)
+    try {
+        // there is at least a one-second overlap
+        assertNotEquals(instantStart, instantEnd)
+        // the offsets before the overlap are equal
+        assertEquals(
+            instantStart.minus(1, DateTimeUnit.SECOND).offsetIn(timeZone),
+            instantStart.minus(2, DateTimeUnit.SECOND).offsetIn(timeZone)
+        )
+        // the offsets after the overlap are equal
+        assertEquals(
+            instantStart.offsetIn(timeZone),
+            instantEnd.offsetIn(timeZone)
+        )
+    } catch (e: Throwable) {
+        throw Exception("Didn't find an overlap at $overlapStart for $timeZone", e)
+    }
+}
+
+private fun checkRegular(timeZone: TimeZone, dateTime: LocalDateTime, offset: UtcOffset) {
+    val instant = dateTime.toInstant(timeZone)
+    assertEquals(offset, instant.offsetIn(timeZone))
+    try {
+        // not a gap:
+        assertEquals(dateTime, instant.toLocalDateTime(timeZone))
+        // not an overlap, or an overlap longer than one hour:
+        assertTrue(dateTime.plusNominalSeconds(3600) <= instant.plus(1, DateTimeUnit.HOUR).toLocalDateTime(timeZone))
+    } catch (e: Throwable) {
+        throw Exception("The date-time at $dateTime for $timeZone was in a gap or overlap", e)
+    }
+}
+
+private fun LocalDateTime.plusNominalSeconds(seconds: Int): LocalDateTime =
+    toInstant(UtcOffset.ZERO).plus(seconds, DateTimeUnit.SECOND).toLocalDateTime(UtcOffset.ZERO)