ZonedDateTime

A date and time of day in a particular region.

ZonedDateTime takes time zone rules into account when performing calendrical calculations.

class ZonedDateTime : TimePoint<ZonedDateTime>

Types

Companion

common

object Companion

Functions

adjustedTo

common

Changes the time zone of a ZonedDateTime, adjusting the date, time, and offset such that the instant represented by it remains the same.

fun adjustedTo(newTimeZone: TimeZone): ZonedDateTime

compareTo

common

Compares this time point with another time point.

Time points can be compared to other time points based on timeline order, but aren't required to implement the Comparable interface since they don't necessarily have a natural order that's consistent with equals.

open operator override fun compareTo(other: TimePoint<*>): Int

copy

common

Returns a copy of this date-time with the values of any individual components replaced by the new values specified.

If the new date falls within a daylight savings time gap, it will be adjusted forward by the length of the gap. If it falls within an overlap, the offset value will be used if possible. The time zone takes precedence over the offset, so any provided offset value will be ignored if it is invalid within the current region.

fun copy(dateTime: DateTime, offset: UtcOffset, zone: TimeZone): ZonedDateTime

fun copy(date: Date, time: Time, offset: UtcOffset, zone: TimeZone): ZonedDateTime

fun copy(year: Int, dayOfYear: Int, hour: Int, minute: Int, second: Int, nanosecond: Int, offset: UtcOffset, zone: TimeZone): ZonedDateTime

fun copy(year: Int, month: Month, dayOfMonth: Int, hour: Int, minute: Int, second: Int, nanosecond: Int, offset: UtcOffset, zone: TimeZone): ZonedDateTime

fun copy(year: Int, monthNumber: Int, dayOfMonth: Int, hour: Int, minute: Int, second: Int, nanosecond: Int, offset: UtcOffset, zone: TimeZone): ZonedDateTime

equals

common

open operator override fun equals(other: Any?): Boolean

hashCode

common

open override fun hashCode(): Int

isSameInstantAs

common

Checks if this time point represents the same instant as other. Unlike the equals operator, equality is determined solely by timeline order.

open override fun isSameInstantAs(other: TimePoint<*>): Boolean

minus

common

Returns this date-time with period subtracted from it.

Years are added first, then months, then days. If the day exceeds the maximum month length at any step, it will be coerced into the valid range.

operator fun minus(period: Period): ZonedDateTime

operator fun minus(duration: Duration): ZonedDateTime

operator fun minus(years: IntYears): ZonedDateTime

operator fun minus(years: LongYears): ZonedDateTime

operator fun minus(months: IntMonths): ZonedDateTime

operator fun minus(months: LongMonths): ZonedDateTime

operator fun minus(weeks: IntWeeks): ZonedDateTime

operator fun minus(weeks: LongWeeks): ZonedDateTime

operator fun minus(days: IntDays): ZonedDateTime

operator fun minus(days: LongDays): ZonedDateTime

open operator override fun minus(hours: IntHours): ZonedDateTime

open operator override fun minus(hours: LongHours): ZonedDateTime

open operator override fun minus(minutes: IntMinutes): ZonedDateTime

open operator override fun minus(minutes: LongMinutes): ZonedDateTime

open operator override fun minus(seconds: IntSeconds): ZonedDateTime

open operator override fun minus(seconds: LongSeconds): ZonedDateTime

open operator override fun minus(milliseconds: IntMilliseconds): ZonedDateTime

open operator override fun minus(milliseconds: LongMilliseconds): ZonedDateTime

open operator override fun minus(microseconds: IntMicroseconds): ZonedDateTime

open operator override fun minus(microseconds: LongMicroseconds): ZonedDateTime

open operator override fun minus(nanoseconds: IntNanoseconds): ZonedDateTime

open operator override fun minus(nanoseconds: LongNanoseconds): ZonedDateTime

plus

common

Returns this date-time with period added to it.

Years are added first, then months, then days. If the day exceeds the maximum month length at any step, it will be coerced into the valid range.

operator fun plus(period: Period): ZonedDateTime

operator fun plus(duration: Duration): ZonedDateTime

operator fun plus(years: IntYears): ZonedDateTime

operator fun plus(years: LongYears): ZonedDateTime

operator fun plus(months: IntMonths): ZonedDateTime

operator fun plus(months: LongMonths): ZonedDateTime

