Add LocalTime (#187)

Author: bishiboosh

README.md

@@ -36,6 +36,7 @@ The library provides the basic set of types for working with date and time:
 - `Clock` to obtain the current instant;
 - `LocalDateTime` to represent date and time components without a reference to the particular time zone; 
 - `LocalDate` to represent the components of date only;
+- `LocalTime` to represent the components of time only;
 - `TimeZone` and `FixedOffsetTimeZone` provide time zone information to convert between `Instant` and `LocalDateTime`;
 - `Month` and `DayOfWeek` enums;
 - `DateTimePeriod` to represent a difference between two instants decomposed into date and time units;
@@ -61,6 +62,8 @@ Here is some basic advice on how to choose which of the date-carrying types to u
   Also, use `LocalDateTime` to decode an `Instant` to its local date-time components for display and UIs.
 
 - Use `LocalDate` to represent a date of the event that does not have a specific time associated with it (like a birth date).
+
+- Use `LocalTime` to represent a time of the event that does not have a specific date associated with it.
 
 ## Operations
 
@@ -143,14 +146,31 @@ Note, that today's date really depends on the time zone in which you're observin
 val knownDate = LocalDate(2020, 2, 21)
 ```
 
+### Getting local time components
+
+`LocalTime` type represents local time without date. You can obtain it from `Instant`
+by converting it to `LocalDateTime` and taking its `time` property.
+
+```kotlin
+val now: Instant = Clock.System.now()
+val thisTime: LocalTime = now.toLocalDateTime(TimeZone.currentSystemDefault()).time
+```
+
+`LocalTime` can be constructed from four components, hour, minute, second and nanosecond:
+```kotlin
+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)
+```
+
 ### Converting instant to and from unix time
 
 An `Instant` can be converted to a number of milliseconds since the Unix/POSIX epoch with the `toEpochMilliseconds()` function.
 To convert back, use `Instant.fromEpochMilliseconds(Long)` companion object function.
 
 ### Converting instant and local date/time to and from string
 
-Currently, `Instant`, `LocalDateTime`, and `LocalDate` only support ISO-8601 format.
+Currently, `Instant`, `LocalDateTime`, `LocalDate` and `LocalTime` only support 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. 
 
@@ -168,10 +188,14 @@ where it feels more convenient:
 
 `LocalDate` uses format with just year, month, and date components, e.g. `2010-06-01`.
 
+`LocalTime` uses 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()
 ```
 
 ### Instant arithmetic

core/common/src/LocalDate.kt

@@ -113,6 +113,14 @@ public fun String.toLocalDate(): LocalDate = LocalDate.parse(this)
 public fun LocalDate.atTime(hour: Int, minute: Int, second: Int = 0, nanosecond: Int = 0): LocalDateTime =
     LocalDateTime(year, monthNumber, dayOfMonth, hour, minute, second, nanosecond)
 
+/**
+ * Combines this date's components with the specified [LocalTime] components into a [LocalDateTime] value.
+ *
+ * For finding an instant that corresponds to the start of a date in a particular time zone consider using
+ * [LocalDate.atStartOfDayIn] function because a day does not always start at the fixed time 0:00:00.
+ */
+public fun LocalDate.atTime(time: LocalTime): LocalDateTime = atTime(time.hour, time.minute, time.second, time.nanosecond)
+
 
 /**
  * Returns a date that is the result of adding components of [DatePeriod] to this date. The components are

core/common/src/LocalDateTime.kt

@@ -107,6 +107,9 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
     /** Returns the date part of this date/time value. */
     public val date: LocalDate
 
