Define the public API endpoints for datetime formatting

Fixes #39
Fixes #58
Fixes #90
Fixes #128
Fixes #133
Fixes #139
Fixes #211
Fixes #240
Fixes #83
Fixes #276

Author: dkhalanskyjb

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,31 +153,28 @@ 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 [DateTimeFormat.parse], followed by [DateTimeComponents.toInstantUsingOffset].
          *
-         * 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)
-         *
-         * 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`
+         * Parses a string that represents an instant including date and time components and a mandatory
+         * time zone offset and returns the parsed [Instant] value.
          *
          * 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.
          *
+         * If the format is not specified, [DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET] is used.
+         *
          * @throws IllegalArgumentException if the text cannot be parsed or the boundaries of [Instant] are exceeded.
+         *
+         * @see Instant.toString for formatting using the default format.
+         * @see Instant.format for formatting using a custom format.
          */
-        public fun parse(isoString: String): Instant
-
+        public fun parse(
+            input: CharSequence,
+            format: DateTimeFormat<DateTimeComponents> = DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET
+        ): Instant
 
         /**
          * An instant value that is far in the past.
@@ -508,12 +509,20 @@ 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
-
 /**
- * Displays the given Instant in the given [offset].
+ * Formats this value using the given [format] using the given [offset].
+ *
+ * Equivalent to calling [DateTimeFormat.format] on [format] and using [DateTimeComponents.setDateTimeOffset] in
+ * the lambda.
  *
- * Be careful: this function may throw for some values of the [Instant].
+ * [DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET] is a format very similar to the one used by [toString].
+ * 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.
  */
-internal expect fun Instant.toStringWithOffset(offset: UtcOffset): String
+public fun Instant.format(format: DateTimeFormat<DateTimeComponents>, offset: UtcOffset = UtcOffset.ZERO): String {
+    val instant = this
+    return format.format { setDateTimeOffset(instant, offset) }
+}
+
+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
 
@@ -23,14 +24,18 @@ import kotlinx.serialization.Serializable
 public expect class LocalDate : Comparable<LocalDate> {
     public companion object {
         /**
-         * Parses a string that represents a date in ISO-8601 format
-         * and returns the parsed [LocalDate] value.
+         * A shortcut for calling [DateTimeFormat.parse].
          *
-         * An example of a local date in ISO-8601 format: `2020-08-30`.
+         * Parses a string that represents a date and returns the parsed [LocalDate] value.
+         *
+         * If [format] is not specified, [Formats.ISO] is used.
          *
          * @throws IllegalArgumentException if the text cannot be parsed or the boundaries of [LocalDate] are exceeded.
+         *
+         * @see LocalDate.toString for formatting using the default format.
+         * @see LocalDate.format for formatting using a custom format.
          */
-        public fun parse(isoString: String): LocalDate
+        public fun parse(input: CharSequence, format: DateTimeFormat<LocalDate> = getIsoDateFormat()): LocalDate
 
         /**
          * Returns a [LocalDate] that is [epochDays] number of days from the epoch day `1970-01-01`.
@@ -41,10 +46,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 +139,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
 
@@ -106,13 +173,21 @@ public expect class LocalDate : Comparable<LocalDate> {
     public override fun compareTo(other: LocalDate): Int
 
     /**
-     * Converts this date to the ISO-8601 string representation.
+     * Converts this date to the extended ISO-8601 string representation.
      *
-     * @see LocalDate.parse
+     * @see Formats.ISO for the format details.
+     * @see parse for the dual operation: obtaining [LocalDate] from a string.
+     * @see LocalDate.format for formatting using a custom format.
      */
     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)
+
 /**
  * @suppress
  */
@@ -159,9 +234,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)
     }
 
 /**
@@ -299,3 +373,6 @@ public expect fun LocalDate.plus(value: Long, unit: DateTimeUnit.DateBased): Loc
  * @throws DateTimeArithmeticException if the result exceeds the boundaries of [LocalDate].
  */
 public fun LocalDate.minus(value: Long, unit: DateTimeUnit.DateBased): LocalDate = plus(-value, unit)
+
+// workaround for https://youtrack.jetbrains.com/issue/KT-65484
+internal fun getIsoDateFormat() = LocalDate.Formats.ISO