Temporary commit: reproducer for a bug. To be squashed with the following commit.

Author: dkhalanskyjb

core/common/src/Instant.kt

@@ -153,29 +153,28 @@ public expect class Instant : Comparable<Instant> {
         public fun fromEpochSeconds(epochSeconds: Long, nanosecondAdjustment: Int): Instant
 
         /**
-         * A shortcut for calling [parse] with [DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET].
+         * A shortcut for calling [DateTimeFormat.parse], followed by [DateTimeComponents.toInstantUsingOffset].
          *
-         * 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.
+         * Parses a string that represents an instant including date and time components and a mandatory
+         * time zone offset and returns the parsed [Instant] value.
          *
-         * Examples of instants in the ISO 8601 format:
-         * - `2020-08-30T18:43:00Z`
-         * - `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.
+         * 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
-         * @see DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET
+         * @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.
@@ -513,34 +512,17 @@ public fun Instant.minus(other: Instant, unit: DateTimeUnit.TimeBased): Long =
 /**
  * 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.
+ * Equivalent to calling [DateTimeFormat.format] on [format] and using [DateTimeComponents.setDateTimeOffset] in
+ * the lambda.
+ *
+ * [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.
  */
 public fun Instant.format(format: DateTimeFormat<DateTimeComponents>, offset: UtcOffset = UtcOffset.ZERO): String {
     val instant = this
     return format.format { setDateTimeOffset(instant, 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].
- *
- * 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.
- */
-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

@@ -24,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> = Formats.ISO): LocalDate
 
         /**
          * Returns a [LocalDate] that is [epochDays] number of days from the epoch day `1970-01-01`.
@@ -169,9 +173,11 @@ 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
 }
@@ -182,15 +188,6 @@ public expect class LocalDate : Comparable<LocalDate> {
  */
 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)
-
 /**
  * @suppress
  */

core/common/src/LocalDateTime.kt

@@ -5,6 +5,8 @@
 
 package kotlinx.datetime
 
+import kotlinx.datetime.LocalDate.*
+import kotlinx.datetime.LocalDate.Companion.parse
 import kotlinx.datetime.format.*
 import kotlinx.datetime.serializers.LocalDateTimeIso8601Serializer
 import kotlinx.serialization.Serializable
@@ -28,23 +30,17 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
     public companion object {
 
         /**
-         * A shortcut for calling [parse] with [Formats.ISO].
+         * A shortcut for calling [DateTimeFormat.parse].
          *
-         * Parses a string that represents a date/time value in ISO 8601 format including date and time components
+         * Parses a string that represents a date/time value including date and time components
          * but without any time zone component and returns the parsed [LocalDateTime] value.
          *
-         * Examples of date/time in ISO 8601 format:
-         * - `2020-08-30T18:43`
-         * - `2020-08-30T18:43:00`
-         * - `2020-08-30T18:43:00.5`
-         * - `2020-08-30T18:43:00.123456789`
-         *
-         * Guaranteed to parse all strings that [LocalDateTime.toString] produces.
+         * If [format] is not specified, [Formats.ISO] is used.
          *
          * @throws IllegalArgumentException if the text cannot be parsed or the boundaries of [LocalDateTime] are
          * exceeded.
          */
-        public fun parse(isoString: String): LocalDateTime
+        public fun parse(input: CharSequence, format: DateTimeFormat<LocalDateTime> = Formats.ISO): LocalDateTime
 
         /**
          * Creates a new format for parsing and formatting [LocalDateTime] values.
@@ -95,6 +91,8 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
          *
          * When formatting, seconds are always included, even if they are zero.
          * Fractional parts of the second are included if non-zero.
+         *
+         * Guaranteed to parse all strings that [LocalDateTime.toString] produces.
          */
         public val ISO: DateTimeFormat<LocalDateTime>
     }
@@ -206,15 +204,21 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
     /**
      * Converts this date/time value to the ISO 8601 string representation.
      *
-     * Examples of date/time in ISO 8601 format:
+     * For readability, if the time represents a round minute (without seconds or fractional seconds),
+     * the string representation will not include seconds. Also, fractions of seconds will add trailing zeros to
+     * the fractional part until its length is a multiple of three.
+     *
+     * Examples of output:
      * - `2020-08-30T18:43`
      * - `2020-08-30T18:43:00`
      * - `2020-08-30T18:43:00.500`
      * - `2020-08-30T18:43:00.123456789`
      *
+     * @see LocalTime.toString for details of how the time part is formatted.
      * @see Formats.ISO for a very similar format. The difference is that [Formats.ISO] will always include seconds,
      * even if they are zero, and will not add trailing zeros to the fractional part of the second for readability.
-     * @see LocalDateTime.parse
+     * @see parse for the dual operation: obtaining [LocalDateTime] from a string.
+     * @see LocalDateTime.format for formatting using a custom format.
      */
     public override fun toString(): String
 }
