Update README to include parsing and formatting

dkhalanskyjb · dkhalanskyjb · commit b5236ed1657d · 2024-02-19T16:16:01.000+03:00
diff --git a/README.md b/README.md
@@ -172,34 +172,100 @@ val hourMinute = LocalTime(hour = 12, minute = 13)
 An `Instant` can be converted to a number of milliseconds since the Unix/POSIX epoch with the `toEpochMilliseconds()` function.
 To convert back, use the companion object function `Instant.fromEpochMilliseconds(Long)`.
 
-### Converting instant and local date/time to and from string
+### Converting instant and local date/time to and from the ISO 8601 string
 
-Currently, `Instant`, `LocalDateTime`, `LocalDate` and `LocalTime` only support ISO-8601 format.
+`Instant`, `LocalDateTime`, `LocalDate` and `LocalTime` provide shortcuts for
+parsing and formatting them using the extended ISO-8601 format.
 The `toString()` function is used to convert the value to a string in that format, and 
 the `parse` function in companion object is used to parse a string representation back. 
 
-
 ```kotlin
 val instantNow = Clock.System.now()
 instantNow.toString()  // returns something like 2015-12-31T12:30:00Z
 val instantBefore = Instant.parse("2010-06-01T22:19:44.475Z")
 ```
 
-Alternatively, the `String.to...()` extension functions can be used instead of `parse`, 
-where it feels more convenient:
-
 `LocalDateTime` uses a similar format, but without `Z` UTC time zone designator in the end.
 
 `LocalDate` uses a format with just year, month, and date components, e.g. `2010-06-01`.
 
 `LocalTime` uses a format with just hour, minute, second and (if non-zero) nanosecond components, e.g. `12:01:03`.
 
 ```kotlin
-"2010-06-01T22:19:44.475Z".toInstant()
-"2010-06-01T22:19:44".toLocalDateTime()
-"2010-06-01".toLocalDate()
-"12:01:03".toLocalTime()
-"12:0:03.999".toLocalTime()
+LocalDateTime.parse("2010-06-01T22:19:44")
+LocalDate.parse("2010-06-01")
+LocalTime.parse("12:01:03")
+LocalTime.parse("12:00:03.999")
+LocalTime.parse("12:0:03.999") // fails with an IllegalArgumentException
+```
+
+### Working with other string formats
+
+When some data needs to be formatted in some format other than ISO-8601, one
+can define their own format or use some of the predefined ones:
+
+```kotlin
+// import kotlinx.datetime.format.*
+
+val dateFormat = LocalDate.Format {
+    monthNumber(padding = Padding.SPACE)
+    char('/')
+    dayOfMonth()
+    char(' ')
+    year()
+}
+
+val date = dateFormat.parse("12/24 2023")
+println(date.format(LocalDate.Formats.ISO_BASIC)) // "20231224"
+```
+
+### Parsing and formatting partial, compound or out-of-bounds data
+
+Sometimes, the required string format doesn't fully correspond to any of the
+classes `kotlinx-datetime` provides. In these cases, `DateTimeComponents`, a
+collection of all date-time fields, can be used instead.
+
+```kotlin
+// import kotlinx.datetime.format.*
+
+val yearMonth = DateTimeComponents.Format { year(); char('-'); monthNumber() }
+    .parse("2024-01")
+println(yearMonth.year)
+println(yearMonth.monthNumber)
+
+val dateTimeOffset = DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET
+    .parse("2023-01-07T23:16:15.53+02:00")
+println(dateTimeOffset.toUtcOffset()) // +02:00
+println(dateTimeOffset.toLocalDateTime()) // 2023-01-07T23:16:15.53
+```
+
+Occasionally, one can encounter strings where the values are slightly off:
+for example, `23:59:60`, where `60` is an invalid value for the second.
+`DateTimeComponents` allows parsing such values as well and then mutating them
+before conversion.
+
+```kotlin
+val time = DateTimeComponents.Format { time(LocalTime.Formats.ISO) }
+    .parse("23:59:60").apply {
+        if (second == 60) second = 59
+    }.toLocalTime()
+println(time) // 23:59:59
+```
+
+Because `DateTimeComponents` is provided specifically for parsing and
+formatting, there is no way to construct it normally. If one needs to format
+partial, complex or out-of-bounds data, the `format` function allows building
+`DateTimeComponents` specifically for formatting it:
+
+```kotlin
+DateTimeComponents.Formats.RFC_1123.format {
+    // the receiver of this lambda is DateTimeComponents
+    setDate(LocalDate(2023, 1, 7))
+    hour = 23
+    minute = 59
+    second = 60
+    setOffset(UtcOffset(hours = 2))
+} // Sat, 7 Jan 2023 23:59:60 +0200
 ```
 
 ### Instant arithmetic
