Locale-invariant parsing and formatting

.gitignore

@@ -4,4 +4,5 @@
 *.iml
 target
 build
-/local.properties
+/local.properties
+benchmarks.jar

README.md

@@ -388,3 +388,5 @@ For local builds, you can use a later version of JDK if you don't have that
 version installed. Specify the version of this JDK with the `java.mainToolchainVersion` Gradle property.
 
 After that, the project can be opened in IDEA and built with Gradle.
+
+For building and running benchmarks, see [README.md](benchmarks/README.md)

benchmarks/README.md

@@ -0,0 +1,28 @@
+### Benchmarks utility module
+
+Module that provides benchmarking infrastructure for kotlinx-datetime.
+Please note that these benchmarks are typically written with the specific target, hypothesis and effect in mind.
+
+They provide numbers, not insights, and shouldn't be used as the generic comparison and statements like
+"X implementaiton or format is faster/slower than Y"
+
+
+#### Usage
+
+```
+// Build `benchmarks.jar` into the project's root
+./gradlew :benchmarks:jmhJar
+
+// Run all benchmarks
+java -jar benchmarks.jar
+
+// Run dedicated benchmark(s)
+java -jar benchmarks.jar Formatting
+java -jar benchmarks.jar FormattingBenchmark.formatIso
+
+// Run with the specified number of warmup iterations, measurement iterations, timeunit and mode
+java -jar benchmarks.jar -wi 5 -i 5 -tu us -bm thrpt Formatting
+
+// Extensive help
+java -jar benchmarks.jar -help
+```

benchmarks/build.gradle.kts

@@ -0,0 +1,34 @@
+/*
+ * 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.
+ */
+
+plugins {
+    id("kotlin")
+    id("me.champeau.jmh")
+}
+
+
+val mainJavaToolchainVersion by ext(project.property("java.mainToolchainVersion"))
+val modularJavaToolchainVersion by ext(project.property("java.modularToolchainVersion"))
+
+sourceSets {
+    dependencies {
+        implementation(project(":kotlinx-datetime"))
+        implementation("org.openjdk.jmh:jmh-core:1.35")
+    }
+}
+
+// Publish benchmarks to the root for the easier 'java -jar benchmarks.jar`
+tasks.named<Jar>("jmhJar") {
+    val nullString: String? = null
+    archiveBaseName.set("benchmarks")
+    archiveClassifier.set(nullString)
+    archiveVersion.set(nullString)
+    archiveVersion.convention(nullString)
+    destinationDirectory.set(file("$rootDir"))
+}
+
+repositories {
+    mavenCentral()
+}

benchmarks/src/jmh/kotlin/FormattingBenchmark.kt

@@ -0,0 +1,27 @@
+/*
+ * 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
+
+import org.openjdk.jmh.annotations.*
+import java.util.concurrent.*
+
+@Warmup(iterations = 5, time = 1)
+@Measurement(iterations = 5, time = 1)
+@BenchmarkMode(Mode.Throughput)
+@OutputTimeUnit(TimeUnit.MICROSECONDS)
+@State(Scope.Benchmark)
+@Fork(1)
+open class FormattingBenchmark {
+
+    private val localDateTime = LocalDateTime(2023, 11, 9, 12, 21, 31, 41)
+    private val formatted = LocalDateTime.Formats.ISO.format(localDateTime)
+
+    @Benchmark
+    fun formatIso() = LocalDateTime.Formats.ISO.format(localDateTime)
+
+    @Benchmark
+    fun parseIso() = LocalDateTime.Formats.ISO.parse(formatted)
+}

core/common/src/Instant.kt

@@ -5,6 +5,7 @@
 
 package kotlinx.datetime
 
+import kotlinx.datetime.format.*
 import kotlinx.datetime.internal.*
 import kotlinx.datetime.serializers.InstantIso8601Serializer
 import kotlinx.serialization.Serializable
@@ -115,6 +116,9 @@ public expect class Instant : Comparable<Instant> {
      * where the component for seconds is 60, and for any day, it's possible to observe 23:59:59.
      *
      * @see Instant.parse
+     * @see DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET for a very similar format. The difference is that
+     * [DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET] will not add trailing zeros for readability to the
+     * fractional part of the second.
      */
     public override fun toString(): String
 
