DateTimeUnit

A unit for measuring time; for example, a second, 20 seconds, a day, a month, or a quarter.

This class is used to express arithmetic operations like addition and subtraction on datetime values: for example, adding 10 days to a datetime value, subtracting 5 hours from a datetime value, or finding the number of 30-second intervals between two datetime values.

Interaction with other entities

Any DateTimeUnit can be used with Instant.plus or Instant.minus to find an instant that is some number of units away from the given instant. Also, Instant.until can be used to find the number of the given units between two instants.

DateTimeUnit.TimeBased can be used in the Instant operations without specifying the time zone because DateTimeUnit.TimeBased is defined in terms of the passage of real-time and is independent of the time zone. Note that a calendar day is not considered identical to 24 hours, so using it does require specifying the time zone. See DateTimeUnit.DayBased for an explanation.

DateTimeUnit.DateBased units can be used in the LocalDate operations: LocalDate.plus, LocalDate.minus, and LocalDate.until.

Arithmetic operations on LocalDateTime are not provided. Please see the LocalDateTime documentation for details.

DateTimePeriod is a combination of DateTimeUnit values of every kind, used to express periods like "two days and three hours". DatePeriod is specifically a combination of DateTimeUnit.DateBased values. DateTimePeriod is more flexible than DateTimeUnit because it can express a combination of values with different kinds of units. However, in exchange, the duration of time between two Instant or LocalDate values can be measured in terms of some DateTimeUnit, but not DateTimePeriod or DatePeriod.

Construction, serialization, and deserialization

See the predefined constants for time units, like DateTimeUnit.NANOSECOND, DateTimeUnit.DAY, DateTimeUnit.MONTH, and others.

Two ways are provided to create custom DateTimeUnit instances:

• By multiplying an existing unit on the right by an integer scalar, for example, DateTimeUnit.MICROSECOND * 10.

• By constructing an instance manually with TimeBased, DayBased, or MonthBased, for example, DateTimeUnit.TimeBased(nanoseconds = 10_000).

Also, DateTimeUnit can be serialized and deserialized using kotlinx.serialization: DateTimeUnitSerializer, DateBasedDateTimeUnitSerializer, DayBasedDateTimeUnitSerializer, MonthBasedDateTimeUnitSerializer, and TimeBasedDateTimeUnitSerializer are provided, with varying levels of specificity of the type they handle.

Samples

import kotlinx.datetime.*
import kotlin.test.*
import kotlin.time.Duration.Companion.hours

fun main() { 
   //sampleStart 
   // Constructing various measurement units
check(DateTimeUnit.HOUR == DateTimeUnit.TimeBased(nanoseconds = 60 * 60 * 1_000_000_000L))
check(DateTimeUnit.WEEK == DateTimeUnit.DayBased(days = 7))
check(DateTimeUnit.WEEK * 2 == DateTimeUnit.DayBased(days = 14))
check(DateTimeUnit.CENTURY == DateTimeUnit.MonthBased(months = 12 * 100)) 
   //sampleEnd
}

Inheritors