diff --git a/core/common/test/ReadmeTest.kt b/core/common/test/ReadmeTest.kt
@@ -0,0 +1,171 @@
+/*
+ * 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
+
+import kotlinx.datetime.*
+import kotlinx.datetime.format.*
+import kotlin.test.*
+import kotlin.time.*
+
+/**
+ * Tests the code snippets in the README.md file.
+ */
+@Suppress("UNUSED_VARIABLE")
+class ReadmeTest {
+    @Test
+    fun testGettingCurrentMoment() {
+        val currentMoment = Clock.System.now()
+    }
+
+    @Test
+    fun testConvertingAnInstantToLocalDateAndTimeComponents() {
+        val currentMoment: Instant = Clock.System.now()
+        val datetimeInUtc: LocalDateTime = currentMoment.toLocalDateTime(TimeZone.UTC)
+        val datetimeInSystemZone: LocalDateTime = currentMoment.toLocalDateTime(TimeZone.currentSystemDefault())
+
+        val tzBerlin = TimeZone.of("Europe/Berlin")
+        val datetimeInBerlin = currentMoment.toLocalDateTime(tzBerlin)
+
+        val kotlinReleaseDateTime = LocalDateTime(2016, 2, 15, 16, 57, 0, 0)
+
+        val kotlinReleaseInstant = kotlinReleaseDateTime.toInstant(TimeZone.of("UTC+3"))
+    }
+
+    @Test
+    fun testGettingLocalDateComponents() {
+        val now: Instant = Clock.System.now()
+        val today: LocalDate = now.toLocalDateTime(TimeZone.currentSystemDefault()).date
+        // or shorter
+        val today2: LocalDate = Clock.System.todayIn(TimeZone.currentSystemDefault())
+
+        val knownDate = LocalDate(2020, 2, 21)
+    }
+
+    @Test
+    fun testGettingLocalTimeComponents() {
+        val now: Instant = Clock.System.now()
+        val thisTime: LocalTime = now.toLocalDateTime(TimeZone.currentSystemDefault()).time
+
+        val knownTime = LocalTime(hour = 23, minute = 59, second = 12)
+        val timeWithNanos = LocalTime(hour = 23, minute = 59, second = 12, nanosecond = 999)
+        val hourMinute = LocalTime(hour = 12, minute = 13)
+    }
+
+    @Test
+    fun testConvertingInstantToAndFromUnixTime() {
+        Instant.fromEpochMilliseconds(Clock.System.now().toEpochMilliseconds())
+    }
+
+    @Test
+    fun testConvertingInstantAndLocalDateTimeToAndFromIso8601String() {
+        val instantNow = Clock.System.now()
+        instantNow.toString()  // returns something like 2015-12-31T12:30:00Z
+        val instantBefore = Instant.parse("2010-06-01T22:19:44.475Z")
+
+        LocalDateTime.parse("2010-06-01T22:19:44")
+        LocalDate.parse("2010-06-01")
+        LocalTime.parse("12:01:03")
+        LocalTime.parse("12:00:03.999")
+        assertFailsWith<IllegalArgumentException> { LocalTime.parse("12:0:03.999") }
+    }
+
+    @Test
+    fun testWorkingWithOtherStringFormats() {
+        val dateFormat = LocalDate.Format {
+            monthNumber(padding = Padding.SPACE)
+            char('/')
+            dayOfMonth()
+            char(' ')
+            year()
+        }
+
+        val date = dateFormat.parse("12/24 2023")
+        assertEquals("20231224", date.format(LocalDate.Formats.ISO_BASIC))
+    }
+
+    @Test
+    fun testParsingAndFormattingPartialCompoundOrOutOfBoundsData() {
+        val yearMonth = DateTimeComponents.Format { year(); char('-'); monthNumber() }
+            .parse("2024-01")
+        assertEquals(2024, yearMonth.year)
+        assertEquals(1, yearMonth.monthNumber)
+
+        val dateTimeOffset = DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET
+            .parse("2023-01-07T23:16:15.53+02:00")
+        assertEquals("+02:00", dateTimeOffset.toUtcOffset().toString())
+        assertEquals("2023-01-07T23:16:15.530", dateTimeOffset.toLocalDateTime().toString())
+
+        val time = DateTimeComponents.Format { time(LocalTime.Formats.ISO) }
+            .parse("23:59:60").apply {
+                if (second == 60) second = 59
+            }.toLocalTime()
+        assertEquals(LocalTime(23, 59, 59), time)
+
+        assertEquals("Sat, 7 Jan 2023 23:59:60 +0200", DateTimeComponents.Formats.RFC_1123.format {
+            // the receiver of this lambda is DateTimeComponents
+            setDate(LocalDate(2023, 1, 7))
+            hour = 23
+            minute = 59
+            second = 60
+            setOffset(UtcOffset(hours = 2))
+        })
+    }
+
+    @Test
+    fun testInstantArithmetic() {
+        run {
+            val now = Clock.System.now()
+            val instantInThePast: Instant = Instant.parse("2020-01-01T00:00:00Z")
+            val durationSinceThen: Duration = now - instantInThePast
+            val equidistantInstantInTheFuture: Instant = now + durationSinceThen
+
+            val period: DateTimePeriod = instantInThePast.periodUntil(Clock.System.now(), TimeZone.UTC)
+
+            instantInThePast.yearsUntil(Clock.System.now(), TimeZone.UTC)
+            instantInThePast.monthsUntil(Clock.System.now(), TimeZone.UTC)
+            instantInThePast.daysUntil(Clock.System.now(), TimeZone.UTC)
+
+            val diffInMonths = instantInThePast.until(Clock.System.now(), DateTimeUnit.MONTH, TimeZone.UTC)
+        }
+
+        run {
+            val now = Clock.System.now()
+            val systemTZ = TimeZone.currentSystemDefault()
+            val tomorrow = now.plus(2, DateTimeUnit.DAY, systemTZ)
+            val threeYearsAndAMonthLater = now.plus(DateTimePeriod(years = 3, months = 1), systemTZ)
+        }
+    }
+
+    @Test
+    fun testDateArithmetic() {
+        val date = LocalDate(2023, 1, 7)
+        val date2 = date.plus(1, DateTimeUnit.DAY)
+        date.plus(DatePeriod(days = 1))
+        date.until(date2, DateTimeUnit.DAY)
+        date.yearsUntil(date2)
+        date.monthsUntil(date2)
+        date.daysUntil(date2)
+        date.periodUntil(date2)
+        date2 - date
+    }
+
+    @Test
+    fun testDateTimeArithmetic() {
+        val timeZone = TimeZone.of("Europe/Berlin")
+        val localDateTime = LocalDateTime.parse("2021-03-27T02:16:20")
+        val instant = localDateTime.toInstant(timeZone)
+
+        val instantOneDayLater = instant.plus(1, DateTimeUnit.DAY, timeZone)
+        val localDateTimeOneDayLater = instantOneDayLater.toLocalDateTime(timeZone)
+        assertEquals(LocalDateTime(2021, 3, 28, 3, 16, 20), localDateTimeOneDayLater)
+        // 2021-03-28T03:16:20, as 02:16:20 that day is in a time gap
+
+        val instantTwoDaysLater = instant.plus(2, DateTimeUnit.DAY, timeZone)
+        val localDateTimeTwoDaysLater = instantTwoDaysLater.toLocalDateTime(timeZone)
+        assertEquals(LocalDateTime(2021, 3, 29, 2, 16, 20), localDateTimeTwoDaysLater)
+        // 2021-03-29T02:16:20
+    }
+}
