kotlinx-datetime/kotlinx.datetime

Package-level declarations

Types

Clock

interface Clock

A source of Instant values.

DatePeriod

@Serializable(with = DatePeriodIso8601Serializer::class)

class DatePeriod : DateTimePeriod

A special case of DateTimePeriod that only stores the date components and has all time components equal to zero.

DateTimeArithmeticException

class DateTimeArithmeticException : RuntimeException

Thrown by datetime arithmetic operations if the result cannot be computed or represented.

DateTimePeriod

@Serializable(with = DateTimePeriodIso8601Serializer::class)

sealed class DateTimePeriod

A difference between two instants, decomposed into date and time components.

DateTimeUnit

@Serializable(with = DateTimeUnitSerializer::class)

sealed class DateTimeUnit

A unit for measuring time; for example, a second, 20 seconds, a day, a month, or a quarter.

DayOfWeek

actual enum DayOfWeek : Enum<DayOfWeek>

expect enum DayOfWeek : Enum<DayOfWeek>

The enumeration class representing the days of the week.

actual typealias DayOfWeek = java.time.DayOfWeek

actual enum DayOfWeek : Enum<DayOfWeek>

FixedOffsetTimeZone

@Serializable(with = FixedOffsetTimeZoneSerializer::class)

actual class FixedOffsetTimeZone : TimeZone

@Serializable(with = FixedOffsetTimeZoneSerializer::class)

expect class FixedOffsetTimeZone : TimeZone

A time zone that is known to always have the same offset from UTC.

@Serializable(with = FixedOffsetTimeZoneSerializer::class)

actual class FixedOffsetTimeZone : TimeZone

@Serializable(with = FixedOffsetTimeZoneSerializer::class)

actual class FixedOffsetTimeZone : TimeZone

IllegalTimeZoneException

class IllegalTimeZoneException : IllegalArgumentException

Thrown when attempting to construct a TimeZone with an invalid ID or unavailable rules.

Instant

@Serializable(with = InstantIso8601Serializer::class)

actual class Instant : Comparable<Instant>

@Serializable(with = InstantIso8601Serializer::class)

expect class Instant : Comparable<Instant>

A moment in time.

@Serializable(with = InstantIso8601Serializer::class)

actual class Instant : Comparable<Instant>

@Serializable(with = InstantIso8601Serializer::class)

actual class Instant : Comparable<Instant>

LocalDate

@Serializable(with = LocalDateIso8601Serializer::class)

actual class LocalDate(year: Int, monthNumber: Int, dayOfMonth: Int) : Comparable<LocalDate>

@Serializable(with = LocalDateIso8601Serializer::class)

expect class LocalDate(year: Int, monthNumber: Int, dayOfMonth: Int) : Comparable<LocalDate>

The date part of LocalDateTime.

@Serializable(with = LocalDateIso8601Serializer::class)

actual class LocalDate(year: Int, monthNumber: Int, dayOfMonth: Int) : Comparable<LocalDate>

@Serializable(with = LocalDateIso8601Serializer::class)

actual class LocalDate(val year: Int, val monthNumber: Int, val dayOfMonth: Int) : Comparable<LocalDate>

LocalDateTime

@Serializable(with = LocalDateTimeIso8601Serializer::class)

actual class LocalDateTime(date: LocalDate, time: LocalTime) : Comparable<LocalDateTime>

@Serializable(with = LocalDateTimeIso8601Serializer::class)

expect class LocalDateTime(date: LocalDate, time: LocalTime) : Comparable<LocalDateTime>

The representation of a specific civil date and time without a reference to a particular time zone.

@Serializable(with = LocalDateTimeIso8601Serializer::class)

actual class LocalDateTime(date: LocalDate, time: LocalTime) : Comparable<LocalDateTime>

@Serializable(with = LocalDateTimeIso8601Serializer::class)

actual class LocalDateTime(val date: LocalDate, val time: LocalTime) : Comparable<LocalDateTime>

LocalTime

@Serializable(with = LocalTimeIso8601Serializer::class)

