Match 'plus' with the corresponding 'minus' functions

Author: dkhalanskyjb

core/commonMain/src/DateTimePeriod.kt

@@ -67,6 +67,9 @@ sealed class DateTimePeriod {
         return result
     }
 
+    internal operator fun unaryMinus(): DateTimePeriod =
+        DateTimePeriod(-years, -months, -days, -hours, -minutes, -seconds, -nanoseconds)
+
     // TODO: parsing from iso string
 }
 

core/commonMain/src/Instant.kt

@@ -173,6 +173,15 @@ public fun String.toInstant(): Instant = Instant.parse(this)
  */
 public expect fun Instant.plus(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.
+ *
+ * @throws DateTimeArithmeticException if this value or the results of intermediate computations are too large to fit in
+ * [LocalDateTime].
+ */
+public fun Instant.minus(period: DateTimePeriod, timeZone: TimeZone): Instant = plus(-period, timeZone)
+
 /**
  * Returns a [DateTimePeriod] representing the difference between `this` and [other] instants.
  *
@@ -282,6 +291,17 @@ public fun Instant.minus(other: Instant, timeZone: TimeZone): DateTimePeriod =
  */
 public expect fun Instant.plus(unit: DateTimeUnit, timeZone: TimeZone): Instant
 
+/**
+ * Returns an instant that is the result of subtracting one [unit] from this instant
+ * in the specified [timeZone].
+ *
+ * The returned instant is earlier than this instant.
+ *
+ * @throws DateTimeArithmeticException if this value or the result is too large to fit in [LocalDateTime].
+ */
+public fun Instant.minus(unit: DateTimeUnit, timeZone: TimeZone): Instant =
+    plus(-1, unit, timeZone)
+
 /**
  * Returns an instant that is the result of adding one [unit] to this instant.
  *
@@ -292,6 +312,16 @@ public expect fun Instant.plus(unit: DateTimeUnit, timeZone: TimeZone): Instant
 public fun Instant.plus(unit: DateTimeUnit.TimeBased): Instant =
     plus(1L, unit)
 
+/**
+ * Returns an instant that is the result of subtracting one [unit] from this instant.
+ *
+ * The returned instant is earlier than this instant.
+ *
+ * The return value is clamped to the platform-specific boundaries for [Instant] if the result exceeds them.
+ */
+public fun Instant.minus(unit: DateTimeUnit.TimeBased): Instant =
+    plus(-1L, unit)
+
 /**
  * Returns an instant that is the result of adding the [value] number of the specified [unit] to this instant
  * in the specified [timeZone].
@@ -303,6 +333,18 @@ public fun Instant.plus(unit: DateTimeUnit.TimeBased): Instant =
  */
 public expect fun Instant.plus(value: Int, 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].
+ *
+ * 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 DateTimeArithmeticException if this value or the result is too large to fit in [LocalDateTime].
+ */
+public fun Instant.minus(value: Int, unit: DateTimeUnit, timeZone: TimeZone): Instant =
+    plus(-value, unit, timeZone)
+
 /**
  * Returns an instant that is the result of adding the [value] number of the specified [unit] to this instant.
  *
@@ -314,6 +356,17 @@ public expect fun Instant.plus(value: Int, unit: DateTimeUnit, timeZone: TimeZon
 public fun Instant.plus(value: Int, unit: DateTimeUnit.TimeBased): Instant =
     plus(value.toLong(), unit)
 
+/**
+ * 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.
+ */
+public fun Instant.minus(value: Int, unit: DateTimeUnit.TimeBased): Instant =
+    plus(-value.toLong(), unit)
+
 /**
  * Returns an instant that is the result of adding the [value] number of the specified [unit] to this instant
  * in the specified [timeZone].
@@ -325,6 +378,17 @@ public fun Instant.plus(value: Int, unit: DateTimeUnit.TimeBased): Instant =
  */
 public expect fun Instant.plus(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].
+ *
+ * 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 DateTimeArithmeticException if this value or the result is too large to fit in [LocalDateTime].
+ */
+public fun Instant.minus(value: Long, unit: DateTimeUnit, timeZone: TimeZone) = plus(-value, unit, timeZone)
+
 /**
  * Returns an instant that is the result of adding the [value] number of the specified [unit] to this instant.
  *
@@ -335,6 +399,16 @@ public expect fun Instant.plus(value: Long, unit: DateTimeUnit, timeZone: TimeZo
  */
 public expect fun Instant.plus(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.
+ *
+ * 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.
+ */
+public fun Instant.minus(value: Long, unit: DateTimeUnit.TimeBased): Instant = plus(-value, unit)
+
 /**
  * Returns the whole number of the specified date or time [units][unit] between [other] and `this` instants
  * in the specified [timeZone].

core/commonMain/src/LocalDate.kt

@@ -110,6 +110,16 @@ public fun LocalDate.atTime(hour: Int, minute: Int, second: Int = 0, nanosecond:
  */
 expect operator fun LocalDate.plus(period: DatePeriod): LocalDate
 
+/**
+ * Returns a date that is the result of subtracting components of [DatePeriod] from this date. The components are
+ * subtracted in the order from the largest units to the smallest, i.e. from years to days.
+ *
+ * @see LocalDate.periodUntil
+ * @throws DateTimeArithmeticException if this value or the results of intermediate computations are too large to fit in
+ * [LocalDate].
+ */
+public operator fun LocalDate.minus(period: DatePeriod): LocalDate = plus(-period as DatePeriod)
+
 /**
  * Returns a [DatePeriod] representing the difference between `this` and [other] dates.
  *
@@ -186,6 +196,15 @@ public expect fun LocalDate.yearsUntil(other: LocalDate): Int
  */
 public expect fun LocalDate.plus(unit: DateTimeUnit.DateBased): LocalDate
 
+/**
+ * Returns a [LocalDate] that is the result of subtracting one [unit] from this date.
+ *
+ * The returned date is earlier than this date.
+ *
+ * @throws DateTimeArithmeticException if the result exceeds the boundaries of [LocalDate].
+ */
+public fun LocalDate.minus(unit: DateTimeUnit.DateBased): LocalDate = plus(-1, unit)
+
 /**
  * Returns a [LocalDate] that is the result of adding the [value] number of the specified [unit] to this date.
  *
@@ -196,6 +215,16 @@ public expect fun LocalDate.plus(unit: DateTimeUnit.DateBased): LocalDate
  */
 public expect fun LocalDate.plus(value: Int, unit: DateTimeUnit.DateBased): LocalDate
 
+/**
+ * Returns a [LocalDate] that is the result of 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.
+ *
+ * @throws DateTimeArithmeticException if the result exceeds the boundaries of [LocalDate].
+ */
+public fun LocalDate.minus(value: Int, unit: DateTimeUnit.DateBased): LocalDate = plus(-value, unit)
+
 /**
  * Returns a [LocalDate] that is the result of adding the [value] number of the specified [unit] to this date.
  *
@@ -205,3 +234,13 @@ public expect fun LocalDate.plus(value: Int, unit: DateTimeUnit.DateBased): Loca
  * @throws DateTimeArithmeticException if the result exceeds the boundaries of [LocalDate].
  */
 public expect fun LocalDate.plus(value: Long, unit: DateTimeUnit.DateBased): LocalDate
+
+/**
+ * Returns a [LocalDate] that is the result of 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.
+ *
+ * @throws DateTimeArithmeticException if the result exceeds the boundaries of [LocalDate].
+ */
+public fun LocalDate.minus(value: Long, unit: DateTimeUnit.DateBased): LocalDate = plus(-value, unit)

core/commonTest/src/InstantTest.kt

@@ -100,6 +100,9 @@ class InstantTest {
                 val diff = instant2.minus(instant1, timeUnit, zone)
                 assertEquals(instant2 - instant1, timeUnit.duration * diff.toDouble())
                 assertEquals(instant2, instant1.plus(diff, timeUnit, zone))
+                assertEquals(instant1, instant2.minus(diff, timeUnit, zone))
+                assertEquals(instant2, instant1.plus(diff, timeUnit))
+                assertEquals(instant1, instant2.minus(diff, timeUnit))
             }
         }
 
@@ -109,12 +112,14 @@ class InstantTest {
         val instant2 = instant1.plus(DateTimePeriod(hours = 24), zone)
         checkComponents(instant2.toLocalDateTime(zone), 2019, 10, 28, 1, 59)
         expectBetween(instant1, instant2, 24, DateTimeUnit.HOUR)
+        assertEquals(instant1, instant2.minus(DateTimePeriod(hours = 24), zone))
 
         val instant3 = instant1.plus(DateTimeUnit.DAY, zone)
         checkComponents(instant3.toLocalDateTime(zone), 2019, 10, 28, 2, 59)
         expectBetween(instant1, instant3, 25, DateTimeUnit.HOUR)
         expectBetween(instant1, instant3, 1, DateTimeUnit.DAY)
         assertEquals(1, instant1.daysUntil(instant3, zone))
+        assertEquals(instant1.minus(DateTimeUnit.HOUR), instant2.minus(DateTimeUnit.DAY, zone))
 
         val instant4 = instant1.plus(14, DateTimeUnit.MONTH, zone)
         checkComponents(instant4.toLocalDateTime(zone), 2020, 12, 27, 2, 59)
@@ -124,19 +129,27 @@ class InstantTest {
         expectBetween(instant1, instant4, 61, DateTimeUnit.WEEK)
         expectBetween(instant1, instant4, 366 + 31 + 30, DateTimeUnit.DAY)
         expectBetween(instant1, instant4, (366 + 31 + 30) * 24 + 1, DateTimeUnit.HOUR)
-
+        /* TODO: make this pass on Darwin-based systems.
+         * Since the Darwin implementation of `offset_at_datetime` can't utilize the preferred offset,
+         * when there's overlap, the implementation always assumes that the used offset is the one before the
+         * transition. However, it's not always the case, as seen here. In practice, this is a problem in
+         * scenarios where the destination of an arithmetic operation on datetimes is an overlap, and the source
+         * datetime is outside the daylight saving time. */
+        // assertEquals(instant1.plus(DateTimeUnit.HOUR), instant4.minus(14, DateTimeUnit.MONTH, zone))
 
         val period = DateTimePeriod(days = 1, hours = 1)
         val instant5 = instant1.plus(period, zone)
         checkComponents(instant5.toLocalDateTime(zone), 2019, 10, 28, 3, 59)
         assertEquals(period, instant1.periodUntil(instant5, zone))
         assertEquals(period, instant5.minus(instant1, zone))
         assertEquals(26.hours, instant5.minus(instant1))
+        assertEquals(instant1.plus(DateTimeUnit.HOUR), instant5.minus(period, zone))
 
         val instant6 = instant1.plus(23, DateTimeUnit.HOUR, zone)
         checkComponents(instant6.toLocalDateTime(zone), 2019, 10, 28, 0, 59)
         expectBetween(instant1, instant6, 23, DateTimeUnit.HOUR)
         expectBetween(instant1, instant6, 0, DateTimeUnit.DAY)
+        assertEquals(instant1, instant6.minus(23, DateTimeUnit.HOUR, zone))
     }
 
     @Test

core/commonTest/src/LocalDateTest.kt

@@ -91,6 +91,9 @@ class LocalDateTest {
         checkComponents(startDate.plus(1, DateTimeUnit.DAY), 2016, 3, 1)
         checkComponents(startDate.plus(DateTimeUnit.YEAR), 2017, 2, 28)
         checkComponents(startDate + DatePeriod(years = 4), 2020, 2, 29)
+        assertEquals(startDate, startDate.plus(DateTimeUnit.DAY).minus(DateTimeUnit.DAY))
+        assertEquals(startDate, startDate.plus(3, DateTimeUnit.DAY).minus(3, DateTimeUnit.DAY))
+        assertEquals(startDate, startDate + DatePeriod(years = 4) - DatePeriod(years = 4))
 
         checkComponents(LocalDate.parse("2016-01-31") + DatePeriod(months = 1), 2016, 2, 29)