kotlinx-datetime/kotlinx.datetime/LocalTime

LocalTime

@Serializable(with = LocalTimeSerializer::class)
actual class LocalTime : 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
Content copied to clipboard

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.

A non-throwing version of the constructor is the orNull function.

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, parseOrNull, 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, parseOrNull, and LocalTime.format all 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
}
Content copied to clipboard
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
}
Content copied to clipboard
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
}
Content copied to clipboard
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
}
Content copied to clipboard
@Serializable(with = LocalTimeSerializer::class)
expect class LocalTime : 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
Content copied to clipboard

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.

A non-throwing version of the constructor is the orNull function.

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, parseOrNull, 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, parseOrNull, and LocalTime.format all 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
}
Content copied to clipboard
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
}
Content copied to clipboard
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
}
Content copied to clipboard
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
}
Content copied to clipboard
@Serializable(with = LocalTimeSerializer::class)
actual class LocalTime : Comparable<LocalTime> , Serializable(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
Content copied to clipboard

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.

A non-throwing version of the constructor is the orNull function.

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, parseOrNull, 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, parseOrNull, and LocalTime.format all 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
}
Content copied to clipboard
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
}
Content copied to clipboard
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
}
Content copied to clipboard
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
}
Content copied to clipboard

Constructors

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

Constructs a LocalTime instance from the given time components.

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)

Constructs a LocalTime instance from the given time components.

Types

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

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

expect object Formats

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

actual object Formats

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

Properties

Link copied to clipboard
actual val hour: Int

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

expect val hour: Int

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

actual val hour: Int

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

Link copied to clipboard
actual val minute: Int

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

expect val minute: Int

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

actual val minute: Int

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

Link copied to clipboard
actual val nanosecond: Int

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

expect val nanosecond: Int

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

actual val nanosecond: Int

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

Link copied to clipboard
actual val second: Int

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

expect val second: Int

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

actual val second: Int

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

Functions

Link copied to clipboard
fun LocalTime.atDate(date: LocalDate): LocalDateTime

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

fun LocalTime.atDate(year: Int, month: Int, day: Int): LocalDateTime
fun LocalTime.atDate(year: Int, month: Month, day: Int): 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

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.

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

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.

Link copied to clipboard
open operator override fun equals(other: Any?): Boolean
open operator override fun equals(other: Any?): Boolean
Link copied to clipboard
fun LocalTime.format(format: DateTimeFormat<LocalTime>): String

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

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

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

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

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

Link copied to clipboard
actual fun toNanosecondOfDay(): Long

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

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

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

Link copied to clipboard
actual fun toSecondOfDay(): Int

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

expect fun toSecondOfDay(): Int

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

actual fun toSecondOfDay(): Int

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

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

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

expect open override fun toString(): String

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

actual open override fun toString(): String

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