until
Returns the whole number of the specified time units between this and other instants.
The value returned is:
Positive or zero if this instant is earlier than the other.
Negative or zero if this instant is later than the other.
Zero if this instant is equal to the other.
If the result does not fit in Long, returns Long.MAX_VALUE for a positive result or Long.MIN_VALUE for a negative result.
Samples
import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.random.*
import kotlin.test.*
import kotlin.time.Duration.Companion.hours
fun main() {
//sampleStart
// Finding the difference between two instants in terms of the given measurement unit
val instant = Instant.fromEpochSeconds(0)
val otherInstant = Instant.fromEpochSeconds(7 * 60 * 60, nanosecondAdjustment = 123_456_789)
val hoursBetweenInstants = instant.until(otherInstant, DateTimeUnit.HOUR)
check(hoursBetweenInstants == 7L)
//sampleEnd
}Returns the whole number of the specified date or time units between this and other instants in the specified timeZone.
The value returned is:
Positive or zero if this instant is earlier than the other.
Negative or zero if this instant is later than the other.
Zero if this instant is equal to the other.
If the result does not fit in Long, returns Long.MAX_VALUE for a positive result or Long.MIN_VALUE for a negative result.
Throws
if this or other instant is too large to fit in LocalDateTime.
Samples
import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.random.*
import kotlin.test.*
import kotlin.time.Duration.Companion.hours
fun main() {
//sampleStart
// Finding the difference between two instants in terms of the given calendar-based measurement unit
val startInstant = Instant.parse("2024-01-01T02:00:00Z")
val endInstant = Instant.parse("2024-03-01T02:00:00Z")
// In New York, we find the difference between 2023-12-31 and 2024-02-29, which is just short of two months
val monthsBetweenInNewYork = startInstant.until(endInstant, DateTimeUnit.MONTH, TimeZone.of("America/New_York"))
check(monthsBetweenInNewYork == 1L)
// In Berlin, we find the difference between 2024-01-01 and 2024-03-01, which is exactly two months
val monthsBetweenInBerlin = startInstant.until(endInstant, DateTimeUnit.MONTH, TimeZone.of("Europe/Berlin"))
check(monthsBetweenInBerlin == 2L)
//sampleEnd
}Returns the whole number of the specified date units between this and other dates.
The value returned is:
Positive or zero if this date is earlier than the other.
Negative or zero if this date is later than the other.
Zero if this date is equal to the other.
The value is rounded toward zero.
If the result does not fit in Int, returns Int.MAX_VALUE for a positive result or Int.MIN_VALUE for a negative result.
See also
Samples
import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.random.*
import kotlin.test.*
fun main() {
//sampleStart
// Measuring the difference between two dates in terms of the given unit
val startDate = LocalDate(2023, Month.JANUARY, 2)
val endDate = LocalDate(2024, Month.APRIL, 1)
val differenceInMonths = startDate.until(endDate, DateTimeUnit.MONTH)
check(differenceInMonths == 14)
// one year, two months, and 30 days, rounded toward zero.
//sampleEnd
}