operator fun plus(weeks: IntWeeks): ZonedDateTime

operator fun plus(weeks: LongWeeks): ZonedDateTime

operator fun plus(days: IntDays): ZonedDateTime

operator fun plus(days: LongDays): ZonedDateTime

open operator override fun plus(hours: IntHours): ZonedDateTime

open operator override fun plus(hours: LongHours): ZonedDateTime

open operator override fun plus(minutes: IntMinutes): ZonedDateTime

open operator override fun plus(minutes: LongMinutes): ZonedDateTime

open operator override fun plus(seconds: IntSeconds): ZonedDateTime

open operator override fun plus(seconds: LongSeconds): ZonedDateTime

open operator override fun plus(milliseconds: IntMilliseconds): ZonedDateTime

open operator override fun plus(milliseconds: LongMilliseconds): ZonedDateTime

open operator override fun plus(microseconds: IntMicroseconds): ZonedDateTime

open operator override fun plus(microseconds: LongMicroseconds): ZonedDateTime

open operator override fun plus(nanoseconds: IntNanoseconds): ZonedDateTime

open operator override fun plus(nanoseconds: LongNanoseconds): ZonedDateTime

rangeTo

common

operator fun rangeTo(other: ZonedDateTime): ZonedDateTimeInterval

toString

common

Converts this date-time to a string in ISO-8601 extended format. For example, 2012-04-15T17:31:45.923452091-04:00[America/New_York] or 2020-02-13T02:30Z.

open override fun toString(): String

withEarlierOffsetAtOverlap

common

If the local date-time falls during an overlap caused by a daylight savings transition, a ZonedDateTime with the same local date and time will be returned, but using the earlier of the two valid offsets.

fun withEarlierOffsetAtOverlap(): ZonedDateTime

withFixedOffsetZone

common

If this date-time uses a region-based time zone, a copy with a fixed offset will be returned. Otherwise, this date-time will be returned unchanged.

fun withFixedOffsetZone(): ZonedDateTime

withLaterOffsetAtOverlap

common

If the local date-time falls during an overlap caused by a daylight savings transition, a ZonedDateTime with the same local date and time will be returned, but using the later of the two valid offsets.

fun withLaterOffsetAtOverlap(): ZonedDateTime

Properties

additionalNanosecondsSinceUnixEpoch

common

The number of additional nanoseconds on top of secondsSinceUnixEpoch.

open override val additionalNanosecondsSinceUnixEpoch: IntNanoseconds

date

common

The local date.

val date: Date

dateTime

common

The local date and time of day.

val dateTime: DateTime

dayOfMonth

common

The day of the month.

val dayOfMonth: Int

dayOfWeek

common

The day of the week.

val dayOfWeek: DayOfWeek

dayOfYear

common

The day of the year.

val dayOfYear: Int

hour

common

The hour of the day.

val hour: Int

millisecondOfUnixEpoch

common

The millisecond of the Unix epoch.

open override val millisecondOfUnixEpoch: Long

millisecondsSinceUnixEpoch

common

The number of milliseconds since the Unix epoch of 1970-01-01T00:00Z.

open override val millisecondsSinceUnixEpoch: LongMilliseconds

minute

common

The minute of the hour.

val minute: Int

month

common

The month of the year.

val month: Month

monthNumber

common

The ISO month number, from 1-12.

val monthNumber: Int

nanosecond

common

The nanosecond of the second.

open override val nanosecond: Int

offset

common

The offset from UTC.

val offset: UtcOffset

second

common

The second of the minute.

val second: Int

secondOfUnixEpoch

common

The second of the Unix epoch.

open override val secondOfUnixEpoch: Long

secondsSinceUnixEpoch

common

The number of seconds since the Unix epoch of 1970-01-01T00:00Z.

open override val secondsSinceUnixEpoch: LongSeconds

time

common

The local time of day.

val time: Time

year

common

The year.

val year: Int

zone

common

The time zone.

val zone: TimeZone

Extensions

endOfMonth

common

The date-time at the last representable instant of the month that this date-time falls in.

val ZonedDateTime.endOfMonth: ZonedDateTime

endOfWeek

common

The date-time at the last representable instant of the ISO week that this date-time falls in.

The ISO week starts on Monday and ends on Sunday.

val ZonedDateTime.endOfWeek: ZonedDateTime

