Clearly define the internal API for platform definitions

Author: dkhalanskyjb

core/darwin/src/TimeZoneNative.kt

@@ -1,8 +1,75 @@
 /*
- * Copyright 2019-2024 JetBrains s.r.o. and contributors.
+ * Copyright 2019-2020 JetBrains s.r.o.
  * Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
  */
 
+@file:OptIn(ExperimentalForeignApi::class)
 package kotlinx.datetime.internal
 
+import kotlinx.cinterop.*
+import kotlinx.datetime.Instant
+import kotlinx.datetime.toKotlinInstant
+import kotlinx.datetime.internal.*
+import platform.Foundation.*
+
+internal actual val systemTzdb: TimeZoneDatabase get() = tzdbOnFilesystem
+
+internal actual fun currentSystemDefaultZone(): Pair<String, TimeZoneRules?> {
+    /* The framework has its own cache of the system timezone. Calls to
+    [NSTimeZone systemTimeZone] do not reflect changes to the system timezone
+    and instead just return the cached value. Thus, to acquire the current
+    system timezone, first, the cache should be cleared.
+
+    This solution is not without flaws, however. In particular, resetting the
+    system timezone also resets the default timezone ([NSTimeZone default]) if
+    it's the same as the cached system timezone:
+
+        NSTimeZone.defaultTimeZone = [NSTimeZone
+            timeZoneWithName: [[NSTimeZone systemTimeZone] name]];
+        NSLog(@"%@", NSTimeZone.defaultTimeZone.name);
+        NSLog(@"Change the system time zone, then press Enter");
+        getchar();
+        [NSTimeZone resetSystemTimeZone];
+        NSLog(@"%@", NSTimeZone.defaultTimeZone.name); // will also change
+
+    This is a fairly marginal problem:
+        * It is only a problem when the developer deliberately sets the default
+          timezone to the region that just happens to be the one that the user
+          is in, and then the user moves to another region, and the app also
+          uses the system timezone.
+        * Since iOS 11, the significance of the default timezone has been
+          de-emphasized. In particular, it is not included in the API for
+          Swift: https://forums.swift.org/t/autoupdating-type-properties/4608/4
+
+    Another possible solution could involve using [NSTimeZone localTimeZone].
+    This is documented to reflect the current, uncached system timezone on
+    iOS 11 and later:
+    https://developer.apple.com/documentation/foundation/nstimezone/1387209-localtimezone
+    However:
+        * Before iOS 11, this was the same as the default timezone and did not
+          reflect the system timezone.
+        * Worse, on a Mac (10.15.5), I failed to get it to work as documented.
+              NSLog(@"%@", NSTimeZone.localTimeZone.name);
+              NSLog(@"Change the system time zone, then press Enter");
+              getchar();
+              // [NSTimeZone resetSystemTimeZone]; // uncomment to make it work
+              NSLog(@"%@", NSTimeZone.localTimeZone.name);
+          The printed strings are the same even if I wait for good 10 minutes
+          before pressing Enter, unless the line with "reset" is uncommented--
+          then the timezone is updated, as it should be. So, for some reason,
+          NSTimeZone.localTimeZone, too, is cached.
+          With no iOS device to test this on, it doesn't seem worth the effort
+          to avoid just resetting the system timezone due to one edge case
+          that's hard to avoid.
+    */
+    NSTimeZone.resetSystemTimeZone()
+    val zone = NSTimeZone.systemTimeZone
+    val zoneId = zone.name
+    return zoneId to null
+}
+
+internal actual fun currentTime(): Instant = NSDate.date().toKotlinInstant()
+
+private val tzdbOnFilesystem = TzdbOnFilesystem(Path.fromString(defaultTzdbPath()))
+
 internal expect fun defaultTzdbPath(): String

core/darwin/src/internal/TimeZoneNative.kt

@@ -4,25 +4,18 @@
  */
 
 @file:OptIn(ExperimentalForeignApi::class)
-package kotlinx.datetime
+package kotlinx.datetime.internal
 
 import kotlinx.cinterop.*
-import kotlinx.datetime.internal.*
+import kotlinx.datetime.Instant
 import platform.posix.*
 
