From 0c8b31b9edd909aeae137c968eb19a4d2f40faf5 Mon Sep 17 00:00:00 2001 From: Vsevolod Tolstopyatov Date: Tue, 28 Jun 2022 07:43:33 +0000 Subject: [PATCH] Clarify specification of Duration.parseIsoString KT-52778 Co-authored-by: Vsevolod Tolstopyatov Merge-request: KT-MR-6556 Merged-by: Vsevolod Tolstopyatov --- libraries/stdlib/src/kotlin/time/Duration.kt | 21 +++++++++++++++----- libraries/stdlib/test/time/DurationTest.kt | 1 + 2 files changed, 17 insertions(+), 5 deletions(-) diff --git a/libraries/stdlib/src/kotlin/time/Duration.kt b/libraries/stdlib/src/kotlin/time/Duration.kt index b6233651bfc..b13d7e7b0ee 100644 --- a/libraries/stdlib/src/kotlin/time/Duration.kt +++ b/libraries/stdlib/src/kotlin/time/Duration.kt @@ -401,7 +401,16 @@ public value class Duration internal constructor(private val rawValue: Long) : C } /** - * Parses a string that represents a duration in ISO-8601 format and returns the parsed [Duration] value. + * Parses a string that represents a duration in a restricted ISO-8601 composite representation + * and returns the parsed [Duration] value. + * Composite representation is a relaxed version of ISO-8601 duration format that supports + * negative durations and negative values of individual components. + * + * The following restrictions are imposed: + * + * - The only allowed non-time designator is days (`D`). `Y` (years), `W` (weeks), and `M` (months) are not supported. + * - Day is considered to be exactly 24 hours (24-hour clock time scale). + * - Alternative week-based representation `["P"][number]["W"]` is not supported. * * @throws IllegalArgumentException if the string doesn't represent a duration in ISO-8601 format. * @sample samples.time.Durations.parseIsoString @@ -418,7 +427,7 @@ public value class Duration internal constructor(private val rawValue: Long) : C * * The following formats are accepted: * - * - ISO-8601 Duration format, e.g. `P1DT2H3M4.058S`, see [toIsoString] and [parseIsoString]. + * - Restricted ISO-8601 duration composite representation, e.g. `P1DT2H3M4.058S`, see [toIsoString] and [parseIsoString]. * - The format of string returned by the default [Duration.toString] and `toString` in a specific unit, * e.g. `10s`, `1h 30m` or `-(1h 30m)`. * @sample samples.time.Durations.parse @@ -430,8 +439,10 @@ public value class Duration internal constructor(private val rawValue: Long) : C } /** - * Parses a string that represents a duration in ISO-8601 format and returns the parsed [Duration] value, - * or `null` if the string doesn't represent a duration in ISO-8601 format. + * Parses a string that represents a duration in restricted ISO-8601 composite representation + * and returns the parsed [Duration] value or `null` if the string doesn't represent a duration in the format + * acceptable by [parseIsoString]. + * * @sample samples.time.Durations.parseIsoString */ public fun parseIsoStringOrNull(value: String): Duration? = try { @@ -1460,4 +1471,4 @@ private fun durationOfMillisNormalized(millis: Long) = internal expect val durationAssertionsEnabled: Boolean internal expect fun formatToExactDecimals(value: Double, decimals: Int): String -internal expect fun formatUpToDecimals(value: Double, decimals: Int): String \ No newline at end of file +internal expect fun formatUpToDecimals(value: Double, decimals: Int): String diff --git a/libraries/stdlib/test/time/DurationTest.kt b/libraries/stdlib/test/time/DurationTest.kt index 03ad5b16dc1..e791e525ea1 100644 --- a/libraries/stdlib/test/time/DurationTest.kt +++ b/libraries/stdlib/test/time/DurationTest.kt @@ -551,6 +551,7 @@ class DurationTest { "1m", "1d", "2d 11s", "Infinity", "-Infinity", "P+12+34D", "P12-34D", "PT1234567890-1234567890S", " P1D", "PT1S ", + "P3W", "P1Y", "P1M", "P1S", "PT1D", "PT1Y", "PT1S2S", "PT1S2H", "P9999999999999DT-9999999999999H",