The date-time at the last representable instant of the week that this date-time falls in. The first day of the week will be determined by the user's system settings. This may differ from the first day of the week associated with the default locale on platforms that allow the user to customize this.

fun ZonedDateTime.endOfWeek(settings: WeekSettings): ZonedDateTime

The date-time at the last representable instant of the week that this date-time falls in. The first day of the week will be determined by locale.

fun ZonedDateTime.endOfWeek(locale: Locale): ZonedDateTime

endOfYear

common

The date-time at the last representable instant of the year that this date-time falls in.

val ZonedDateTime.endOfYear: ZonedDateTime

isInLeapDay

common

Checks if this date-time falls within February 29.

val ZonedDateTime.isInLeapDay: Boolean

isInLeapYear

common

Checks if this date-time falls within a leap year.

val ZonedDateTime.isInLeapYear: Boolean

lengthOfMonth

common

The length of this date-time's month in days.

val ZonedDateTime.lengthOfMonth: IntDays

lengthOfWeekBasedYear

common

The length of the ISO week-based year that this date-time falls in, either 52 or 53 weeks.

val ZonedDateTime.lengthOfWeekBasedYear: IntWeeks

lengthOfYear

common

The length of this date-time's year in days.

val ZonedDateTime.lengthOfYear: IntDays

common

The next date-time after this one that falls on dayOfWeek.

fun ZonedDateTime.next(dayOfWeek: DayOfWeek): ZonedDateTime

nextOrSame

common

The next date-time that falls on dayOfWeek, or this date-time if it falls on the same day.

fun ZonedDateTime.nextOrSame(dayOfWeek: DayOfWeek): ZonedDateTime

common

The last date-time before this one that falls on dayOfWeek.

fun ZonedDateTime.previous(dayOfWeek: DayOfWeek): ZonedDateTime

previousOrSame

common

The previous date-time that falls on dayOfWeek, or this date-time if it falls on the same day.

fun ZonedDateTime.previousOrSame(dayOfWeek: DayOfWeek): ZonedDateTime

roundedDownTo

common

Returns this date-time, rounded down to match the precision of a given unit.

Due to daylight savings time transitions, there a few complexities to be aware of. If the new local time falls within a 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 offset will be retained if possible. Otherwise, the earlier offset will be used.

This is equivalent to truncatedTo.

fun ZonedDateTime.roundedDownTo(unit: TimeUnit): ZonedDateTime

roundedDownToNearest

common

Returns this date-time, rounded down to the nearest hour that satisfies the increment.

The increment must multiply evenly into a 24-hour day.

fun ZonedDateTime.roundedDownToNearest(increment: IntHours): ZonedDateTime

Returns this date-time, rounded down to the nearest minute that satisfies the increment.

The increment must multiply evenly into an hour.

fun ZonedDateTime.roundedDownToNearest(increment: IntMinutes): ZonedDateTime

Returns this date-time, rounded down to the nearest second that satisfies the increment.

The increment must multiply evenly into a minute.

fun ZonedDateTime.roundedDownToNearest(increment: IntSeconds): ZonedDateTime

Returns this date-time, rounded down to the nearest millisecond that satisfies the increment.

The increment must multiply evenly into a second.

fun ZonedDateTime.roundedDownToNearest(increment: IntMilliseconds): ZonedDateTime

Returns this date-time, rounded down to the nearest microsecond that satisfies the increment.

The increment must multiply evenly into a second.

fun ZonedDateTime.roundedDownToNearest(increment: IntMicroseconds): ZonedDateTime

Returns this date-time, rounded down to the nearest nanosecond that satisfies the increment.

The increment must multiply evenly into a second.

fun ZonedDateTime.roundedDownToNearest(increment: IntNanoseconds): ZonedDateTime

roundedTo

common

Returns this date-time, rounded to match the precision of a given unit. If the time is halfway between whole values of the unit, it will be rounded up.

fun ZonedDateTime.roundedTo(unit: TimeUnit): ZonedDateTime

roundedToNearest

common

Returns this date-time, rounded to the nearest hour that satisfies the increment. If the time is halfway between increments, it will be rounded up.

The increment must multiply evenly into a 24-hour day.

fun ZonedDateTime.roundedToNearest(increment: IntHours): ZonedDateTime

Returns this date-time, rounded to the nearest minute that satisfies the increment. If the time is halfway between increments, it will be rounded up.

The increment must multiply evenly into an hour.

