Common: introduce DISTANT_PAST and DISTANT_FUTURE (#19)

Author: dkhalanskyjb

core/commonMain/src/Instant.kt

@@ -8,7 +8,6 @@ package kotlinx.datetime
 import kotlin.time.Duration
 import kotlin.time.ExperimentalTime
 
-
 @OptIn(kotlin.time.ExperimentalTime::class)
 public expect class Instant : Comparable<Instant> {
 
@@ -63,11 +62,23 @@ public expect class Instant : Comparable<Instant> {
          */
         fun parse(isoString: String): Instant
 
+        // -100001-12-31T23:59:59.999999999Z
+        val DISTANT_PAST: Instant
+
+        // +100000-01-01T00:00:00Z
+        val DISTANT_FUTURE: Instant
+
         internal val MIN: Instant
         internal val MAX: Instant
     }
 }
 
+public val Instant.isDistantPast
+    get() = this <= Instant.DISTANT_PAST
+
+public val Instant.isDistantFuture
+    get() = this >= Instant.DISTANT_FUTURE
+
 /**
  * @throws DateTimeFormatException if the text cannot be parsed or the boundaries of [Instant] are exceeded.
  */
@@ -155,3 +166,6 @@ public fun Instant.plus(value: Long, unit: DateTimeUnit, zone: TimeZone): Instan
 
 
 public fun Instant.minus(other: Instant, unit: DateTimeUnit, zone: TimeZone): Long = other.until(this, unit, zone)
+
+internal const val DISTANT_PAST_SECONDS = -3217862419201
+internal const val DISTANT_FUTURE_SECONDS = 3093527980800

core/commonTest/src/InstantTest.kt

@@ -323,6 +323,29 @@ class InstantTest {
         assertEquals("+19999-12-31T23:59:59.000000009Z", LocalDateTime(19999, 12, 31, 23, 59, 59, 9).toInstant(TimeZone.UTC).toString())
     }
 
+    @ExperimentalTime
+    @Test
+    fun distantPastAndFuture() {
+        val distantFutureString = "+100000-01-01T00:00:00Z"
+        val distantPastString = "-100001-12-31T23:59:59.999999999Z"
+        assertEquals(distantFutureString, Instant.DISTANT_FUTURE.toString())
+        assertEquals(Instant.DISTANT_FUTURE, distantFutureString.toInstant())
+        assertEquals(distantPastString, Instant.DISTANT_PAST.toString())
+        assertEquals(Instant.DISTANT_PAST, distantPastString.toInstant())
+        assertTrue(Instant.DISTANT_PAST.isDistantPast)
+        assertTrue(Instant.DISTANT_FUTURE.isDistantFuture)
+        assertFalse(Instant.DISTANT_PAST.isDistantFuture)
+        assertFalse(Instant.DISTANT_FUTURE.isDistantPast)
+        assertFalse((Instant.DISTANT_PAST + 1.nanoseconds).isDistantPast)
+        assertFalse((Instant.DISTANT_FUTURE - 1.nanoseconds).isDistantFuture)
+        assertTrue((Instant.DISTANT_PAST - 1.nanoseconds).isDistantPast)
+        assertTrue((Instant.DISTANT_FUTURE + 1.nanoseconds).isDistantFuture)
+        assertTrue(Instant.MAX.isDistantFuture)
+        assertFalse(Instant.MAX.isDistantPast)
+        assertTrue(Instant.MIN.isDistantPast)
+        assertFalse(Instant.MIN.isDistantFuture)
+    }
+
 }
 
 @OptIn(ExperimentalTime::class)

core/jsMain/src/Instant.kt

@@ -87,6 +87,9 @@ public actual class Instant internal constructor(internal val value: jtInstant)
             if (epochSeconds > 0) MAX else MIN
         }
 
+        actual val DISTANT_PAST: Instant = Instant(jtInstant.ofEpochSecond(DISTANT_PAST_SECONDS, 999_999_999))
+        actual val DISTANT_FUTURE: Instant = Instant(jtInstant.ofEpochSecond(DISTANT_FUTURE_SECONDS, 0))
+
         internal actual val MIN: Instant = Instant(jtInstant.MIN)
         internal actual val MAX: Instant = Instant(jtInstant.MAX)
     }

core/jvmMain/src/Instant.kt

@@ -73,6 +73,9 @@ public actual class Instant internal constructor(internal val value: jtInstant)
             if (epochSeconds > 0) MAX else MIN
         }
 
+        actual val DISTANT_PAST: Instant = Instant(jtInstant.ofEpochSecond(DISTANT_PAST_SECONDS, 999_999_999))
+        actual val DISTANT_FUTURE: Instant = Instant(jtInstant.ofEpochSecond(DISTANT_FUTURE_SECONDS, 0))
+
         internal actual val MIN: Instant = Instant(jtInstant.MIN)
         internal actual val MAX: Instant = Instant(jtInstant.MAX)
     }

core/nativeMain/src/Instant.kt

@@ -253,6 +253,12 @@ public actual class Instant internal constructor(actual val epochSeconds: Long,
 
         actual fun parse(isoString: String): Instant =
             instantParser.parse(isoString)
+
+        @SharedImmutable
+        actual val DISTANT_PAST: Instant = fromEpochSeconds(DISTANT_PAST_SECONDS, 999_999_999)
+
+        @SharedImmutable
+        actual val DISTANT_FUTURE: Instant = fromEpochSeconds(DISTANT_FUTURE_SECONDS, 0)
     }
 
 }