@@ -149,28 +153,26 @@ public expect class Instant : Comparable<Instant> {
         public fun fromEpochSeconds(epochSeconds: Long, nanosecondAdjustment: Int): Instant
 
         /**
-         * Parses a string that represents an instant in ISO-8601 format including date and time components and
-         * the mandatory time zone offset and returns the parsed [Instant] value.
+         * A shortcut for calling [parse] with [DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET].
          *
-         * Supports the following ways of specifying the time zone offset:
-         * - the `Z` designator for the UTC+0 time zone,
-         * - a custom time zone offset specified with `+hh`, or `+hh:mm`, or `+hh:mm:ss`
-         *   (with `+` being replaced with `-` for the negative offsets)
+         * Parses a string that represents an instant in ISO 8601 format including date and time components and
+         * the mandatory time zone offset and returns the parsed [Instant] value.
          *
-         * Examples of instants in the ISO-8601 format:
+         * Examples of instants in the ISO 8601 format:
          * - `2020-08-30T18:43:00Z`
-         * - `2020-08-30T18:43:00.500Z`
+         * - `2020-08-30T18:43:00.50Z`
          * - `2020-08-30T18:43:00.123456789Z`
          * - `2020-08-30T18:40:00+03:00`
          * - `2020-08-30T18:40:00+03:30:20`
+         * * `2020-01-01T23:59:59.123456789+01`
+         * * `+12020-01-31T23:59:59Z`
          *
-         * The string is considered to represent time on the UTC-SLS time scale instead of UTC.
-         * In practice, this means that, even if there is a leap second on the given day, it will not affect how the
-         * time is parsed, even if it's in the last 1000 seconds of the day.
-         * Instead, even if there is a negative leap second on the given day, 23:59:59 is still considered valid time.
-         * 23:59:60 is invalid on UTC-SLS, so parsing it will fail.
+         * Guaranteed to parse all strings that [Instant.toString] produces.
          *
          * @throws IllegalArgumentException if the text cannot be parsed or the boundaries of [Instant] are exceeded.
+         *
+         * @see Instant.toString
+         * @see DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET
          */
         public fun parse(isoString: String): Instant
 
@@ -512,12 +514,37 @@ public fun Instant.minus(other: Instant, unit: DateTimeUnit, timeZone: TimeZone)
 public fun Instant.minus(other: Instant, unit: DateTimeUnit.TimeBased): Long =
     other.until(this, unit)
 
-internal const val DISTANT_PAST_SECONDS = -3217862419201
-internal const val DISTANT_FUTURE_SECONDS = 3093527980800
+/**
+ * Formats this value using the given [format] using the given [offset].
+ *
+ * [DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET] is the format very similar to the one used by [toString] and
+ * [Instant.Companion.parse]. The only difference is that [Instant.toString] adds trailing zeros to the
+ * fraction-of-second component so that the number of digits after a dot is a multiple of three.
+ */
+public fun Instant.format(format: DateTimeFormat<DateTimeComponents>, offset: UtcOffset = UtcOffset.ZERO): String {
+    val instant = this
+    return format.format { setDateTimeOffset(instant, offset) }
+}
 
 /**
- * Displays the given Instant in the given [offset].
+ * Parses an [Instant] value using the given [format].
+ *
+ * Equivalent to calling [DateTimeFormat.parse] on [format] with [input] and obtaining the resulting [Instant] using
+ * [DateTimeComponents.toInstantUsingOffset].
  *
- * Be careful: this function may throw for some values of the [Instant].
+ * The string is considered to represent time on the UTC-SLS time scale instead of UTC.
+ * In practice, this means that, even if there is a leap second on the given day, it will not affect how the
+ * time is parsed, even if it's in the last 1000 seconds of the day.
+ * Instead, even if there is a negative leap second on the given day, 23:59:59 is still considered valid time.
+ * 23:59:60 is invalid on UTC-SLS, so parsing it will fail.
+ *
+ * @throws IllegalArgumentException if the text cannot be parsed or the boundaries of [Instant] are exceeded.
  */
-internal expect fun Instant.toStringWithOffset(offset: UtcOffset): String
+public fun Instant.Companion.parse(input: CharSequence, format: DateTimeFormat<DateTimeComponents>): Instant = try {
+    format.parse(input).toInstantUsingOffset()
+} catch (e: IllegalArgumentException) {
+    throw DateTimeFormatException("Failed to parse an instant from '$input'", e)
+}
+
+internal const val DISTANT_PAST_SECONDS = -3217862419201
+internal const val DISTANT_FUTURE_SECONDS = 3093527980800

core/common/src/LocalDate.kt

@@ -5,6 +5,7 @@
 
 package kotlinx.datetime
 
+import kotlinx.datetime.format.*
 import kotlinx.datetime.serializers.LocalDateIso8601Serializer
 import kotlinx.serialization.Serializable
 
@@ -41,10 +42,67 @@ public expect class LocalDate : Comparable<LocalDate> {
          */
         public fun fromEpochDays(epochDays: Int): LocalDate
 
+        /**
+         * Creates a new format for parsing and formatting [LocalDate] values.
+         *
+         * Example:
+         * ```
+         * // 2020 Jan 05
+         * LocalDate.Format {
+         *   year()
+         *   char(' ')
+         *   monthName(MonthNames.ENGLISH_ABBREVIATED)
+         *   char(' ')
+         *   dayOfMonth()
+         * }
+         * ```
+         *
+         * Only parsing and formatting of well-formed values is supported. If the input does not fit the boundaries
+         * (for example, [dayOfMonth] is 31 for February), consider using [DateTimeComponents.Format] instead.
+         *
+         * There is a collection of predefined formats in [LocalDate.Formats].
+         */
+        @Suppress("FunctionName")
+        public fun Format(block: DateTimeFormatBuilder.WithDate.() -> Unit): DateTimeFormat<LocalDate>
+
         internal val MIN: LocalDate
         internal val MAX: LocalDate
     }
 
+    /**
+     * A collection of predefined formats for parsing and formatting [LocalDate] values.
+     *
+     * See [LocalDate.Formats.ISO] and [LocalDate.Formats.ISO_BASIC] for popular predefined formats.
+     * [LocalDate.parse] and [LocalDate.toString] can be used as convenient shortcuts for the
+     * [LocalDate.Formats.ISO] format.
+     *
+     * If predefined formats are not sufficient, use [LocalDate.Format] to create a custom
+     * [kotlinx.datetime.format.DateTimeFormat] for [LocalDate] values.
+     */
+    public object Formats {
+        /**
+         * ISO 8601 extended format, which is the format used by [LocalDate.toString] and [LocalDate.parse].
+         *
+         * Examples of dates in ISO 8601 format:
+         * - `2020-08-30`
+         * - `+12020-08-30`
+         * - `0000-08-30`
+         * - `-0001-08-30`
+         */
+        public val ISO: DateTimeFormat<LocalDate>
+
+        /**
+         * ISO 8601 basic format.
+         *
+         * Examples of dates in ISO 8601 basic format:
+         * - `20200830`
+         * - `+120200830`
+         * - `00000830`
+         * - `-00010830`
+         */
+        public val ISO_BASIC: DateTimeFormat<LocalDate>
+    }
+
     /**
      * Constructs a [LocalDate] instance from the given date components.
      *
@@ -77,14 +135,19 @@ public expect class LocalDate : Comparable<LocalDate> {
 
     /** Returns the year component of the date. */
     public val year: Int
+
     /** Returns the number-of-month (1..12) component of the date. */
     public val monthNumber: Int
+
     /** Returns the month ([Month]) component of the date. */
     public val month: Month
+
     /** Returns the day-of-month component of the date. */
     public val dayOfMonth: Int
+
     /** Returns the day-of-week component of the date. */
     public val dayOfWeek: DayOfWeek
+
     /** Returns the day-of-year component of the date. */
     public val dayOfYear: Int
 
@@ -113,6 +176,21 @@ public expect class LocalDate : Comparable<LocalDate> {
     public override fun toString(): String
 }
 
+/**
+ * Formats this value using the given [format].
+ * Equivalent to calling [DateTimeFormat.format] on [format] with `this`.
+ */
+public fun LocalDate.format(format: DateTimeFormat<LocalDate>): String = format.format(this)
+
+/**
+ * Parses a [LocalDate] value using the given [format].
+ * Equivalent to calling [DateTimeFormat.parse] on [format] with [input].
+ *
+ * @throws IllegalArgumentException if the text cannot be parsed or the boundaries of [LocalDate] are exceeded.
+ */
+public fun LocalDate.Companion.parse(input: CharSequence, format: DateTimeFormat<LocalDate>): LocalDate =
+    format.parse(input)
+
 /**
  * Converts this string representing a date in ISO-8601 format to a [LocalDate] value.
  *
@@ -162,9 +240,8 @@ public operator fun LocalDate.minus(period: DatePeriod): LocalDate =
     if (period.days != Int.MIN_VALUE && period.months != Int.MIN_VALUE) {
         plus(with(period) { DatePeriod(-years, -months, -days) })
     } else {
-        minus(period.years, DateTimeUnit.YEAR).
-        minus(period.months, DateTimeUnit.MONTH).
-        minus(period.days, DateTimeUnit.DAY)
+        minus(period.years, DateTimeUnit.YEAR).minus(period.months, DateTimeUnit.MONTH)
+            .minus(period.days, DateTimeUnit.DAY)
     }
 
 /**