fun ZonedDateTime.roundedToNearest(increment: IntMinutes): ZonedDateTime

Returns this date-time, rounded to the nearest second that satisfies the increment. If the time is halfway between increments, it will be rounded up.

The increment must multiply evenly into a minute.

fun ZonedDateTime.roundedToNearest(increment: IntSeconds): ZonedDateTime

Returns this date-time, rounded to the nearest millisecond that satisfies the increment. If the time is halfway between increments, it will be rounded up.

The increment must multiply evenly into a second.

fun ZonedDateTime.roundedToNearest(increment: IntMilliseconds): ZonedDateTime

Returns this date-time, rounded to the nearest microsecond that satisfies the increment. If the time is halfway between increments, it will be rounded up.

The increment must multiply evenly into a second.

fun ZonedDateTime.roundedToNearest(increment: IntMicroseconds): ZonedDateTime

Returns this date-time, rounded to the nearest nanosecond that satisfies the increment. If the time is halfway between increments, it will be rounded up.

The increment must multiply evenly into a second.

fun ZonedDateTime.roundedToNearest(increment: IntNanoseconds): ZonedDateTime

roundedUpTo

common

Returns this date-time, rounded up to match the precision of a given unit.

The start of the next day will be returned when the resulting time is after midnight.

fun ZonedDateTime.roundedUpTo(unit: TimeUnit): ZonedDateTime

roundedUpToNearest

common

Returns this date-time, rounded up to the nearest hour that satisfies the increment.

The increment must multiply evenly into a 24-hour day.

fun ZonedDateTime.roundedUpToNearest(increment: IntHours): ZonedDateTime

Returns this date-time, rounded up to the nearest minute that satisfies the increment.

The increment must multiply evenly into an hour.

fun ZonedDateTime.roundedUpToNearest(increment: IntMinutes): ZonedDateTime

Returns this date-time, rounded up to the nearest second that satisfies the increment.

The increment must multiply evenly into a minute.

fun ZonedDateTime.roundedUpToNearest(increment: IntSeconds): ZonedDateTime

Returns this date-time, rounded up to the nearest millisecond that satisfies the increment.

The increment must multiply evenly into a second.

fun ZonedDateTime.roundedUpToNearest(increment: IntMilliseconds): ZonedDateTime

Returns this date-time, rounded up to the nearest microsecond that satisfies the increment.

The increment must multiply evenly into a second.

fun ZonedDateTime.roundedUpToNearest(increment: IntMicroseconds): ZonedDateTime

Returns this date-time, rounded up to the nearest nanosecond that satisfies the increment.

The increment must multiply evenly into a second.

fun ZonedDateTime.roundedUpToNearest(increment: IntNanoseconds): ZonedDateTime

startOfMonth

common

The date-time at the first instant of the month that this date-time falls in.

val ZonedDateTime.startOfMonth: ZonedDateTime

startOfWeek

common

The date-time at the first instant of the ISO week that this date-time falls in.

The ISO week starts on Monday and ends on Sunday.

val ZonedDateTime.startOfWeek: ZonedDateTime

The date-time at the first instant of the week that this date-time falls in. The first day of the week will be determined by the user's system settings. This may differ from the first day of the week associated with the default locale on platforms that allow the user to customize this.

fun ZonedDateTime.startOfWeek(settings: WeekSettings): ZonedDateTime

The date-time at the first instant of the week that this date-time falls in. The first day of the week will be determined by locale.

fun ZonedDateTime.startOfWeek(locale: Locale): ZonedDateTime

startOfYear

common

The date-time at the first instant of the year that this date-time falls in.

val ZonedDateTime.startOfYear: ZonedDateTime

toInstant

common

Converts this date-time to an Instant representing the same time point.

fun ZonedDateTime.toInstant(): Instant

toJavaZonedDateTime

jvm

Converts this date-time to an equivalent Java ZonedDateTime.

fun ZonedDateTime.toJavaZonedDateTime(): ZonedDateTime

toNSDateComponents

darwin

Converts this date-time to an equivalent NSDateComponents object.

fun ZonedDateTime.toNSDateComponents(includeCalendar: Boolean): <ERROR CLASS>

toOffsetDateTime

common

Returns the combined date, time, and UTC offset.

While similar to ZonedDateTime, an OffsetDateTime representation is unaffected by time zone rule changes or database differences between systems, making it better suited for use cases involving persistence or network transfer.