-internal actual class TimeZoneDatabase {
-    actual companion object {
-        actual fun rulesForId(id: String): TimeZoneRules = tzdbOnFilesystem.rulesForId(id)
+internal actual val systemTzdb: TimeZoneDatabase get() = tzdbOnFilesystem
 
-        actual fun currentSystemDefault(): Pair<String, TimeZoneRules?> {
-            val zoneId = tzdbOnFilesystem.currentSystemDefault()?.second?.toString()
-                ?: throw IllegalStateException("Failed to get the system timezone")
-            return zoneId to null
-        }
-
-        actual val availableZoneIds: Set<String>
-            get() = tzdbOnFilesystem.availableTimeZoneIds()
-    }
+internal actual fun currentSystemDefaultZone(): Pair<String, TimeZoneRules?> {
+    val zoneId = tzdbOnFilesystem.currentSystemDefault()?.second?.toString()
+        ?: throw IllegalStateException("Failed to get the system timezone")
+    return zoneId to null
 }
 
 @OptIn(UnsafeNumber::class)
@@ -43,4 +36,4 @@ internal actual fun currentTime(): Instant = memScoped {
     }
 }
 
-private val tzdbOnFilesystem = TzdbOnFilesystem(Path.fromString("/usr/share/zoneinfo"))
+private val tzdbOnFilesystem: TzdbOnFilesystem = TzdbOnFilesystem(Path.fromString("/usr/share/zoneinfo"))

core/linux/src/TimeZoneNative.kt renamed to core/linux/src/internal/TimeZoneNative.kt

@@ -127,8 +127,6 @@ private const val MAX_SECOND = 31494816403199L // +1000000-12-31T23:59:59
 
 private fun isValidInstantSecond(second: Long) = second >= MIN_SECOND && second <= MAX_SECOND
 
