Implement parsing of Instant with an offset

Author: dkhalanskyjb

core/common/src/Instant.kt

@@ -123,12 +123,18 @@ public expect class Instant : Comparable<Instant> {
 
         /**
          * Parses a string that represents an instant in ISO-8601 format including date and time components and
-         * the mandatory `Z` designator of the UTC+0 time zone and returns the parsed [Instant] value.
+         * the mandatory time zone offset and returns the parsed [Instant] value.
          *
-         * Examples of instants in ISO-8601 format:
+         * In addition to allowing the `Z` designator of the UTC+0 time zone to be passed as the time zone offset, which
+         * is required by the ISO-8601, this parser also accepts the other possible offsets, but does not provide a way
+         * to query the result for which offset was present in the string.
+         *
+         * Examples of instants in the ISO-8601 format:
          * - `2020-08-30T18:43:00Z`
          * - `2020-08-30T18:43:00.500Z`
          * - `2020-08-30T18:43:00.123456789Z`
+         * - `2020-08-30T18:40.00+03:00`
+         * - `2020-08-30T18:40.00+03:30:20`
          *
          * @throws IllegalArgumentException if the text cannot be parsed or the boundaries of [Instant] are exceeded.
          */
@@ -166,7 +172,7 @@ public val Instant.isDistantFuture
 
 /**
  * Converts this string representing an instant in ISO-8601 format including date and time components and
- * the mandatory `Z` designator of the UTC+0 time zone to an [Instant] value.
+ * the time zone offset to an [Instant] value.
  *
  * See [Instant.parse] for examples of instant string representations.
  *

core/common/test/InstantTest.kt

@@ -85,6 +85,27 @@ class InstantTest {
         assertInvalidFormat { Instant.parse("+1000000001-12-31T23:59:59.000000000Z") }
     }
 
+    @Test
+    fun parseStringsWithOffsets() {
+        val instants = arrayOf(
+            Triple("2020-01-01T00:01:01.02+18:00", 1577772061L, 20_000_000),
+            Triple("2020-01-01T00:01:01.123456789-17:59:59", 1577901660L, 123456789),
+            Triple("2020-01-01T00:01:01.010203040+17:59:59", 1577772062L, 10203040),
+            Triple("2020-01-01T00:01:01.010203040+17:59", 1577772121L, 10203040),
+            // Triple("2020-01-01T00:01:01+00", 1577836861L, 0), // fails on JS, passes everywhere else
+        )
+        instants.forEach {
+            val (str, seconds, nanos) = it
+            val instant = Instant.parse(str)
+            assertEquals(nanos, instant.nanosecondsOfSecond, str)
+            assertEquals(seconds, instant.epochSeconds, str)
+        }
+        assertInvalidFormat { Instant.parse("2020-01-01T00:01:01+18:01") }
+        assertInvalidFormat { Instant.parse("2020-01-01T00:01:01+1801") }
+        assertInvalidFormat { Instant.parse("2020-01-01T00:01:01+0") }
+        assertInvalidFormat { Instant.parse("2020-01-01T00:01:01+000000") }
+    }
+
     @OptIn(ExperimentalTime::class)
     @Test
     fun instantCalendarArithmetic() {

core/js/src/Instant.kt

@@ -11,6 +11,7 @@ import kotlin.time.ExperimentalTime
 import kotlin.time.nanoseconds
 import kotlin.time.seconds
 import kotlinx.datetime.internal.JSJoda.Instant as jtInstant
+import kotlinx.datetime.internal.JSJoda.OffsetDateTime as jtOffsetDateTime
 import kotlinx.datetime.internal.JSJoda.Duration as jtDuration
 import kotlinx.datetime.internal.JSJoda.Clock as jtClock
 import kotlinx.datetime.internal.JSJoda.ChronoUnit
@@ -76,7 +77,7 @@ public actual class Instant internal constructor(internal val value: jtInstant)
         }
 
         actual fun parse(isoString: String): Instant = try {
-            Instant(jtInstant.parse(isoString))
+            Instant(jtOffsetDateTime.parse(isoString).toInstant())
         } catch (e: Throwable) {
             if (e.isJodaDateTimeParseException()) throw DateTimeFormatException(e)
             throw e

core/jvm/src/Instant.kt

@@ -13,6 +13,7 @@ import java.time.format.DateTimeParseException
 import java.time.temporal.ChronoUnit
 import kotlin.time.*
 import java.time.Instant as jtInstant
+import java.time.OffsetDateTime as jtOffsetDateTime
 import java.time.Clock as jtClock
 
 @Serializable(with = InstantIso8601Serializer::class)
@@ -63,7 +64,7 @@ public actual class Instant internal constructor(internal val value: jtInstant)
                 Instant(jtInstant.ofEpochMilli(epochMilliseconds))
 
         actual fun parse(isoString: String): Instant = try {
-            Instant(jtInstant.parse(isoString))
+            Instant(jtOffsetDateTime.parse(isoString).toInstant())
         } catch (e: DateTimeParseException) {
             throw DateTimeFormatException(e)
         }

core/native/src/Instant.kt

@@ -23,8 +23,48 @@ public actual enum class DayOfWeek {
     SUNDAY;
 }
 
+/** A parser for the string representation of [ZoneOffset] as seen in `OffsetDateTime`.
+ *
+ * We can't just reuse the parsing logic of [ZoneOffset.of], as that version is more lenient: here, strings like
+ * "0330" are not considered valid zone offsets, whereas [ZoneOffset.of] sees treats the example above as "03:30". */
+private val zoneOffsetParser: Parser<ZoneOffset>
+    get() = (concreteCharParser('z').or(concreteCharParser('Z')).map { ZoneOffset.UTC })
+        .or(
+            concreteCharParser('+').or(concreteCharParser('-'))
+                .chain(intParser(2, 2))
+                .chain(
+                    optional(
+                        // minutes
+                        concreteCharParser(':').chainSkipping(intParser(2, 2))
+                            .chain(optional(
+                                    // seconds
+                                    concreteCharParser(':').chainSkipping(intParser(2, 2))
+                            ))))
+                .map {
+                    val (signHours, minutesSeconds) = it
+                    val (sign, hours) = signHours
+                    val minutes: Int
+                    val seconds: Int
+                    if (minutesSeconds == null) {
+                        minutes = 0
+                        seconds = 0
+                    } else {
+                        minutes = minutesSeconds.first
+                        seconds = minutesSeconds.second ?: 0
+                    }
+                    try {
+                        if (sign == '-')
+                            ZoneOffset.ofHoursMinutesSeconds(-hours, -minutes, -seconds)
+                        else
+                            ZoneOffset.ofHoursMinutesSeconds(hours, minutes, seconds)
+                    } catch (e: IllegalTimeZoneException) {
+                        throw DateTimeFormatException(e)
+                    }
+                }
+        )
+
 // This is a function and not a value due to https://github.com/Kotlin/kotlinx-datetime/issues/5
-// org.threeten.bp.format.DateTimeFormatterBuilder.InstantPrinterParser#parse
+// org.threeten.bp.format.DateTimeFormatter#ISO_OFFSET_DATE_TIME
 private val instantParser: Parser<Instant>
     get() = localDateParser
         .chainIgnoring(concreteCharParser('T').or(concreteCharParser('t')))
@@ -37,9 +77,10 @@ private val instantParser: Parser<Instant>
             concreteCharParser('.')
                 .chainSkipping(fractionParser(0, 9, 9)) // nanos
         ))
-        .chainIgnoring(concreteCharParser('Z').or(concreteCharParser('z')))
+        .chain(zoneOffsetParser)
         .map {
-            val (dateHourMinuteSecond, nanosVal) = it
+            val (localDateTime, offset) = it
+            val (dateHourMinuteSecond, nanosVal) = localDateTime
             val (dateHourMinute, secondsVal) = dateHourMinuteSecond
             val (dateHour, minutesVal) = dateHourMinute
             val (dateVal, hoursVal) = dateHour
@@ -63,7 +104,7 @@ private val instantParser: Parser<Instant>
                 throw DateTimeFormatException(e)
             }
             val epochDay = localDate.toEpochDay().toLong()
-            val instantSecs = epochDay * 86400 + localTime.toSecondOfDay() + secDelta
+            val instantSecs = epochDay * 86400 - offset.totalSeconds + localTime.toSecondOfDay() + secDelta
             try {
                 Instant(instantSecs, nano)
             } catch (e: IllegalArgumentException) {