fun ZonedDateTime.toOffsetDateTime(): OffsetDateTime

toOffsetTime

common

Returns the combined time and UTC offset.

fun ZonedDateTime.toOffsetTime(): OffsetTime

toYear

common

Returns this date-time with the precision reduced to the year.

fun ZonedDateTime.toYear(): Year

toYearMonth

common

Returns this date-time with the precision reduced to the month.

fun ZonedDateTime.toYearMonth(): YearMonth

truncatedTo

common

Returns this date-time, rounded down to match the precision of a given unit.

This is equivalent to roundedDownTo.

fun ZonedDateTime.truncatedTo(unit: TimeUnit): ZonedDateTime

until

common

Creates a ZonedDateTimeInterval from this date-time up to, but not including to.

infix fun ZonedDateTime.until(to: ZonedDateTime): ZonedDateTimeInterval

week

common

The interval defining the ISO week that this date-time falls within.

The ISO week starts on Monday and ends on Sunday.

val ZonedDateTime.week: ZonedDateTimeInterval

The interval defining the week that this date-time falls within. The first day of the week will be determined by the provided settings.

fun ZonedDateTime.week(settings: WeekSettings): ZonedDateTimeInterval

The interval defining the week that this date-time falls within. The first day of the week will be the default associated with the provided locale.

Keep in mind that that the system's calendar settings may differ from that of the default locale on some platforms. To respect the system calendar settings, use WeekSettings.systemDefault instead.

fun ZonedDateTime.week(locale: Locale): ZonedDateTimeInterval

weekBasedYear

common

The week-based year used in the ISO week date system. This value differs from the regular ISO year when the week number falls in the preceding or following year.

val ZonedDateTime.weekBasedYear: Int

The week-based year, calculated using the week definition in settings. This value differs from the regular ISO year when the week number falls in the preceding or following year.

fun ZonedDateTime.weekBasedYear(settings: WeekSettings): Int

The week-based year, calculated using the week definition associated with the provided locale. This value differs from the regular ISO year when the week number falls in the preceding or following year.

Keep in mind that that the system's calendar settings may differ from that of the default locale on some platforms. To respect the system calendar settings, use WeekSettings.systemDefault instead.

fun ZonedDateTime.weekBasedYear(locale: Locale): Int

weekOfMonth

common

The week of the month, from 0-6, calculated using the ISO week definition.

val ZonedDateTime.weekOfMonth: Int

The week of the month, from 0-6, calculated using the week definition in settings.

fun ZonedDateTime.weekOfMonth(settings: WeekSettings): Int

The week of the month, from 0-6, calculated using the default week definition associated with the provided locale.

Keep in mind that that the system's calendar settings may differ from that of the default locale on some platforms. To respect the system calendar settings, use WeekSettings.systemDefault instead.

fun ZonedDateTime.weekOfMonth(locale: Locale): Int

weekOfWeekBasedYear

common

The week number used in the ISO week date system.

val ZonedDateTime.weekOfWeekBasedYear: Int

The week number of the week-based year, calculated using the week definition in settings.

fun ZonedDateTime.weekOfWeekBasedYear(settings: WeekSettings): Int

The week number of the week-based year, calculated using the week definition associated with the provided locale.

Keep in mind that that the system's calendar settings may differ from that of the default locale on some platforms. To respect the system calendar settings, use WeekSettings.systemDefault instead.

fun ZonedDateTime.weekOfWeekBasedYear(locale: Locale): Int

weekOfYear

common

The week of the year, calculated using the ISO week definition. If the week number is associated with the preceding year, 0 will be returned.

To obtain the week number used in the ISO week date system, use weekOfWeekBasedYear instead.

val ZonedDateTime.weekOfYear: Int

The week of the year, calculated using the week definition in settings. If the week number is associated with the preceding year, 0 will be returned.

To obtain the week number of the week-based year, use weekOfWeekBasedYear instead.

fun ZonedDateTime.weekOfYear(settings: WeekSettings): Int

The week of the year, calculated using the week definition associated with the provided locale. If the week number is associated with the preceding year, 0 will be returned.

To obtain the week number of the week-based year, use weekOfWeekBasedYear instead.

Keep in mind that that the system's calendar settings may differ from that of the default locale on some platforms. To respect the system calendar settings, use WeekSettings.systemDefault instead.

fun ZonedDateTime.weekOfYear(locale: Locale): Int