actual class LocalTime(hour: Int, minute: Int, second: Int, nanosecond: Int) : Comparable<LocalTime>

@Serializable(with = LocalTimeIso8601Serializer::class)

expect class LocalTime(hour: Int, minute: Int, second: Int = 0, nanosecond: Int = 0) : Comparable<LocalTime>

The time part of LocalDateTime.

@Serializable(with = LocalTimeIso8601Serializer::class)

actual class LocalTime(hour: Int, minute: Int, second: Int, nanosecond: Int) : Comparable<LocalTime>

@Serializable(with = LocalTimeIso8601Serializer::class)

actual class LocalTime(val hour: Int, val minute: Int, val second: Int, val nanosecond: Int) : Comparable<LocalTime>

Month

actual enum Month : Enum<Month>

expect enum Month : Enum<Month>

The enumeration class representing the 12 months of the year.

actual typealias Month = java.time.Month

actual enum Month : Enum<Month>

TimeZone

@Serializable(with = TimeZoneSerializer::class)

actual open class TimeZone

@Serializable(with = TimeZoneSerializer::class)

expect open class TimeZone

A time zone, provides the conversion between Instant and LocalDateTime values using a collection of rules specifying which LocalDateTime value corresponds to each Instant.

@Serializable(with = TimeZoneSerializer::class)

actual open class TimeZone

@Serializable(with = TimeZoneSerializer::class)

actual open class TimeZone

UtcOffset

@Serializable(with = UtcOffsetSerializer::class)

actual class UtcOffset

@Serializable(with = UtcOffsetSerializer::class)

expect class UtcOffset

An offset from UTC.

@Serializable(with = UtcOffsetSerializer::class)

actual class UtcOffset(zoneOffset: ZoneOffset)

@Serializable(with = UtcOffsetSerializer::class)

actual class UtcOffset

Properties

isDistantFuture

val Instant.isDistantFuture: Boolean

Returns true if the instant is Instant.DISTANT_FUTURE or later.

isDistantPast

val Instant.isDistantPast: Boolean

Returns true if the instant is Instant.DISTANT_PAST or earlier.

isoDayNumber

val DayOfWeek.isoDayNumber: Int

The ISO 8601 number of the given day of the week. Monday is 1, Sunday is 7.

number

val Month.number: Int

The number of the Month. January is 1, December is 12.

Functions

asTimeSource

@ExperimentalTime

fun Clock.asTimeSource(): TimeSource.WithComparableMarks

Returns a TimeSource that uses this Clock to mark a time instant and to find the amount of time elapsed since that mark.

asTimeZone

fun UtcOffset.asTimeZone(): FixedOffsetTimeZone

Returns the fixed-offset time zone with the given UTC offset.

atDate

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, 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.

atStartOfDayIn

actual fun LocalDate.atStartOfDayIn(timeZone: TimeZone): Instant

expect fun LocalDate.atStartOfDayIn(timeZone: TimeZone): Instant

Returns an instant that corresponds to the start of this date in the specified timeZone.

actual fun LocalDate.atStartOfDayIn(timeZone: TimeZone): Instant

atTime

fun LocalDate.atTime(time: LocalTime): LocalDateTime

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

fun LocalDate.atTime(hour: Int, minute: Int, second: Int = 0, nanosecond: Int = 0): LocalDateTime

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

DateTimePeriod

fun DateTimePeriod(years: Int = 0, months: Int = 0, days: Int = 0, hours: Int = 0, minutes: Int = 0, seconds: Int = 0, nanoseconds: Long = 0): DateTimePeriod

Constructs a new DateTimePeriod. If all the time components are zero, returns a DatePeriod.

DayOfWeek

fun DayOfWeek(isoDayNumber: Int): DayOfWeek

Returns the DayOfWeek instance for the given ISO 8601 weekday number. Monday is 1, and Sunday is 7.

daysUntil

actual fun LocalDate.daysUntil(other: LocalDate): Int

expect fun LocalDate.daysUntil(other: LocalDate): Int