+    /** Returns the time part of this date/time value. */
+    public val time: LocalTime
+
     /**
      * Compares `this` date/time value with the [other] date/time value.
      * Returns zero if this value is equal to the other,

core/common/src/LocalTime.kt

@@ -0,0 +1,113 @@
+/*
+ * Copyright 2019-2022 JetBrains s.r.o.
+ * 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
+
+import kotlinx.datetime.serializers.LocalTimeIso8601Serializer
+import kotlinx.serialization.Serializable
+
+/**
+ * The time part of [LocalDateTime].
+ *
+ * This class represents time-of-day without a referencing a specific date.
+ * To reconstruct a full [LocalDateTime], representing civil date and time, [LocalTime] needs to be
+ * combined with [LocalDate] via [LocalDate.atTime] or [LocalTime.atDate].
+ *
+ * Also, [LocalTime] does not reference a particular time zone.
+ * Therefore, even on the same date, [LocalTime] denotes different moments of time.
+ * For example, `18:43` happens at different moments in Berlin and in Tokyo.
+ *
+ * The arithmetic on [LocalTime] values is not provided, since without accounting for the time zone
+ * transitions it may give misleading results.
+ */
+@Serializable(LocalTimeIso8601Serializer::class)
+public expect class LocalTime : Comparable<LocalTime> {
+    public companion object {
+
+        /**
+         * 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.500`
+         * - `18:43:00.123456789`
+         *
+         * @throws IllegalArgumentException if the text cannot be parsed or the boundaries of [LocalTime] are
+         * exceeded.
+         */
+        public fun parse(isoString: String): LocalTime
+
+        internal val MIN: LocalTime
+        internal val MAX: LocalTime
+    }
+
+    /**
+     * Constructs a [LocalTime] instance from the given time components.
+     *
+     * The supported ranges of components:
+     * - [hour] `0..23`
+     * - [minute] `0..59`
+     * - [second] `0..59`
+     * - [nanosecond] `0..999_999_999`
+     *
+     * @throws IllegalArgumentException if any parameter is out of range.
+     */
+    public constructor(hour: Int, minute: Int, second: Int = 0, nanosecond: Int = 0)
+
+    /** Returns the hour-of-day time component of this time value. */
+    public val hour: Int
+    /** Returns the minute-of-hour time component of this time value. */
+    public val minute: Int
+    /** Returns the second-of-minute time component of this time value. */
+    public val second: Int
+    /** Returns the nanosecond-of-second time component of this time value. */
+    public val nanosecond: Int
+
+    /**
+     * Compares `this` time value with the [other] time value.
+     * Returns zero if this value is equal to the other, a negative number if this value occurs earlier
+     * in the course of a typical day than the other, and a positive number if this value occurs
+     * later in the course of a typical day than the other.
+     *
+     * Note that, on days when there is a time overlap (for example, due to the daylight saving time
+     * transitions in autumn), a "lesser" wall-clock reading can, in fact, happen later than the
+     * "greater" one.
+     */
+    public override operator fun compareTo(other: LocalTime): Int
+
+    /**
+     * Converts this time value to the ISO-8601 string representation.
+     *
+     * @see LocalDateTime.parse
+     */
+    public override fun toString(): String
+}
+
+/**
+ * Converts this string representing a time value in ISO-8601 format to a [LocalTime] value.
+ *
+ * See [LocalTime.parse] for examples of time string representations.
+ *
+ * @throws IllegalArgumentException if the text cannot be parsed or the boundaries of [LocalTime] are exceeded.
+ */
+public fun String.toLocalTime(): LocalTime = LocalTime.parse(this)
+
+/**
+ * Combines this time's components with the specified date components into a [LocalDateTime] value.
+ */
+public fun LocalTime.atDate(year: Int, monthNumber: Int, dayOfMonth: Int = 0): LocalDateTime =
+    LocalDateTime(year, monthNumber, dayOfMonth, hour, minute, second, nanosecond)
+
+/**
+ * Combines this time's components with the specified date components into a [LocalDateTime] value.
+ */
+public fun LocalTime.atDate(year: Int, month: Month, dayOfMonth: Int = 0): LocalDateTime =
+    LocalDateTime(year, month, dayOfMonth, hour, minute, second, nanosecond)
+
+/**
+ * Combines this time's components with the specified [LocalDate] components into a [LocalDateTime] value.
+ */
+public fun LocalTime.atDate(date: LocalDate): LocalDateTime = atDate(date.year, date.monthNumber, date.dayOfMonth)

