LocalTime

@Serializable(with = LocalTimeIso8601Serializer::class)
actual class LocalTime(hour: Int, minute: Int, second: Int, nanosecond: Int) : Comparable<LocalTime> (source)
@Serializable(with = LocalTimeIso8601Serializer::class)
expect class LocalTime(hour: Int, minute: Int, second: Int = 0, nanosecond: Int = 0) : Comparable<LocalTime> (source)

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:

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
}
@Serializable(with = LocalTimeIso8601Serializer::class)
actual class LocalTime(hour: Int, minute: Int, second: Int, nanosecond: Int) : Comparable<LocalTime> (source)
@Serializable(with = LocalTimeIso8601Serializer::class)
actual class LocalTime(val hour: Int, val minute: Int, val second: Int, val nanosecond: Int) : Comparable<LocalTime> (source)

Constructors

Link copied to clipboard
actual constructor(hour: Int, minute: Int, second: Int, nanosecond: Int)
expect constructor(hour: Int, minute: Int, second: Int = 0, nanosecond: Int = 0)

Constructs a LocalTime instance from the given time components.

actual constructor(hour: Int, minute: Int, second: Int, nanosecond: Int)
actual constructor(hour: Int, minute: Int, second: Int, nanosecond: Int)

Types

Link copied to clipboard
actual object Companion
expect object Companion
actual object Companion
actual object Companion
Link copied to clipboard
actual object Formats
expect object Formats

A collection of predefined formats for parsing and formatting LocalDateTime values.

actual object Formats
actual object Formats

Properties

Link copied to clipboard
actual val hour: Int
expect val hour: Int

Returns the hour-of-day (0..23) time component of this time value.

actual val hour: Int
actual val hour: Int
Link copied to clipboard
actual val minute: Int
expect val minute: Int

Returns the minute-of-hour (0..59) time component of this time value.

actual val minute: Int
actual val minute: Int
Link copied to clipboard
actual val nanosecond: Int
expect val nanosecond: Int

Returns the nanosecond-of-second (0..999_999_999) time component of this time value.

actual val nanosecond: Int
actual val nanosecond: Int
Link copied to clipboard
actual val second: Int
expect val second: Int

Returns the second-of-minute (0..59) time component of this time value.

actual val second: Int
actual val second: Int

Functions

Link copied to clipboard

Combines this time's components with the specified LocalDate components into a LocalDateTime value.

fun LocalTime.atDate(year: Int, monthNumber: Int, dayOfMonth: Int = 0): LocalDateTime
fun LocalTime.atDate(year: Int, month: Month, dayOfMonth: Int = 0): LocalDateTime

Combines this time's components with the specified date components into a LocalDateTime value.

Link copied to clipboard
actual open operator override fun compareTo(other: LocalTime): Int
expect open operator override fun compareTo(other: LocalTime): 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.

actual open operator override fun compareTo(other: LocalTime): Int
actual open operator override fun compareTo(other: LocalTime): Int
equals
Link copied to clipboard
open operator override fun equals(other: Any?): Boolean
open operator override fun equals(other: Any?): Boolean
open operator override fun equals(other: Any?): Boolean
Link copied to clipboard

Formats this value using the given format. Equivalent to calling DateTimeFormat.format on format with this.

hashCode
Link copied to clipboard
open override fun hashCode(): Int
open override fun hashCode(): Int
open override fun hashCode(): Int
Link copied to clipboard
Link copied to clipboard
actual fun toMillisecondOfDay(): Int
expect fun toMillisecondOfDay(): Int

Returns the time as a millisecond of a day, in 0 until 24 * 60 * 60 * 1_000.

actual fun toMillisecondOfDay(): Int
actual fun toMillisecondOfDay(): Int
Link copied to clipboard
actual fun toNanosecondOfDay(): Long
expect fun toNanosecondOfDay(): Long

Returns the time as a nanosecond of a day, in 0 until 24 * 60 * 60 * 1_000_000_000.

actual fun toNanosecondOfDay(): Long
actual fun toNanosecondOfDay(): Long
Link copied to clipboard
actual fun toSecondOfDay(): Int
expect fun toSecondOfDay(): Int

Returns the time as a second of a day, in 0 until 24 * 60 * 60.

actual fun toSecondOfDay(): Int
actual fun toSecondOfDay(): Int
Link copied to clipboard
actual open override fun toString(): String
expect open override fun toString(): String

Converts this time value to the extended ISO 8601 string representation.

actual open override fun toString(): String
actual open override fun toString(): String