Returns the number of whole days between two dates.

fun Instant.daysUntil(other: Instant, timeZone: TimeZone): Int

Returns the number of whole days between two instants in the specified timeZone.

actual fun LocalDate.daysUntil(other: LocalDate): Int

format

fun LocalDate.format(format: DateTimeFormat<LocalDate>): String

fun LocalDateTime.format(format: DateTimeFormat<LocalDateTime>): String

fun LocalTime.format(format: DateTimeFormat<LocalTime>): String

fun UtcOffset.format(format: DateTimeFormat<UtcOffset>): String

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

fun Instant.format(format: DateTimeFormat<DateTimeComponents>, offset: UtcOffset = UtcOffset.ZERO): String

Formats this value using the given format using the given offset.

minus

actual fun LocalDate.minus(value: Int, unit: DateTimeUnit.DateBased): LocalDate

actual fun Instant.minus(value: Int, unit: DateTimeUnit, timeZone: TimeZone): Instant

operator fun LocalDate.minus(period: DatePeriod): LocalDate

Returns a date that results from subtracting components of DatePeriod from this date. The components are subtracted in the order from the largest units to the smallest: first years and months, then days.

operator fun LocalDate.minus(other: LocalDate): DatePeriod

Returns a DatePeriod representing the difference between other and this dates.

fun Instant.minus(value: Int, unit: DateTimeUnit.TimeBased): Instant

fun Instant.minus(value: Long, unit: DateTimeUnit.TimeBased): Instant

Returns an instant that is the result of subtracting the value number of the specified unit from this instant.

fun Instant.minus(period: DateTimePeriod, timeZone: TimeZone): Instant

Returns an instant that is the result of subtracting components of DateTimePeriod from this instant. The components are subtracted in the order from the largest units to the smallest, i.e., from years to nanoseconds.

fun Instant.minus(other: Instant, unit: DateTimeUnit.TimeBased): Long

Returns the whole number of the specified time units between other and this instants.

fun Instant.minus(other: Instant, timeZone: TimeZone): DateTimePeriod

Returns a DateTimePeriod representing the difference between other and this instants.

expect fun LocalDate.minus(value: Int, unit: DateTimeUnit.DateBased): LocalDate

fun LocalDate.minus(value: Long, unit: DateTimeUnit.DateBased): LocalDate

Returns a LocalDate that results from subtracting the value number of the specified unit from this date.

expect fun Instant.minus(value: Int, unit: DateTimeUnit, timeZone: TimeZone): Instant

fun Instant.minus(value: Long, unit: DateTimeUnit, timeZone: TimeZone): Instant

Returns an instant that is the result of subtracting the value number of the specified unit from this instant in the specified timeZone.

fun Instant.minus(other: Instant, unit: DateTimeUnit, timeZone: TimeZone): Long

Returns the whole number of the specified date or time units between other and this instants in the specified timeZone.

actual fun LocalDate.minus(value: Int, unit: DateTimeUnit.DateBased): LocalDate

actual fun Instant.minus(value: Int, unit: DateTimeUnit, timeZone: TimeZone): Instant

actual fun LocalDate.minus(value: Int, unit: DateTimeUnit.DateBased): LocalDate

actual fun Instant.minus(value: Int, unit: DateTimeUnit, timeZone: TimeZone): Instant

Month

fun Month(number: Int): Month

Returns the Month instance for the given month number. January is 1, December is 12.

monthsUntil

actual fun LocalDate.monthsUntil(other: LocalDate): Int

expect fun LocalDate.monthsUntil(other: LocalDate): Int

Returns the number of whole months between two dates.

fun Instant.monthsUntil(other: Instant, timeZone: TimeZone): Int

Returns the number of whole months between two instants in the specified timeZone.

actual fun LocalDate.monthsUntil(other: LocalDate): Int

offsetAt

actual fun TimeZone.offsetAt(instant: Instant): UtcOffset

expect fun TimeZone.offsetAt(instant: Instant): UtcOffset

