minus
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.
If the DateTimePeriod only contains time-based components, please consider subtracting a Duration instead, as in
Clock.System.now() - 5.hours. Then, it is not necessary to pass the timeZone.If the DateTimePeriod only has a single non-zero component (only the months or only the days), please consider using a multiple of DateTimeUnit.DAY or DateTimeUnit.MONTH, as in
Clock.System.now().minus(5, DateTimeUnit.DAY, TimeZone.currentSystemDefault()).
Throws
if this value or the results of intermediate computations are 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 a moment that's earlier than the starting point by the given length of calendar time
val period = DateTimePeriod(months = 1, days = -1) // one day short from a month earlier
val startInstant = Instant.parse("2024-03-23T16:50:41.926Z")
val afterPeriodInBerlin = startInstant.minus(period, TimeZone.of("Europe/Berlin"))
check(afterPeriodInBerlin == Instant.parse("2024-02-24T16:50:41.926Z"))
val afterPeriodInNewYork = startInstant.minus(period, TimeZone.of("America/New_York"))
check(afterPeriodInNewYork == Instant.parse("2024-02-24T17:50:41.926Z"))
//sampleEnd
}Returns a DateTimePeriod representing the difference between other and this instants.
The components of DateTimePeriod are calculated so that adding it back to the other instant results in this instant.
All components of the DateTimePeriod returned are:
Negative or zero if this instant is earlier than the other.
Positive or zero if this instant is later than the other.
Exactly zero if this instant is equal to the other.
See also
Throws
if this or other instant is too large to fit in LocalDateTime. Or (only on the JVM) if the number of months between the two dates exceeds an Int.
Samples
import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.random.*
import kotlin.test.*
import kotlin.time.Duration.Companion.hours
fun main() {
//sampleStart
// Finding a period that it would take to get from the starting instant to the ending instant
val startInstant = Instant.parse("2024-01-01T02:00:00Z")
val endInstant = Instant.parse("2024-03-01T03:15:03Z")
// In New York, we find the difference between 2023-12-31 and 2024-02-29, which is just short of two months
val periodInNewYork = endInstant.minus(startInstant, TimeZone.of("America/New_York"))
check(periodInNewYork == DateTimePeriod(months = 1, days = 29, hours = 1, minutes = 15, seconds = 3))
// In Berlin, we find the difference between 2024-01-01 and 2024-03-01, which is exactly two months
val periodInBerlin = endInstant.minus(startInstant, TimeZone.of("Europe/Berlin"))
check(periodInBerlin == DateTimePeriod(months = 2, days = 0, hours = 1, minutes = 15, seconds = 3))
//sampleEnd
}Returns an instant that is the result of subtracting the value number of the specified unit from this instant.
If the value is positive, the returned instant is earlier than this instant. If the value is negative, the returned instant is later than this instant.
The return value is clamped to the platform-specific boundaries for Instant if the result exceeds them.
Samples
import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.random.*
import kotlin.test.*
import kotlin.time.Duration.Companion.hours
fun main() {
//sampleStart
// Finding a moment that's earlier than the starting point by the given amount of real time
val instant = Instant.fromEpochSeconds(7 * 60 * 60, nanosecondAdjustment = 123_456_789)
val fiveHoursEarlier = instant.minus(5, DateTimeUnit.HOUR)
check(fiveHoursEarlier.epochSeconds == 2 * 60 * 60L)
check(fiveHoursEarlier.nanosecondsOfSecond == 123_456_789)
//sampleEnd
}Returns an instant that is the result of subtracting the value number of the specified unit from this instant in the specified timeZone.
If the value is positive, the returned instant is earlier than this instant. If the value is negative, the returned instant is later than this instant.
Note that the time zone does not need to be passed when the unit is a time-based unit. It is also not needed when subtracting date-based units from a LocalDate.
Throws
if this value or the result 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 a moment that's earlier than the starting point by the given length of calendar time
val startInstant = Instant.parse("2024-03-28T02:04:56.256Z")
val twoYearsEarlierInBerlin = startInstant.minus(2, DateTimeUnit.YEAR, TimeZone.of("Europe/Berlin"))
check(twoYearsEarlierInBerlin == Instant.parse("2022-03-28T01:04:56.256Z"))
val twoYearsEarlierInCairo = startInstant.minus(2, DateTimeUnit.YEAR, TimeZone.of("Africa/Cairo"))
check(twoYearsEarlierInCairo == Instant.parse("2022-03-28T02:04:56.256Z"))
//sampleEnd
}Returns the whole number of the specified date or time units between other and this instants in the specified timeZone.
The value returned is negative or zero if this instant is earlier than the other, and positive or zero if this instant is later than 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.
See also
for the same operation but with swapped arguments.
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 a moment that's earlier than the starting point by the given length of calendar time
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 = endInstant.minus(startInstant, 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 = endInstant.minus(startInstant, DateTimeUnit.MONTH, TimeZone.of("Europe/Berlin"))
check(monthsBetweenInBerlin == 2L)
//sampleEnd
}Returns the whole number of the specified time units between other and this instants.
The value returned is negative or zero if this instant is earlier than the other, and positive or zero if this instant is later than 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.
See also
for the same operation but with swapped arguments.
Samples
import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.random.*
import kotlin.test.*
import kotlin.time.Duration.Companion.hours
fun main() {
//sampleStart
// Finding a moment that's earlier than the starting point by a given amount of real time
val instant = Instant.fromEpochSeconds(0)
val otherInstant = Instant.fromEpochSeconds(7 * 60 * 60, nanosecondAdjustment = 123_456_789)
val hoursBetweenInstants = otherInstant.minus(instant, DateTimeUnit.HOUR)
check(hoursBetweenInstants == 7L)
//sampleEnd
}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.
See also
Throws
if this value or the results of intermediate computations are too large to fit in LocalDate.
Samples
import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.random.*
import kotlin.test.*
fun main() {
//sampleStart
// Finding a date that's a given period before another date
val startDate = LocalDate(2023, Month.JANUARY, 2)
check(startDate - DatePeriod(years = 1, months = 2, days = 3) == LocalDate(2021, Month.OCTOBER, 30))
// Step by step explanation:
// 1. Months and years are subtracted first as one step.
val intermediateDate = LocalDate(2021, Month.NOVEMBER, 2)
check(startDate.minus(14, DateTimeUnit.MONTH) == intermediateDate)
// 2. Days are subtracted.
check(intermediateDate.minus(3, DateTimeUnit.DAY) == LocalDate(2021, Month.OCTOBER, 30))
//sampleEnd
}Returns a DatePeriod representing the difference between other and this dates.
The components of DatePeriod are calculated so that adding it back to the other date results in this date.
All components of the DatePeriod returned are:
Negative or zero if this date is earlier than the other.
Positive or zero if this date is later than the other.
Exactly zero if this date is equal to the other.
See also
for the same operation with the order of arguments reversed.
Throws
if the number of months between the two dates exceeds an Int (JVM only).
Samples
import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.random.*
import kotlin.test.*
fun main() {
//sampleStart
// Finding the period between two dates
val startDate = LocalDate(2023, Month.JANUARY, 2)
val endDate = LocalDate(2024, Month.APRIL, 1)
val period = endDate - startDate
check(period == DatePeriod(years = 1, months = 2, days = 30))
//sampleEnd
}Returns a LocalDate that results from subtracting the value number of the specified unit from this date.
If the value is positive, the returned date is earlier than this date. If the value is negative, the returned date is later than this date.
The value is rounded toward zero.
Throws
if the result exceeds the boundaries of LocalDate.
Samples
import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.random.*
import kotlin.test.*
fun main() {
//sampleStart
// Subtracting a number of days or months from a date
val today = LocalDate(2024, Month.APRIL, 16)
val tenDaysAgo = today.minus(10, DateTimeUnit.DAY)
check(tenDaysAgo == LocalDate(2024, Month.APRIL, 6))
val twoMonthsAgo = today.minus(2, DateTimeUnit.MONTH)
check(twoMonthsAgo == LocalDate(2024, Month.FEBRUARY, 16))
//sampleEnd
}Returns an instant that is the result of subtracting the value number of the specified unit from this instant in the specified timeZone.
If the value is positive, the returned instant is earlier than this instant. If the value is negative, the returned instant is later than this instant.
Note that the time zone does not need to be passed when the unit is a time-based unit. It is also not needed when subtracting date-based units from a LocalDate.
If the value is positive, the returned instant is earlier than this instant. If the value is negative, the returned instant is later than this instant.
Throws
if this value or the result 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 a moment that's earlier than the starting point by the given length of calendar time
val startInstant = Instant.parse("2024-03-28T02:04:56.256Z")
val twoYearsEarlierInBerlin = startInstant.minus(2, DateTimeUnit.YEAR, TimeZone.of("Europe/Berlin"))
check(twoYearsEarlierInBerlin == Instant.parse("2022-03-28T01:04:56.256Z"))
val twoYearsEarlierInCairo = startInstant.minus(2, DateTimeUnit.YEAR, TimeZone.of("Africa/Cairo"))
check(twoYearsEarlierInCairo == Instant.parse("2022-03-28T02:04:56.256Z"))
//sampleEnd
}