Add rounding operators

core/src/commonMain/kotlin/io/islandtime/ZonedDateTime.kt

@@ -501,7 +501,7 @@ class ZonedDateTime private constructor(
  * Create a [ZonedDateTime] from a local date and time.
  *
  * Due to daylight savings time transitions, there a few complexities to be aware of. If the local time falls within a
- * gap (meaning it doesn't exist), it will adjusted forward by the length of the gap. If it falls within an overlap
+ * gap (meaning it doesn't exist), it will be adjusted forward by the length of the gap. If it falls within an overlap
  * (meaning the local time exists twice), the earlier offset will be used.
  */
 @Suppress("FunctionName")
@@ -520,7 +520,7 @@ fun ZonedDateTime(
  * Create a [ZonedDateTime] from a local date and time.
  *
  * Due to daylight savings time transitions, there a few complexities to be aware of. If the local time falls within a
- * gap (meaning it doesn't exist), it will adjusted forward by the length of the gap. If it falls within an overlap
+ * gap (meaning it doesn't exist), it will be adjusted forward by the length of the gap. If it falls within an overlap
  * (meaning the local time exists twice), the earlier offset will be used.
  */
 @Suppress("FunctionName")
@@ -539,7 +539,7 @@ fun ZonedDateTime(
  * Create a [ZonedDateTime] from a local date and time.
  *
  * Due to daylight savings time transitions, there a few complexities to be aware of. If the local time falls within a
- * gap (meaning it doesn't exist), it will adjusted forward by the length of the gap. If it falls within an overlap
+ * gap (meaning it doesn't exist), it will be adjusted forward by the length of the gap. If it falls within an overlap
  * (meaning the local time exists twice), the earlier offset will be used.
  */
 @Suppress("FunctionName")
@@ -557,7 +557,7 @@ fun ZonedDateTime(
  * Create a [ZonedDateTime] from a local date and time.
  *
  * Due to daylight savings time transitions, there a few complexities to be aware of. If the local time falls within a
- * gap (meaning it doesn't exist), it will adjusted forward by the length of the gap. If it falls within an overlap
+ * gap (meaning it doesn't exist), it will be adjusted forward by the length of the gap. If it falls within an overlap
  * (meaning the local time exists twice), the earlier offset will be used.
  */
 @Suppress("FunctionName")
@@ -567,7 +567,7 @@ fun ZonedDateTime(date: Date, time: Time, zone: TimeZone) = ZonedDateTime.fromLo
  * Create a [ZonedDateTime] from a local date and time.
  *
  * Due to daylight savings time transitions, there a few complexities to be aware of. If the local time falls within a
- * gap (meaning it doesn't exist), it will adjusted forward by the length of the gap. If it falls within an overlap
+ * gap (meaning it doesn't exist), it will be adjusted forward by the length of the gap. If it falls within an overlap
  * (meaning the local time exists twice), the earlier offset will be used.
  */
 @Suppress("FunctionName")
@@ -582,7 +582,7 @@ infix fun Instant.at(zone: TimeZone) = ZonedDateTime.fromSecondOfUnixEpoch(secon
  * Combine a local date and time with a time zone to create a [ZonedDateTime].
  *
  * Due to daylight savings time transitions, there a few complexities to be aware of. If the local time falls within a
- * gap (meaning it doesn't exist), it will adjusted forward by the length of the gap. If it falls within an overlap
+ * gap (meaning it doesn't exist), it will be adjusted forward by the length of the gap. If it falls within an overlap
  * (meaning the local time exists twice), the earlier offset will be used.
  */
 infix fun DateTime.at(zone: TimeZone) = ZonedDateTime.fromLocal(this, zone)

core/src/commonMain/kotlin/io/islandtime/measures/Duration.kt

@@ -3,6 +3,7 @@ package io.islandtime.measures
 import io.islandtime.base.DateTimeField
 import io.islandtime.internal.*
 import io.islandtime.measures.Duration.Companion.create
+import io.islandtime.measures.TimeUnit.*
 import io.islandtime.measures.internal.plusWithOverflow
 import io.islandtime.parser.DateTimeParseResult
 import io.islandtime.parser.DateTimeParser
@@ -69,70 +70,115 @@ class Duration private constructor(
      * Convert this duration into the number of whole milliseconds represented by it.
      * @throws ArithmeticException if the duration cannot be represented without overflow
      */
-    val inMilliseconds
+    val inMilliseconds: LongMilliseconds
         get() = seconds.inMilliseconds + nanosecondAdjustment.inMilliseconds.toLongMilliseconds()
 
     /**
      * Convert this duration into the number of whole microseconds represented by it.
      * @throws ArithmeticException if the duration cannot be represented without overflow
      */
-    val inMicroseconds
+    val inMicroseconds: LongMicroseconds
         get() = seconds.inMicroseconds + nanosecondAdjustment.inMicroseconds.toLongMicroseconds()
 
     /**
      * Convert this duration into [LongNanoseconds].
      * @throws ArithmeticException if the duration cannot be represented without overflow
      */
-    val inNanoseconds
+    val inNanoseconds: LongNanoseconds
         get() = seconds.inNanoseconds + nanosecondAdjustment
 
+    /**
+     * Return this duration, rounded down to match the precision of a given [unit].
+     */
+    fun truncatedTo(unit: TimeUnit): Duration {
+        return when (unit) {
+            DAYS -> create(seconds / SECONDS_PER_DAY * SECONDS_PER_DAY, 0.nanoseconds)
+            HOURS -> create(seconds / SECONDS_PER_HOUR * SECONDS_PER_HOUR, 0.nanoseconds)
+            MINUTES -> create(seconds / SECONDS_PER_MINUTE * SECONDS_PER_MINUTE, 0.nanoseconds)
+            SECONDS -> create(seconds, 0.nanoseconds)
+            MILLISECONDS -> create(
+                seconds,
+                (nanosecondAdjustment.value / NANOSECONDS_PER_MILLISECOND * NANOSECONDS_PER_MILLISECOND).nanoseconds
+            )
+            MICROSECONDS -> create(
+                seconds,
+                (nanosecondAdjustment.value / NANOSECONDS_PER_MICROSECOND * NANOSECONDS_PER_MICROSECOND).nanoseconds
+            )
+            NANOSECONDS -> this
+        }
+    }
+
     /**
      * Return this duration truncated to the number of 24-hour days.
      *
      * All unit components smaller than a day will be replaced with zero.
      */
-    fun truncatedToDays() = create(seconds / SECONDS_PER_DAY * SECONDS_PER_DAY, 0.nanoseconds)
+    @Deprecated(
+        "Use truncatedTo().",
+        ReplaceWith("truncatedTo(DAYS)", "io.islandtime.measures.TimeUnit.DAYS"),
+        DeprecationLevel.WARNING
+    )
+    fun truncatedToDays() = truncatedTo(DAYS)
 
     /**
      * Return this duration truncated to the number of whole hours.
      *
      * All unit components smaller than an hour will be replaced with zero.
      */
-    fun truncatedToHours() = create(seconds / SECONDS_PER_HOUR * SECONDS_PER_HOUR, 0.nanoseconds)
+    @Deprecated(
+        "Use truncatedTo().",
+        ReplaceWith("truncatedTo(HOURS)", "io.islandtime.measures.TimeUnit.HOURS"),
+        DeprecationLevel.WARNING
+    )
+    fun truncatedToHours() = truncatedTo(HOURS)
 
     /**
      * Return this duration truncated to the number of whole minutes.
      *
      * All unit components smaller than a minute will be replaced with zero.
      */
-    fun truncatedToMinutes() = create(seconds / SECONDS_PER_MINUTE * SECONDS_PER_MINUTE, 0.nanoseconds)
+    @Deprecated(
+        "Use truncatedTo().",
+        ReplaceWith("truncatedTo(MINUTES)", "io.islandtime.measures.TimeUnit.MINUTES"),
+        DeprecationLevel.WARNING
+    )
+    fun truncatedToMinutes() = truncatedTo(MINUTES)
 
     /**
      * Return this duration truncated to the number of whole seconds.
      *
      * All unit components smaller than a second will be replaced with zero.
      */
-    fun truncatedToSeconds() = create(seconds, 0.nanoseconds)
+    @Deprecated(
+        "Use truncatedTo().",
+        ReplaceWith("truncatedTo(SECONDS)", "io.islandtime.measures.TimeUnit.SECONDS"),
+        DeprecationLevel.WARNING
+    )
+    fun truncatedToSeconds() = truncatedTo(SECONDS)
 
     /**
      * Return this duration truncated to the number of whole milliseconds.
      *
      * All unit components smaller than a millisecond will be replaced with zero.
      */
-    fun truncatedToMilliseconds() = create(
-        seconds,
-        (nanosecondAdjustment.value / NANOSECONDS_PER_MILLISECOND * NANOSECONDS_PER_MILLISECOND).nanoseconds
+    @Deprecated(
+        "Use truncatedTo().",
+        ReplaceWith("truncatedTo(MILLISECONDS)", "io.islandtime.measures.TimeUnit.MILLISECONDS"),
+        DeprecationLevel.WARNING
     )
+    fun truncatedToMilliseconds() = truncatedTo(MILLISECONDS)
 
     /**
      * Return this duration truncated to the number of whole microseconds.
      *
      * All unit components smaller than a microsecond will be replaced with zero.
      */
-    fun truncatedToMicroseconds() = create(
-        seconds,
-        (nanosecondAdjustment.value / NANOSECONDS_PER_MICROSECOND * NANOSECONDS_PER_MICROSECOND).nanoseconds
+    @Deprecated(
+        "Use truncatedTo().",
+        ReplaceWith("truncatedTo(MICROSECONDS)", "io.islandtime.measures.TimeUnit.MICROSECONDS"),
+        DeprecationLevel.WARNING
     )
+    fun truncatedToMicroseconds() = truncatedTo(MICROSECONDS)
 
     operator fun unaryMinus() = create(-seconds, nanosecondAdjustment.negateUnchecked())
 

core/src/commonMain/kotlin/io/islandtime/measures/TimeUnit.kt

@@ -0,0 +1,14 @@
+package io.islandtime.measures
+
+/**
+ * A unit of time measurement.
+ */
+enum class TimeUnit {
+    NANOSECONDS,
+    MICROSECONDS,
+    MILLISECONDS,
+    SECONDS,
+    MINUTES,
+    HOURS,
+    DAYS
+}