Finds the offset from UTC this time zone has at the specified instant of physical time.

actual fun TimeZone.offsetAt(instant: Instant): UtcOffset

offsetIn

fun Instant.offsetIn(timeZone: TimeZone): UtcOffset

Finds the offset from UTC the specified timeZone has at this instant of physical time.

periodUntil

actual fun LocalDate.periodUntil(other: LocalDate): DatePeriod

actual fun Instant.periodUntil(other: Instant, timeZone: TimeZone): DateTimePeriod

expect fun LocalDate.periodUntil(other: LocalDate): DatePeriod

Returns a DatePeriod representing the difference between this and other dates.

expect fun Instant.periodUntil(other: Instant, timeZone: TimeZone): DateTimePeriod

Returns a DateTimePeriod representing the difference between this and other instants.

actual fun LocalDate.periodUntil(other: LocalDate): DatePeriod

actual fun Instant.periodUntil(other: Instant, timeZone: TimeZone): DateTimePeriod

actual fun LocalDate.periodUntil(other: LocalDate): DatePeriod

actual fun Instant.periodUntil(other: Instant, timeZone: TimeZone): DateTimePeriod

plus

actual operator fun LocalDate.plus(period: DatePeriod): LocalDate

actual fun Instant.plus(value: Long, unit: DateTimeUnit.TimeBased): Instant

actual fun Instant.plus(period: DateTimePeriod, timeZone: TimeZone): Instant

actual fun LocalDate.plus(value: Int, unit: DateTimeUnit.DateBased): LocalDate

actual fun LocalDate.plus(value: Long, unit: DateTimeUnit.DateBased): LocalDate

actual fun Instant.plus(value: Int, unit: DateTimeUnit, timeZone: TimeZone): Instant

actual fun Instant.plus(value: Long, unit: DateTimeUnit, timeZone: TimeZone): Instant

operator fun DatePeriod.plus(other: DatePeriod): DatePeriod

Adds two DatePeriod instances.

operator fun DateTimePeriod.plus(other: DateTimePeriod): DateTimePeriod

Adds two DateTimePeriod instances.

expect operator fun LocalDate.plus(period: DatePeriod): LocalDate

Returns a date that results from adding components of DatePeriod to this date. The components are added in the order from the largest units to the smallest: first years and months, then days.

fun Instant.plus(value: Int, unit: DateTimeUnit.TimeBased): Instant

expect fun Instant.plus(value: Long, unit: DateTimeUnit.TimeBased): Instant

Returns an instant that is the result of adding the value number of the specified unit to this instant.

expect fun Instant.plus(period: DateTimePeriod, timeZone: TimeZone): Instant

Returns an instant that is the result of adding components of DateTimePeriod to this instant. The components are added in the order from the largest units to the smallest, i.e., from years to nanoseconds.

expect fun LocalDate.plus(value: Int, unit: DateTimeUnit.DateBased): LocalDate

expect fun LocalDate.plus(value: Long, unit: DateTimeUnit.DateBased): LocalDate

Returns a LocalDate that results from adding the value number of the specified unit to this date.

expect fun Instant.plus(value: Int, unit: DateTimeUnit, timeZone: TimeZone): Instant

expect fun Instant.plus(value: Long, unit: DateTimeUnit, timeZone: TimeZone): Instant

Returns an instant that is the result of adding the value number of the specified unit to this instant in the specified timeZone.

actual operator fun LocalDate.plus(period: DatePeriod): LocalDate

actual fun Instant.plus(value: Long, unit: DateTimeUnit.TimeBased): Instant

actual fun Instant.plus(period: DateTimePeriod, timeZone: TimeZone): Instant

actual fun LocalDate.plus(value: Int, unit: DateTimeUnit.DateBased): LocalDate

actual fun LocalDate.plus(value: Long, unit: DateTimeUnit.DateBased): LocalDate

actual fun Instant.plus(value: Int, unit: DateTimeUnit, timeZone: TimeZone): Instant

actual fun Instant.plus(value: Long, unit: DateTimeUnit, timeZone: TimeZone): Instant

