Add samples for format builders

Author: dkhalanskyjb

core/common/src/format/DateTimeFormatBuilder.kt

@@ -106,6 +106,8 @@ public sealed interface DateTimeFormatBuilder {
          * The hour of the day, from 0 to 23.
          *
          * By default, it's zero-padded to two digits, but this can be changed with [padding].
+         *
+         * @sample kotlinx.datetime.test.samples.format.LocalTimeFormatSamples.hhmmss
          */
         public fun hour(padding: Padding = Padding.ZERO)
 
@@ -122,6 +124,7 @@ public sealed interface DateTimeFormatBuilder {
          * By default, it's zero-padded to two digits, but this can be changed with [padding].
          *
          * @see [amPmMarker]
+         * @sample kotlinx.datetime.test.samples.format.LocalTimeFormatSamples.amPm
          */
         public fun amPmHour(padding: Padding = Padding.ZERO)
 
@@ -131,13 +134,16 @@ public sealed interface DateTimeFormatBuilder {
          * [am] is used for the AM marker (0-11 hours), [pm] is used for the PM marker (12-23 hours).
          *
          * @see [amPmHour]
+         * @sample kotlinx.datetime.test.samples.format.LocalTimeFormatSamples.amPm
          */
         public fun amPmMarker(am: String, pm: String)
 
         /**
          * The minute of hour.
          *
          * By default, it's zero-padded to two digits, but this can be changed with [padding].
+         *
+         * @sample kotlinx.datetime.test.samples.format.LocalTimeFormatSamples.hhmmss
          */
         public fun minute(padding: Padding = Padding.ZERO)
 
@@ -147,6 +153,8 @@ public sealed interface DateTimeFormatBuilder {
          * By default, it's zero-padded to two digits, but this can be changed with [padding].
          *
          * This field has the default value of 0. If you want to omit it, use [optional].
+         *
+         * @sample kotlinx.datetime.test.samples.format.LocalTimeFormatSamples.hhmmss
          */
         public fun second(padding: Padding = Padding.ZERO)
 
@@ -166,6 +174,8 @@ public sealed interface DateTimeFormatBuilder {
          * part.
          *
          * @throws IllegalArgumentException if [minLength] is greater than [maxLength] or if either is not in the range 1..9.
+         *
+         * @sample kotlinx.datetime.test.samples.format.LocalTimeFormatSamples.hhmmss
          */
         public fun secondFraction(minLength: Int = 1, maxLength: Int = 9)
 
@@ -186,6 +196,7 @@ public sealed interface DateTimeFormatBuilder {
          * @throws IllegalArgumentException if [fixedLength] is not in the range 1..9.
          *
          * @see secondFraction that accepts two parameters.
+         * @sample kotlinx.datetime.test.samples.format.LocalTimeFormatSamples.fixedLengthSecondFraction
          */
         public fun secondFraction(fixedLength: Int) {
             secondFraction(fixedLength, fixedLength)
@@ -194,10 +205,7 @@ public sealed interface DateTimeFormatBuilder {
         /**
          * An existing [DateTimeFormat] for the time part.
          *
-         * Example:
-         * ```
-         * time(LocalTime.Formats.ISO)
-         * ```
+         * @sample kotlinx.datetime.test.samples.format.LocalTimeFormatSamples.time
          */
         public fun time(format: DateTimeFormat<LocalTime>)
     }
@@ -209,10 +217,7 @@ public sealed interface DateTimeFormatBuilder {
         /**
          * An existing [DateTimeFormat] for the date-time part.
          *
-         * Example:
-         * ```
-         * dateTime(LocalDateTime.Formats.ISO)
-         * ```
+         * @sample kotlinx.datetime.test.samples.format.LocalDateTimeFormatSamples.dateTime
          */
         public fun dateTime(format: DateTimeFormat<LocalDateTime>)
     }
@@ -227,6 +232,8 @@ public sealed interface DateTimeFormatBuilder {
          * By default, it's zero-padded to two digits, but this can be changed with [padding].
          *
          * This field has the default value of 0. If you want to omit it, use [optional].
+         *
+         * @sample kotlinx.datetime.test.samples.format.UtcOffsetFormatSamples.isoOrGmt
          */
         public fun offsetHours(padding: Padding = Padding.ZERO)
 
@@ -236,6 +243,8 @@ public sealed interface DateTimeFormatBuilder {
          * By default, it's zero-padded to two digits, but this can be changed with [padding].
          *
          * This field has the default value of 0. If you want to omit it, use [optional].
+         *
+         * @sample kotlinx.datetime.test.samples.format.UtcOffsetFormatSamples.isoOrGmt
          */
         public fun offsetMinutesOfHour(padding: Padding = Padding.ZERO)
 
@@ -245,16 +254,15 @@ public sealed interface DateTimeFormatBuilder {
          * By default, it's zero-padded to two digits, but this can be changed with [padding].
          *
          * This field has the default value of 0. If you want to omit it, use [optional].
+         *
+         * @sample kotlinx.datetime.test.samples.format.UtcOffsetFormatSamples.isoOrGmt
          */
         public fun offsetSecondsOfMinute(padding: Padding = Padding.ZERO)
 
         /**
          * An existing [DateTimeFormat] for the UTC offset part.
          *
-         * Example:
-         * ```
-         * offset(UtcOffset.Formats.FOUR_DIGITS)
-         * ```
+         * @sample kotlinx.datetime.test.samples.format.UtcOffsetFormatSamples.offset
          */
         public fun offset(format: DateTimeFormat<UtcOffset>)
     }
@@ -269,16 +277,15 @@ public sealed interface DateTimeFormatBuilder {
          *
          * When formatting, the timezone identifier is supplied as is, without any validation.
          * On parsing, [TimeZone.availableZoneIds] is used to validate the identifier.
+         *
+         * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsFormatSamples.timeZoneId
          */
         public fun timeZoneId()
 
         /**
          * An existing [DateTimeFormat].
          *
-         * Example:
-         * ```
-         * dateTimeComponents(DateTimeComponents.Formats.RFC_1123)
-         * ```
+         * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsFormatSamples.dateTimeComponents
          */
         public fun dateTimeComponents(format: DateTimeFormat<DateTimeComponents>)
     }

core/common/test/samples/format/DateTimeComponentsFormatSamples.kt

@@ -0,0 +1,46 @@
+/*
+ * Copyright 2019-2024 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.test.samples.format
+
+import kotlinx.datetime.*
+import kotlinx.datetime.format.*
+import kotlin.test.*
+
+class DateTimeComponentsFormatSamples {
+    @Test
+    fun timeZoneId() {
+        val format = DateTimeComponents.Format {
+            dateTime(LocalDateTime.Formats.ISO)
+            char('[')
+            timeZoneId()
+            char(']')
+        }
+        val formatted = format.format {
+            setDateTime(LocalDate(2021, 1, 13).atTime(9, 34, 58, 120_000_000))
+            timeZoneId = "Europe/Paris"
+        }
+        check(formatted == "2021-01-13T09:34:58.12[Europe/Paris]")
+        val parsed = format.parse("2021-01-13T09:34:58.12[Europe/Paris]")
+        check(parsed.toLocalDateTime() == LocalDate(2021, 1, 13).atTime(9, 34, 58, 120_000_000))
+        check(parsed.timeZoneId == "Europe/Paris")
+    }
+
+    @Test
+    fun dateTimeComponents() {
+        val format = DateTimeComponents.Format {
+            char('{')
+            dateTimeComponents(DateTimeComponents.Formats.RFC_1123)
+            char('}')
+        }
+        val formatted = format.format {
+            setDateTimeOffset(
+                LocalDate(2021, 1, 13).atTime(9, 34, 58, 120_000_000),
+                UtcOffset(hours = 3, minutes = 30)
+            )
+        }
+        check(formatted == "{Wed, 13 Jan 2021 09:34:58 +0330}")
+    }
+}

core/common/test/samples/format/LocalDateTimeFormatSamples.kt

@@ -0,0 +1,27 @@
+/*
+ * Copyright 2019-2024 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.test.samples.format
+
+import kotlinx.datetime.*
+import kotlinx.datetime.format.*
+import kotlin.test.*
+
+class LocalDateTimeFormatSamples {
+    @Test
+    fun dateTime() {
+        val format = DateTimeComponents.Format {
+            dateTime(LocalDateTime.Formats.ISO)
+            offset(UtcOffset.Formats.FOUR_DIGITS)
+        }
+        val formatted = format.format {
+            setDateTimeOffset(
+                LocalDate(2021, 1, 13).atTime(9, 34, 58, 120_000_000),
+                UtcOffset(hours = 2)
+            )
+        }
+        check(formatted == "2021-01-13T09:34:58.12+0200")
+    }
+}

core/common/test/samples/format/LocalTimeFormatSamples.kt

@@ -0,0 +1,54 @@
+/*
+ * Copyright 2019-2024 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.test.samples.format
+
+import kotlinx.datetime.*
+import kotlinx.datetime.format.*
+import kotlin.test.*
+
+class LocalTimeFormatSamples {
+    @Test
+    fun hhmmss() {
+        // format the local time as a single number
+        val format = LocalTime.Format {
+            hour(); minute(); second()
+            optional { char('.'); secondFraction(1, 9) }
+        }
+        val formatted = format.format(LocalTime(9, 34, 58, 120_000_000))
+        check(formatted == "093458.12")
+    }
+
+    @Test
+    fun amPm() {
+        val format = LocalTime.Format {
+            amPmHour(); char(':'); minute(); char(':'); second()
+            char(' '); amPmMarker("AM", "PM")
+        }
+        val formatted = format.format(LocalTime(9, 34, 58, 120_000_000))
+        check(formatted == "09:34:58 AM")
+    }
+
+    @Test
+    fun fixedLengthSecondFraction() {
+        val format = LocalTime.Format {
+            hour(); char(':'); minute(); char(':'); second()
+            char('.'); secondFraction(fixedLength = 3)
+        }
+        val formatted = format.format(LocalTime(9, 34, 58, 120_000_000))
+        check(formatted == "09:34:58.120")
+    }
+
+    @Test
+    fun time() {
+        val format = LocalDateTime.Format {
+            date(LocalDate.Formats.ISO)
+            char(' ')
+            time(LocalTime.Formats.ISO)
+        }
+        val formatted = format.format(LocalDateTime(2021, 1, 13, 9, 34, 58, 120_000_000))
+        check(formatted == "2021-01-13 09:34:58.12")
+    }
+}

core/common/test/samples/format/UtcOffsetFormatSamples.kt

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2019-2024 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.test.samples.format
+
+import kotlinx.datetime.*
+import kotlinx.datetime.format.*
+import kotlin.test.*
+
+class UtcOffsetFormatSamples {
+    @Test
+    fun isoOrGmt() {
+        val format = UtcOffset.Format {
+            // if the offset is zero, `GMT` is printed
+            optional("GMT") {
+                offsetHours(); char(':'); offsetMinutesOfHour()
+                // if seconds are zero, they are omitted
+                optional { char(':'); offsetSecondsOfMinute() }
+            }
+        }
+        check(format.format(UtcOffset.ZERO) == "GMT")
+        check(format.format(UtcOffset(hours = -2)) == "-02:00")
+        check(format.format(UtcOffset(hours = -2, minutes = -30)) == "-02:30")
+        check(format.format(UtcOffset(hours = -2, minutes = -30, seconds = -59)) == "-02:30:59")
+    }
+
+    @Test
+    fun offset() {
+        val format = DateTimeComponents.Format {
+            dateTime(LocalDateTime.Formats.ISO)
+            offset(UtcOffset.Formats.FOUR_DIGITS)
+        }
+        val formatted = format.format {
+            setDateTimeOffset(
+                LocalDate(2021, 1, 13).atTime(9, 34, 58, 120_000_000),
+                UtcOffset(hours = 2)
+            )
+        }
+        check(formatted == "2021-01-13T09:34:58.12+0200")
+    }
+}