kotlinx-datetime/kotlinx.datetime/Instant

Instant

@Serializable(with = InstantIso8601Serializer::class)

actual class Instant : Comparable<Instant> (source)

@Serializable(with = InstantIso8601Serializer::class)

expect class Instant : Comparable<Instant> (source)

A moment in time.

A point in time must be uniquely identified, so that it is independent of a time zone. For example, 1970-01-01, 00:00:00 does not represent a moment in time, since this would happen at different times in different time zones: someone in Tokyo would think its already 1970-01-01 several hours earlier than someone in Berlin would. To represent such entities, use LocalDateTime. In contrast, "the moment the clocks in London first showed 00:00 on Jan 1, 2000" is a specific moment in time, as is "1970-01-01, 00:00:00 UTC+0", and so it can be represented as an Instant.

Instant uses the UTC-SLS (smeared leap second) time scale. This time scale doesn't contain instants corresponding to leap seconds, but instead "smears" positive and negative leap seconds among the last 1000 seconds of the day when a leap second happens.

Some ways in which Instant can be acquired are:

Clock.now can be used to query the current moment for the given clock. With Clock.System, it is the current moment as the platform sees it.
Instant.parse parses an ISO-8601 string.
Instant.fromEpochMilliseconds and Instant.fromEpochSeconds construct the instant values from the amount of time since 1970-01-01T00:00:00Z (the Unix epoch).

@Serializable(with = InstantIso8601Serializer::class)

actual class Instant : Comparable<Instant> (source)

@Serializable(with = InstantIso8601Serializer::class)

actual class Instant : Comparable<Instant> (source)

Types

Companion

actual object Companion

expect object Companion

actual object Companion

Properties

epochSeconds

actual val epochSeconds: Long

expect val epochSeconds: Long

The number of seconds from the epoch instant 1970-01-01T00:00:00Z rounded down to a Long number.

actual val epochSeconds: Long

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.

nanosecondsOfSecond

actual val nanosecondsOfSecond: Int

expect val nanosecondsOfSecond: Int

The number of nanoseconds by which this instant is later than epochSeconds from the epoch instant.

actual val nanosecondsOfSecond: Int

Functions

compareTo

actual open operator override fun compareTo(other: Instant): Int

expect open operator override fun compareTo(other: Instant): Int

Compares this instant with the other instant. Returns zero if this instant represents the same moment as the other (i.e. equal to other), a negative number if this instant is earlier than the other, and a positive number if this instant is later than the other.

actual open operator override fun compareTo(other: Instant): Int

daysUntil

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

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

equals

open operator override fun equals(other: Any?): Boolean

format

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

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

hashCode

open override fun hashCode(): Int

minus

actual operator fun minus(duration: Duration): Instant

actual operator fun minus(other: Instant): Duration

expect operator fun minus(duration: Duration): Instant

Returns an instant that is the result of subtracting the specified duration from this instant.

expect operator fun minus(other: Instant): Duration

Returns the Duration between two instants: other and this.

actual operator fun minus(duration: Duration): Instant

actual operator fun minus(other: Instant): Duration

actual operator fun minus(duration: Duration): Instant

actual operator fun minus(other: Instant): Duration

minus

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

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 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 Instant.minus(value: Int, unit: DateTimeUnit, timeZone: TimeZone): Instant

monthsUntil

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

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

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 Instant.periodUntil(other: Instant, timeZone: TimeZone): DateTimePeriod

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

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

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

plus

actual operator fun plus(duration: Duration): Instant

expect operator fun plus(duration: Duration): Instant

Returns an instant that is the result of adding the specified duration to this instant.

actual operator fun plus(duration: Duration): Instant

plus

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

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

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

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

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 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 fun Instant.plus(value: Long, unit: DateTimeUnit.TimeBased): Instant

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

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

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

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

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

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

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

toEpochMilliseconds

actual fun toEpochMilliseconds(): Long

expect fun toEpochMilliseconds(): Long

Returns the number of milliseconds from the epoch instant 1970-01-01T00:00:00Z.

actual fun toEpochMilliseconds(): Long

toJavaInstant

fun Instant.toJavaInstant(): Instant

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

toJSDate

fun Instant.toJSDate(): Date

Converts the Instant to an instance of JS Date.

toLocalDateTime

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

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

Returns a civil date/time 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.

toString

actual open override fun toString(): String

expect open override fun toString(): String

Converts this instant to the ISO-8601 string representation.

actual open override fun toString(): String

until

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 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 Instant.until(other: Instant, unit: DateTimeUnit, timeZone: TimeZone): Long

yearsUntil

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

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