actual operator fun LocalDate.plus(period: DatePeriod): LocalDate

actual fun Instant.plus(value: Long, unit: DateTimeUnit.TimeBased): Instant

actual fun Instant.plus(period: DateTimePeriod, timeZone: TimeZone): Instant

actual fun LocalDate.plus(value: Int, unit: DateTimeUnit.DateBased): LocalDate

actual fun LocalDate.plus(value: Long, unit: DateTimeUnit.DateBased): LocalDate

actual fun Instant.plus(value: Int, unit: DateTimeUnit, timeZone: TimeZone): Instant

actual fun Instant.plus(value: Long, unit: DateTimeUnit, timeZone: TimeZone): Instant

toDateTimePeriod

fun Duration.toDateTimePeriod(): DateTimePeriod

Constructs a DateTimePeriod from a Duration.

todayIn

fun Clock.todayIn(timeZone: TimeZone): LocalDate

Returns the current date at the given time zone, according to this Clock.

toInstant

actual fun LocalDateTime.toInstant(timeZone: TimeZone): Instant

actual fun LocalDateTime.toInstant(offset: UtcOffset): Instant

expect fun LocalDateTime.toInstant(timeZone: TimeZone): Instant

Returns an instant that corresponds to this civil datetime value in the specified timeZone.

expect fun LocalDateTime.toInstant(offset: UtcOffset): Instant

Returns an instant that corresponds to this civil datetime value that happens at the specified UTC offset.

actual fun LocalDateTime.toInstant(timeZone: TimeZone): Instant

actual fun LocalDateTime.toInstant(offset: UtcOffset): Instant

actual fun LocalDateTime.toInstant(timeZone: TimeZone): Instant

actual fun LocalDateTime.toInstant(offset: UtcOffset): Instant

toJavaInstant

fun Instant.toJavaInstant(): Instant

Converts this kotlinx.datetime.Instant value to a java.time.Instant value.

toJavaLocalDate

fun LocalDate.toJavaLocalDate(): LocalDate

Converts this kotlinx.datetime.LocalDate value to a java.time.LocalDate value.

toJavaLocalDateTime

fun LocalDateTime.toJavaLocalDateTime(): LocalDateTime

Converts this kotlinx.datetime.LocalDateTime value to a java.time.LocalDateTime value.

toJavaLocalTime

fun LocalTime.toJavaLocalTime(): LocalTime

Converts this kotlinx.datetime.LocalDateTime value to a java.time.LocalTime value.

toJavaPeriod

fun DatePeriod.toJavaPeriod(): Period

Converts this kotlinx.datetime.DatePeriod value to a java.time.Period value.

toJavaZoneId

fun TimeZone.toJavaZoneId(): ZoneId

Converts this kotlinx.datetime.TimeZone value to a java.time.ZoneId value.

toJavaZoneOffset

fun FixedOffsetTimeZone.toJavaZoneOffset(): ZoneOffset

Converts this kotlinx.datetime.FixedOffsetTimeZone value to a java.time.ZoneOffset value.

fun UtcOffset.toJavaZoneOffset(): ZoneOffset

Converts this kotlinx.datetime.UtcOffset value to a java.time.ZoneOffset value.

toJSDate

fun Instant.toJSDate(): Date

Converts the Instant to an instance of JS Date.

toKotlinDatePeriod

fun Period.toKotlinDatePeriod(): DatePeriod

Converts this java.time.Period value to a kotlinx.datetime.DatePeriod value.

toKotlinFixedOffsetTimeZone

fun ZoneOffset.toKotlinFixedOffsetTimeZone(): FixedOffsetTimeZone

Converts this java.time.ZoneOffset value to a kotlinx.datetime.FixedOffsetTimeZone value.

toKotlinInstant

fun <Error class: unknown class>.toKotlinInstant(): Instant

Converts the NSDate to the corresponding Instant.

fun Date.toKotlinInstant(): Instant

Converts the JS Date to the corresponding Instant.