@@ -225,15 +229,6 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
  */
 public fun LocalDateTime.format(format: DateTimeFormat<LocalDateTime>): String = format.format(this)
 
-/**
- * Parses a [LocalDateTime] 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 [LocalDateTime] are exceeded.
- */
-public fun LocalDateTime.Companion.parse(input: CharSequence, format: DateTimeFormat<LocalDateTime>): LocalDateTime =
-    format.parse(input)
-
 /**
  * @suppress
  */

core/common/src/LocalTime.kt

@@ -5,6 +5,8 @@
 
 package kotlinx.datetime
 
+import kotlinx.datetime.LocalDate.*
+import kotlinx.datetime.LocalDate.Companion.parse
 import kotlinx.datetime.format.*
 import kotlinx.datetime.serializers.LocalTimeIso8601Serializer
 import kotlinx.serialization.Serializable
@@ -28,22 +30,17 @@ public expect class LocalTime : Comparable<LocalTime> {
     public companion object {
 
         /**
-         * A shortcut for calling [parse] with [Formats.ISO].
+         * A shortcut for calling [DateTimeFormat.parse].
          *
-         * Parses a string that represents a time value in ISO 8601 and returns the parsed [LocalTime] value.
-         *
-         * Examples of time in ISO 8601 format:
-         * - `18:43`
-         * - `18:43:00`
-         * - `18:43:00.5`
-         * - `18:43:00.123456789`
-         *
-         * Guaranteed to parse all strings that [LocalTime.toString] produces.
+         * Parses a string that represents time-of-day and returns the parsed [LocalTime] value.
          *
          * @throws IllegalArgumentException if the text cannot be parsed or the boundaries of [LocalTime] are
          * exceeded.
+         *
+         * @see LocalTime.toString for formatting using the default format.
+         * @see LocalTime.format for formatting using a custom format.
          */
-        public fun parse(isoString: String): LocalTime
+        public fun parse(input: CharSequence, format: DateTimeFormat<LocalTime> = Formats.ISO): LocalTime
 
         /**
          * Constructs a [LocalTime] that represents the specified number of seconds since the start of a calendar day.
@@ -124,6 +121,8 @@ public expect class LocalTime : Comparable<LocalTime> {
          *
          * When formatting, seconds are always included, even if they are zero.
          * Fractional parts of the second are included if non-zero.
+         *
+         * Guaranteed to parse all strings that [LocalTime.toString] produces.
          */
         public val ISO: DateTimeFormat<LocalTime>
     }
@@ -175,14 +174,22 @@ public expect class LocalTime : Comparable<LocalTime> {
     public override operator fun compareTo(other: LocalTime): Int
 
     /**
-     * Converts this time value to the ISO 8601 string representation:
-     * * `12:34`
-     * * `12:34:56.5`
-     * * `12:34:56.123456789`
+     * Converts this time value to the extended ISO-8601 string representation.
+     *
+     * For readability, if the time represents a round minute (without seconds or fractional seconds),
+     * the string representation will not include seconds. Also, fractions of seconds will add trailing zeros to
+     * the fractional part until the number of digits after the dot is a multiple of three.
+     *
+     * Examples of output:
+     * - `18:43`
+     * - `18:43:00`
+     * - `18:43:00.500`
+     * - `18:43:00.123456789`
      *
      * @see Formats.ISO for a very similar format. The difference is that [Formats.ISO] will always include seconds,
      * even if they are zero, and will not add trailing zeros to the fractional part of the second for readability.
-     * @see LocalTime.parse
+     * @see parse for the dual operation: obtaining [LocalTime] from a string.
+     * @see LocalTime.format for formatting using a custom format.
      */
     public override fun toString(): String
 }
@@ -193,15 +200,6 @@ public expect class LocalTime : Comparable<LocalTime> {
  */
 public fun LocalTime.format(format: DateTimeFormat<LocalTime>): String = format.format(this)
 
-/**
- * Parses a [LocalTime] 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 [LocalTime] are exceeded.
- */
-public fun LocalTime.Companion.parse(input: CharSequence, format: DateTimeFormat<LocalTime>): LocalTime =
-    format.parse(input)
-
 /**
  * @suppress
  */