plus
Adds two DateTimePeriod instances.
Pitfall: given three instants, adding together the periods between the first and the second and between the second and the third does not necessarily equal the period between the first and the third.
Throws
if arithmetic overflow happens.
Adds two DatePeriod instances.
Pitfall: given three dates, adding together the periods between the first and the second and between the second and the third does not necessarily equal the period between the first and the third.
Throws
if arithmetic overflow happens.
Returns an instant that is the result of adding the value number of the specified unit to this instant.
If the value is positive, the returned instant is later than this instant. If the value is negative, 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.
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 later than the starting point by the given amount of real time
val instant = Instant.fromEpochSeconds(7 * 60 * 60, nanosecondAdjustment = 123_456_789)
val fiveHoursLater = instant.plus(5, DateTimeUnit.HOUR)
check(fiveHoursLater.epochSeconds == 12 * 60 * 60L)
check(fiveHoursLater.nanosecondsOfSecond == 123_456_789)
//sampleEnd
}Returns an instant that is the result of adding components of DateTimePeriod to this instant. The components are added 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 adding a Duration instead, as in
Clock.System.now() + 5.hours. Then, it will not be 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, like in
Clock.System.now().plus(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 later than the starting point by the given length of calendar time
val startInstant = Instant.parse("2024-03-09T07:16:39.688Z")
val period = DateTimePeriod(months = 1, days = -1) // one day short from a month later
val afterPeriodInBerlin = startInstant.plus(period, TimeZone.of("Europe/Berlin"))
check(afterPeriodInBerlin == Instant.parse("2024-04-08T06:16:39.688Z"))
val afterPeriodInSydney = startInstant.plus(period, TimeZone.of("Australia/Sydney"))
check(afterPeriodInSydney == Instant.parse("2024-04-08T08:16:39.688Z"))
//sampleEnd
}Returns an instant that is the result of adding the value number of the specified unit to this instant in the specified timeZone.
If the value is positive, the returned instant is later than this instant. If the value is negative, the returned instant is earlier 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 adding date-based units to 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 later than the starting point by the given length of calendar time
val startInstant = Instant.parse("2024-04-05T22:51:45.586Z")
val twoYearsLaterInBerlin = startInstant.plus(2, DateTimeUnit.YEAR, TimeZone.of("Europe/Berlin"))
check(twoYearsLaterInBerlin == Instant.parse("2026-04-05T22:51:45.586Z"))
val twoYearsLaterInSydney = startInstant.plus(2, DateTimeUnit.YEAR, TimeZone.of("Australia/Sydney"))
check(twoYearsLaterInSydney == Instant.parse("2026-04-05T23:51:45.586Z"))
//sampleEnd
}Returns an instant that is the result of adding the value number of the specified unit to this instant in the specified timeZone.
If the value is positive, the returned instant is later than this instant. If the value is negative, the returned instant is earlier 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 adding date-based units to 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 later than the starting point by the given length of calendar time
val startInstant = Instant.parse("2024-04-05T22:51:45.586Z")
val twoYearsLaterInBerlin = startInstant.plus(2, DateTimeUnit.YEAR, TimeZone.of("Europe/Berlin"))
check(twoYearsLaterInBerlin == Instant.parse("2026-04-05T22:51:45.586Z"))
val twoYearsLaterInSydney = startInstant.plus(2, DateTimeUnit.YEAR, TimeZone.of("Australia/Sydney"))
check(twoYearsLaterInSydney == Instant.parse("2026-04-05T23:51:45.586Z"))
//sampleEnd
}Returns a LocalDate that results from adding the value number of the specified unit to this date.
If the value is positive, the returned date is later than this date. If the value is negative, the returned date is earlier 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
// Adding a number of days or months to a date
val today = LocalDate(2024, Month.APRIL, 16)
val tenDaysLater = today.plus(10, DateTimeUnit.DAY)
check(tenDaysLater == LocalDate(2024, Month.APRIL, 26))
val twoMonthsLater = today.plus(2, DateTimeUnit.MONTH)
check(twoMonthsLater == LocalDate(2024, Month.JUNE, 16))
//sampleEnd
}Returns a date that results from adding components of DatePeriod to this date. The components are added 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 after another date
val startDate = LocalDate(2021, Month.OCTOBER, 30)
check(startDate + DatePeriod(years = 1, months = 2, days = 3) == LocalDate(2023, Month.JANUARY, 2))
// Step by step explanation:
// 1. Months and years are added first as one step.
val intermediateDate = LocalDate(2022, Month.DECEMBER, 30)
check(startDate.plus(14, DateTimeUnit.MONTH) == intermediateDate)
// 2. Days are added.
check(intermediateDate.plus(3, DateTimeUnit.DAY) == LocalDate(2023, Month.JANUARY, 2))
//sampleEnd
}