fun Instant.toKotlinInstant(): Instant

Converts this java.time.Instant value to a kotlinx.datetime.Instant value.

toKotlinLocalDate

fun LocalDate.toKotlinLocalDate(): LocalDate

Converts this java.time.LocalDate value to a kotlinx.datetime.LocalDate value.

toKotlinLocalDateTime

fun LocalDateTime.toKotlinLocalDateTime(): LocalDateTime

Converts this java.time.LocalDateTime value to a kotlinx.datetime.LocalDateTime value.

toKotlinLocalTime

fun LocalTime.toKotlinLocalTime(): LocalTime

Converts this java.time.LocalTime value to a kotlinx.datetime.LocalTime value.

toKotlinTimeZone

fun <Error class: unknown class>.toKotlinTimeZone(): TimeZone

Converts the NSTimeZone to the corresponding TimeZone.

fun ZoneId.toKotlinTimeZone(): TimeZone

Converts this java.time.ZoneId value to a kotlinx.datetime.TimeZone value.

toKotlinUtcOffset

fun ZoneOffset.toKotlinUtcOffset(): UtcOffset

Converts this java.time.ZoneOffset value to a kotlinx.datetime.UtcOffset value.

toLocalDateTime

actual fun Instant.toLocalDateTime(timeZone: TimeZone): LocalDateTime

expect fun Instant.toLocalDateTime(timeZone: TimeZone): LocalDateTime

Returns a civil datetime value that this instant has in the specified timeZone.

actual fun Instant.toLocalDateTime(timeZone: TimeZone): LocalDateTime

toNSDate

fun Instant.toNSDate(): <Error class: unknown class>

Converts the Instant to an instance of NSDate.

toNSDateComponents

fun LocalDate.toNSDateComponents(): <Error class: unknown class>

fun LocalDateTime.toNSDateComponents(): <Error class: unknown class>

Converts the given LocalDate to NSDateComponents.

toNSTimeZone

fun TimeZone.toNSTimeZone(): <Error class: unknown class>

Converts the TimeZone to NSTimeZone.

until

actual fun LocalDate.until(other: LocalDate, unit: DateTimeUnit.DateBased): Int

actual fun Instant.until(other: Instant, unit: DateTimeUnit, timeZone: TimeZone): Long

fun Instant.until(other: Instant, unit: DateTimeUnit.TimeBased): Long

Returns the whole number of the specified time units between this and other instants.

expect fun LocalDate.until(other: LocalDate, unit: DateTimeUnit.DateBased): Int

Returns the whole number of the specified date units between this and other dates.

expect fun Instant.until(other: Instant, unit: DateTimeUnit, timeZone: TimeZone): Long

Returns the whole number of the specified date or time units between this and other instants in the specified timeZone.

actual fun LocalDate.until(other: LocalDate, unit: DateTimeUnit.DateBased): Int

actual fun Instant.until(other: Instant, unit: DateTimeUnit, timeZone: TimeZone): Long

actual fun LocalDate.until(other: LocalDate, unit: DateTimeUnit.DateBased): Int

actual fun Instant.until(other: Instant, unit: DateTimeUnit, timeZone: TimeZone): Long

UtcOffset

actual fun UtcOffset(hours: Int? = null, minutes: Int? = null, seconds: Int? = null): UtcOffset

expect fun UtcOffset(hours: Int? = null, minutes: Int? = null, seconds: Int? = null): UtcOffset

Constructs a UtcOffset from hours, minutes, and seconds components.

actual fun UtcOffset(hours: Int? = null, minutes: Int? = null, seconds: Int? = null): UtcOffset

yearsUntil

actual fun LocalDate.yearsUntil(other: LocalDate): Int

expect fun LocalDate.yearsUntil(other: LocalDate): Int

Returns the number of whole years between two dates.

fun Instant.yearsUntil(other: Instant, timeZone: TimeZone): Int

Returns the number of whole years between two instants in the specified timeZone.

actual fun LocalDate.yearsUntil(other: LocalDate): Int