Add Duration.parse/parseIsoString samples

libraries/stdlib/samples/test/samples/time/durations.kt

@@ -6,6 +6,7 @@
 package samples.time
 
 import samples.*
+import kotlin.test.*
 
 import kotlin.time.*
 
@@ -41,6 +42,28 @@ class Durations {
         assertPrints(Duration.minutes(1230).toString(DurationUnit.SECONDS), "73800s")
     }
 
+    @Sample
+    fun parse() {
+        val isoFormatString = "PT1H30M"
+        val defaultFormatString = "1h 30m"
+        val singleUnitFormatString = "1.5h"
+        val invalidFormatString = "1 hour 30 minutes"
 
+        assertPrints(Duration.parse(isoFormatString), "1h 30m")
+        assertPrints(Duration.parse(defaultFormatString), "1h 30m")
+        assertPrints(Duration.parse(singleUnitFormatString), "1h 30m")
+        assertFails { Duration.parse(invalidFormatString) }
+        assertPrints(Duration.parseOrNull(invalidFormatString), "null")
+    }
+
+    @Sample
+    fun parseIsoString() {
+        val isoFormatString = "PT1H30M"
+        val defaultFormatString = "1h 30m"
+
+        assertPrints(Duration.parseIsoString(isoFormatString), "1h 30m")
+        assertFails { Duration.parseIsoString(defaultFormatString) }
+        assertPrints(Duration.parseIsoStringOrNull(defaultFormatString), "null")
+    }
 
 }

libraries/stdlib/src/kotlin/time/Duration.kt

@@ -181,6 +181,7 @@ public value class Duration internal constructor(private val rawValue: Long) : C
          *   e.g. `10s`, `1h 30m` or `-(1h 30m)`.
          *
          * @throws IllegalArgumentException if the string doesn't represent a duration in any of the supported formats.
+         * @sample samples.time.Durations.parse
          */
         @SinceKotlin("1.5")
         public fun parse(value: String): Duration = try {
@@ -193,6 +194,7 @@ 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.
          *
          * @throws IllegalArgumentException if the string doesn't represent a duration in ISO-8601 format.
+         * @sample samples.time.Durations.parseIsoString
          */
         @SinceKotlin("1.5")
         public fun parseIsoString(value: String): Duration = try {
@@ -210,6 +212,7 @@ public value class Duration internal constructor(private val rawValue: Long) : C
          * - ISO-8601 Duration format, 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
          */
         @SinceKotlin("1.5")
         public fun parseOrNull(value: String): Duration? = try {
@@ -221,6 +224,7 @@ 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.
+         * @sample samples.time.Durations.parseIsoString
          */
         @SinceKotlin("1.5")
         public fun parseIsoStringOrNull(value: String): Duration? = try {