core/common/src/serializers/LocalTimeSerializers.kt

@@ -0,0 +1,83 @@
+/*
+ * Copyright 2019-2022 JetBrains s.r.o.
+ * 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.serializers
+
+import kotlinx.datetime.*
+import kotlinx.serialization.*
+import kotlinx.serialization.descriptors.*
+import kotlinx.serialization.encoding.*
+
+/**
+ * A serializer for [LocalTime] that uses the ISO-8601 representation.
+ *
+ * JSON example: `"12:01:03.999"`
+ *
+ * @see LocalDate.parse
+ * @see LocalDate.toString
+ */
+public object LocalTimeIso8601Serializer : KSerializer<LocalTime> {
+
+    override val descriptor: SerialDescriptor =
+        PrimitiveSerialDescriptor("LocalTime", PrimitiveKind.STRING)
+
+    override fun deserialize(decoder: Decoder): LocalTime =
+        LocalTime.parse(decoder.decodeString())
+
+    override fun serialize(encoder: Encoder, value: LocalTime) {
+        encoder.encodeString(value.toString())
+    }
+}
+
+/**
+ * A serializer for [LocalTime] that represents a value as its components.
+ *
+ * JSON example: `{"hour":12,"minute":1,"second":3,"nanosecond":999}`
+ */
+public object LocalTimeComponentSerializer : KSerializer<LocalTime> {
+
+    override val descriptor: SerialDescriptor =
+        buildClassSerialDescriptor("LocalTime") {
+            element<Short>("hour")
+            element<Short>("minute")
+            element<Short>("second", isOptional = true)
+            element<Int>("nanosecond", isOptional = true)
+        }
+
+    @Suppress("INVISIBLE_MEMBER") // to be able to throw `MissingFieldException`
+    override fun deserialize(decoder: Decoder): LocalTime =
+        decoder.decodeStructure(descriptor) {
+            var hour: Short? = null
+            var minute: Short? = null
+            var second: Short = 0
+            var nanosecond = 0
+            loop@while (true) {
+                when (val index = decodeElementIndex(descriptor)) {
+                    0 -> hour = decodeShortElement(descriptor, 0)
+                    1 -> minute = decodeShortElement(descriptor, 1)
+                    2 -> second = decodeShortElement(descriptor, 2)
+                    3 -> nanosecond = decodeIntElement(descriptor, 3)
+                    CompositeDecoder.DECODE_DONE -> break@loop // https://youtrack.jetbrains.com/issue/KT-42262
+                    else -> throw SerializationException("Unexpected index: $index")
+                }
+            }
+            if (hour == null) throw MissingFieldException("hour")
+            if (minute == null) throw MissingFieldException("minute")
+            LocalTime(hour.toInt(), minute.toInt(), second.toInt(), nanosecond)
+        }
+
+    override fun serialize(encoder: Encoder, value: LocalTime) {
+        encoder.encodeStructure(descriptor) {
+            encodeShortElement(descriptor, 0, value.hour.toShort())
+            encodeShortElement(descriptor, 1, value.minute.toShort())
+            if (value.second != 0 || value.nanosecond != 0) {
+                encodeShortElement(descriptor, 2, value.second.toShort())
+                if (value.nanosecond != 0) {
+                    encodeIntElement(descriptor, 3, value.nanosecond)
+                }
+            }
+        }
+    }
+}

core/common/test/LocalDateTest.kt

@@ -62,6 +62,8 @@ class LocalDateTest {
     fun atTime() {
         val date = LocalDate(2016, Month.FEBRUARY, 29)
         val datetime = date.atTime(12, 1, 59)
+        val datetimeWithLocalTime = date.atTime(LocalTime(12, 1, 59))
+        assertEquals(datetime, datetimeWithLocalTime)
         checkComponents(datetime, 2016, 2, 29, 12, 1, 59)
         checkLocalDateTimePart(date, datetime)
     }