Local Time
The time part of LocalDateTime.
This class represents time-of-day without 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. It may not even exist or be ambiguous on days when clocks are adjusted.
The arithmetic on LocalTime values is not provided, since without accounting for the time zone transitions it may give misleading results.
Arithmetic operations
Arithmetic operations on LocalTime are not provided because they are not well-defined without a date and a time zone. See LocalDateTime for an explanation of why not accounting for time zone transitions may lead to incorrect results. To perform arithmetic operations on time values, first, obtain an Instant.
val time = LocalTime(13, 30)
val date = Clock.System.todayAt(TimeZone.currentSystemDefault())
val instant = time.atDate(date).toInstant(TimeZone.currentSystemDefault())
val instantThreeHoursLater = instant.plus(3.hours)
val timeThreeHoursLater = instantThreeHoursLater.toLocalDateTime(TimeZone.currentSystemDefault()).time
Since this pattern is extremely verbose and difficult to get right, it is recommended to work exclusively with Instant and only obtain a LocalTime when displaying the time to the user.
Platform specifics
On the JVM, there are LocalTime.toJavaLocalTime()
and java.time.LocalTime.toKotlinLocalTime()
extension functions to convert between kotlinx.datetime
and java.time
objects used for the same purpose.
Construction, serialization, and deserialization
LocalTime can be constructed directly from its components using the constructor. See sample 1.
fromSecondOfDay, fromMillisecondOfDay, and fromNanosecondOfDay can be used to obtain a LocalTime from the number of seconds, milliseconds, or nanoseconds since the start of the day, assuming that the offset from the UTC does not change during the day. toSecondOfDay, toMillisecondOfDay, and toNanosecondOfDay are the inverse operations. See sample 2.
parse and toString methods can be used to obtain a LocalTime from and convert it to a string in the ISO 8601 extended format. See sample 3.
parse and LocalTime.format both support custom formats created with Format or defined in Formats. See sample 4.
Additionally, there are several kotlinx-serialization
serializers for LocalTime:
LocalTimeIso8601Serializer for the ISO 8601 extended format,
LocalTimeComponentSerializer for an object with components.
Samples
import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.random.*
import kotlin.test.*
fun main() {
//sampleStart
// Constructing a LocalTime using its constructor
val night = LocalTime(hour = 23, minute = 13, second = 16, nanosecond = 153_200_001)
check(night.hour == 23)
check(night.minute == 13)
check(night.second == 16)
check(night.nanosecond == 153_200_001)
val noon = LocalTime(12, 0)
check(noon.hour == 12)
check(noon.minute == 0)
check(noon.second == 0)
check(noon.nanosecond == 0)
val evening = LocalTime(hour = 18, minute = 31, second = 54)
check(evening.nanosecond == 0)
//sampleEnd
}
import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.random.*
import kotlin.test.*
fun main() {
//sampleStart
// Representing a LocalTime as the number of seconds, milliseconds, or nanoseconds since the start of the day
val time = LocalTime(hour = 8, minute = 30, second = 15, nanosecond = 123_456_789)
// The number of whole seconds since the start of the day:
val timeAsSecondOfDay = time.toSecondOfDay()
check(timeAsSecondOfDay == 8 * 60 * 60 + 30 * 60 + 15)
// The number of whole milliseconds since the start of the day:
val timeAsMillisecondOfDay = time.toMillisecondOfDay()
check(timeAsMillisecondOfDay == timeAsSecondOfDay * 1_000 + 123)
// The number of nanoseconds since the start of the day:
val timeAsNanosecondOfDay = time.toNanosecondOfDay()
check(timeAsNanosecondOfDay == timeAsMillisecondOfDay * 1_000_000L + 456_789)
// The local time is completely defined by the number of nanoseconds since the start of the day:
val reconstructedTime = LocalTime.fromNanosecondOfDay(timeAsNanosecondOfDay)
check(reconstructedTime == time)
//sampleEnd
}
import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.random.*
import kotlin.test.*
fun main() {
//sampleStart
// Parsing a LocalTime from a string and formatting it back
val time = LocalTime.parse("08:30:15.1234567")
check(time == LocalTime(8, 30, 15, 123_456_700))
val formatted = time.toString()
check(formatted == "08:30:15.123456700")
//sampleEnd
}
import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.random.*
import kotlin.test.*
fun main() {
//sampleStart
// Parsing and formatting LocalTime values using a custom format
val customFormat = LocalTime.Format {
hour(); char(':'); minute(); char(':'); second()
char(','); secondFraction(fixedLength = 3)
}
val time = LocalTime(8, 30, 15, 123_456_789)
check(time.format(customFormat) == "08:30:15,123")
check(time.format(LocalTime.Formats.ISO) == "08:30:15.123456789")
//sampleEnd
}
Constructors
Constructs a LocalTime instance from the given time components.
Properties
Functions
Combines this time's components with the specified LocalDate components into a LocalDateTime value.
Combines this time's components with the specified date components into a LocalDateTime value.
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.
Formats this value using the given format. Equivalent to calling DateTimeFormat.format on format with this
.
Converts this kotlinx.datetime.LocalDateTime value to a java.time.LocalTime value.
Returns the time as a millisecond of a day, in 0 until 24 * 60 * 60 * 1_000
.
Returns the time as a nanosecond of a day, in 0 until 24 * 60 * 60 * 1_000_000_000
.
Returns the time as a second of a day, in 0 until 24 * 60 * 60
.