-internal expect fun currentTime(): Instant
-
 @Serializable(with = InstantIso8601Serializer::class)
 public actual class Instant internal constructor(public actual val epochSeconds: Long, public actual val nanosecondsOfSecond: Int) : Comparable<Instant> {
 

core/native/src/Instant.kt

@@ -19,7 +19,7 @@ public actual open class TimeZone internal constructor() {
 
         public actual fun currentSystemDefault(): TimeZone {
             // TODO: probably check if currentSystemDefault name is parseable as FixedOffsetTimeZone?
-            val (name, rules) = TimeZoneDatabase.currentSystemDefault()
+            val (name, rules) = currentSystemDefaultZone()
             return if (rules == null) {
                 of(name)
             } else {
@@ -66,14 +66,14 @@ public actual open class TimeZone internal constructor() {
                 throw IllegalTimeZoneException(e)
             }
             return try {
-                RegionTimeZone(TimeZoneDatabase.rulesForId(zoneId), zoneId)
+                RegionTimeZone(systemTzdb.rulesForId(zoneId), zoneId)
             } catch (e: Exception) {
                 throw IllegalTimeZoneException("Invalid zone ID: $zoneId", e)
             }
         }
 
         public actual val availableZoneIds: Set<String>
-            get() = TimeZoneDatabase.availableZoneIds
+            get() = systemTzdb.availableTimeZoneIds()
     }
 
     public actual open val id: String
@@ -105,15 +105,6 @@ public actual open class TimeZone internal constructor() {
     override fun toString(): String = id
 }
 
-internal expect class TimeZoneDatabase {
-    companion object {
-        fun rulesForId(id: String): TimeZoneRules
-        fun currentSystemDefault(): Pair<String, TimeZoneRules?>
-        val availableZoneIds: Set<String>
-    }
-}
-
-
 @Serializable(with = FixedOffsetTimeZoneSerializer::class)
 public actual class FixedOffsetTimeZone internal constructor(public actual val offset: UtcOffset, override val id: String) : TimeZone() {
 

core/native/src/TimeZone.kt

@@ -0,0 +1,11 @@
+/*
+ * Copyright 2019-2024 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
+
+internal interface TimeZoneDatabase {
+    fun rulesForId(id: String): TimeZoneRules
+    fun availableTimeZoneIds(): Set<String>
+}

core/native/src/internal/TimeZoneDatabase.kt

@@ -0,0 +1,14 @@
+/*
+ * Copyright 2019-2024 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
+
+import kotlinx.datetime.*
+
+internal expect val systemTzdb: TimeZoneDatabase
+
+internal expect fun currentSystemDefaultZone(): Pair<String, TimeZoneRules?>
+
+internal expect fun currentTime(): Instant

core/native/src/internal/TimeZoneNative.kt

@@ -5,12 +5,12 @@
 
 package kotlinx.datetime.internal
 
-internal class TzdbOnFilesystem(defaultTzdbPath: Path) {
+internal class TzdbOnFilesystem(defaultTzdbPath: Path): TimeZoneDatabase {
 
-    internal fun rulesForId(id: String): TimeZoneRules =
+    override fun rulesForId(id: String): TimeZoneRules =
         readTzFile(tzdbPath.resolve(Path.fromString(id)).readBytes()).toTimeZoneRules()
 
-    internal fun availableTimeZoneIds(): Set<String> = buildSet {
+    override fun availableTimeZoneIds(): Set<String> = buildSet {
         tzdbPath.traverseDirectory(exclude = tzdbUnneededFiles) { add(it.toString()) }
     }
 

core/nix/src/internal/TzdbOnFilesystem.kt

@@ -1,26 +1,18 @@
 /*
- * Copyright 2019-2023 JetBrains s.r.o. and contributors.
+ * Copyright 2019-2024 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.
  */
+
 @file:OptIn(ExperimentalForeignApi::class)
-package kotlinx.datetime
+package kotlinx.datetime.internal
 
 import kotlinx.cinterop.*
-import kotlinx.datetime.internal.*
+import kotlinx.datetime.*
 import platform.posix.*
 
-internal actual class TimeZoneDatabase {
-    actual companion object {
-        actual fun rulesForId(id: String): TimeZoneRules = tzdbInRegistry.rulesForId(id)
-
-        actual fun currentSystemDefault(): Pair<String, TimeZoneRules?> = tzdbInRegistry.currentSystemDefault()
-
-        actual val availableZoneIds: Set<String>
-            get() = tzdbInRegistry.availableTimeZoneIds()
-    }
-}
+internal actual val systemTzdb: TimeZoneDatabase get() = tzdbInRegistry
 
-private val tzdbInRegistry = TzdbInRegistry()
+internal actual fun currentSystemDefaultZone(): Pair<String, TimeZoneRules?> = tzdbInRegistry.currentSystemDefault()
 
 internal actual fun currentTime(): Instant = memScoped {
     val tm = alloc<timespec>()
@@ -33,3 +25,5 @@ internal actual fun currentTime(): Instant = memScoped {
         throw IllegalStateException("The readings from the system clock (${tm.tv_sec} seconds, ${tm.tv_nsec} nanoseconds) are not representable as an Instant")
     }
 }
+
+private val tzdbInRegistry = TzdbInRegistry()

core/windows/src/TimeZoneNative.kt renamed to core/windows/src/internal/TimeZoneNative.kt

@@ -2,15 +2,15 @@
  * 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.
  */
-@file:OptIn(kotlinx.cinterop.ExperimentalForeignApi::class)
+@file:OptIn(ExperimentalForeignApi::class)
 package kotlinx.datetime.internal
 
 import kotlinx.datetime.*
 import kotlinx.cinterop.*
-import kotlinx.datetime.internal.*
+import platform.posix.*
 import platform.windows.*
 
-internal class TzdbInRegistry {
+internal class TzdbInRegistry: TimeZoneDatabase {
 
     // TODO: starting version 1703 of Windows 10, the ICU library is also bundled, with more accurate/ timezone information.
     // When Kotlin/Native drops support for Windows 7, we should investigate moving to the ICU.
@@ -45,13 +45,13 @@ internal class TzdbInRegistry {
         }
     }
 
-    internal fun rulesForId(id: String): TimeZoneRules {
+    override fun rulesForId(id: String): TimeZoneRules {
         val standardName = standardToWindows[id] ?: throw IllegalTimeZoneException("Unknown time zone $id")
         return windowsToRules[standardName]
                 ?: throw IllegalTimeZoneException("The rules for time zone $id are absent in the Windows registry")
     }
 
-    internal fun availableTimeZoneIds(): Set<String> = standardToWindows.filter {
+    override fun availableTimeZoneIds(): Set<String> = standardToWindows.filter {
         windowsToRules.containsKey(it.value)
     }.keys