OffsetDateTime

A date and time of day with an offset from UTC.

OffsetDateTime is intended to be used primarily for use cases involving persistence or network transfer where the application of time zone rules may be undesirable. For most applications, ZonedDateTime is a better choice since it takes time zone rules into account when performing calendrical calculations.

class OffsetDateTime(dateTime: DateTime,offset: UtcOffset) : TimePoint<OffsetDateTime>

Parameters

dateTime

the local date and time of day

offset

the offset from UTC

Constructors

OffsetDateTime

common

Creates an OffsetDateTime.

fun OffsetDateTime(date: Date, time: Time, offset: UtcOffset)

OffsetDateTime

common

Creates an OffsetDateTime.

fun OffsetDateTime(year: Int, month: Month, dayOfMonth: Int, hour: Int, minute: Int, second: Int, nanosecond: Int, offset: UtcOffset)

OffsetDateTime

common

Creates an OffsetDateTime.

fun OffsetDateTime(year: Int, monthNumber: Int, dayOfMonth: Int, hour: Int, minute: Int, second: Int, nanosecond: Int, offset: UtcOffset)

OffsetDateTime

common

Creates an OffsetDateTime.

fun OffsetDateTime(year: Int, dayOfYear: Int, hour: Int, minute: Int, second: Int, nanosecond: Int, offset: UtcOffset)

OffsetDateTime

common

Creates an OffsetDateTime by combining a DateTime and UtcOffset.

fun OffsetDateTime(dateTime: DateTime, offset: UtcOffset)

Types

Companion

common

object Companion

Functions

adjustedTo

common

Changes the offset of this OffsetDateTime, adjusting the date and time components such that the instant represented by it remains the same.

fun adjustedTo(newOffset: UtcOffset): OffsetDateTime

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.

fun copy(dateTime: DateTime, offset: UtcOffset): OffsetDateTime

fun copy(date: Date, time: Time, offset: UtcOffset): OffsetDateTime

fun copy(year: Int, dayOfYear: Int, hour: Int, minute: Int, second: Int, nanosecond: Int, offset: UtcOffset): OffsetDateTime

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

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): OffsetDateTime

operator fun minus(duration: Duration): OffsetDateTime

operator fun minus(years: LongYears): OffsetDateTime

operator fun minus(years: IntYears): OffsetDateTime

operator fun minus(months: LongMonths): OffsetDateTime

operator fun minus(months: IntMonths): OffsetDateTime

operator fun minus(weeks: LongWeeks): OffsetDateTime

operator fun minus(weeks: IntWeeks): OffsetDateTime

operator fun minus(days: LongDays): OffsetDateTime

operator fun minus(days: IntDays): OffsetDateTime

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

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

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

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

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

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

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

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

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

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

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

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

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): OffsetDateTime

operator fun plus(duration: Duration): OffsetDateTime

operator fun plus(years: LongYears): OffsetDateTime

operator fun plus(years: IntYears): OffsetDateTime

operator fun plus(months: LongMonths): OffsetDateTime

operator fun plus(months: IntMonths): OffsetDateTime

operator fun plus(weeks: LongWeeks): OffsetDateTime

operator fun plus(weeks: IntWeeks): OffsetDateTime

operator fun plus(days: LongDays): OffsetDateTime

operator fun plus(days: IntDays): OffsetDateTime

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

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

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

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

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

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

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

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

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

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

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

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

rangeTo

common

operator fun rangeTo(other: OffsetDateTime): OffsetDateTimeInterval

toString

common

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

open override fun toString(): String

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

Extensions

asZonedDateTime

common

Converts this OffsetDateTime to an equivalent ZonedDateTime using a fixed-offset time zone.

This comes with the caveat that a fixed-offset zone lacks knowledge of any region and will not respond to daylight savings time changes. To convert to a region-based zone, use toZonedDateTime instead.

fun OffsetDateTime.asZonedDateTime(): ZonedDateTime

endOfMonth

common

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

val OffsetDateTime.endOfMonth: OffsetDateTime

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 OffsetDateTime.endOfWeek: OffsetDateTime

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 OffsetDateTime.endOfWeek(settings: WeekSettings): OffsetDateTime

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 OffsetDateTime.endOfWeek(locale: Locale): OffsetDateTime

endOfYear

common

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

val OffsetDateTime.endOfYear: OffsetDateTime

isInLeapDay

common

Checks if this date-time falls within February 29.

val OffsetDateTime.isInLeapDay: Boolean

isInLeapYear

common

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

val OffsetDateTime.isInLeapYear: Boolean

lengthOfMonth

common

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

val OffsetDateTime.lengthOfMonth: IntDays

lengthOfWeekBasedYear

common

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

val OffsetDateTime.lengthOfWeekBasedYear: IntWeeks

lengthOfYear

common

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

val OffsetDateTime.lengthOfYear: IntDays

common

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

fun OffsetDateTime.next(dayOfWeek: DayOfWeek): OffsetDateTime

nextOrSame

common

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

fun OffsetDateTime.nextOrSame(dayOfWeek: DayOfWeek): OffsetDateTime

common

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

fun OffsetDateTime.previous(dayOfWeek: DayOfWeek): OffsetDateTime

previousOrSame

common

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

fun OffsetDateTime.previousOrSame(dayOfWeek: DayOfWeek): OffsetDateTime

roundedDownTo

common

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

This is equivalent to truncatedTo.

fun OffsetDateTime.roundedDownTo(unit: TimeUnit): OffsetDateTime

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 OffsetDateTime.roundedDownToNearest(increment: IntHours): OffsetDateTime

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

The increment must multiply evenly into an hour.

fun OffsetDateTime.roundedDownToNearest(increment: IntMinutes): OffsetDateTime

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

The increment must multiply evenly into a minute.

fun OffsetDateTime.roundedDownToNearest(increment: IntSeconds): OffsetDateTime

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

The increment must multiply evenly into a second.

fun OffsetDateTime.roundedDownToNearest(increment: IntMilliseconds): OffsetDateTime

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

The increment must multiply evenly into a second.

fun OffsetDateTime.roundedDownToNearest(increment: IntMicroseconds): OffsetDateTime

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

The increment must multiply evenly into a second.

fun OffsetDateTime.roundedDownToNearest(increment: IntNanoseconds): OffsetDateTime

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 OffsetDateTime.roundedTo(unit: TimeUnit): OffsetDateTime

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 OffsetDateTime.roundedToNearest(increment: IntHours): OffsetDateTime

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 OffsetDateTime.roundedToNearest(increment: IntMinutes): OffsetDateTime

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 OffsetDateTime.roundedToNearest(increment: IntSeconds): OffsetDateTime

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 OffsetDateTime.roundedToNearest(increment: IntMilliseconds): OffsetDateTime

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 OffsetDateTime.roundedToNearest(increment: IntMicroseconds): OffsetDateTime

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 OffsetDateTime.roundedToNearest(increment: IntNanoseconds): OffsetDateTime

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 OffsetDateTime.roundedUpTo(unit: TimeUnit): OffsetDateTime

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 OffsetDateTime.roundedUpToNearest(increment: IntHours): OffsetDateTime

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

The increment must multiply evenly into an hour.

fun OffsetDateTime.roundedUpToNearest(increment: IntMinutes): OffsetDateTime

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

The increment must multiply evenly into a minute.

fun OffsetDateTime.roundedUpToNearest(increment: IntSeconds): OffsetDateTime

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

The increment must multiply evenly into a second.

fun OffsetDateTime.roundedUpToNearest(increment: IntMilliseconds): OffsetDateTime

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

The increment must multiply evenly into a second.

fun OffsetDateTime.roundedUpToNearest(increment: IntMicroseconds): OffsetDateTime

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

The increment must multiply evenly into a second.

fun OffsetDateTime.roundedUpToNearest(increment: IntNanoseconds): OffsetDateTime

startOfMonth

common

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

val OffsetDateTime.startOfMonth: OffsetDateTime

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 OffsetDateTime.startOfWeek: OffsetDateTime

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 OffsetDateTime.startOfWeek(settings: WeekSettings): OffsetDateTime

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 OffsetDateTime.startOfWeek(locale: Locale): OffsetDateTime

startOfYear

common

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

val OffsetDateTime.startOfYear: OffsetDateTime

toInstant

common

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

fun OffsetDateTime.toInstant(): Instant

toJavaOffsetDateTime

jvm

Converts this date-time to an equivalent Java OffsetDateTime.

fun OffsetDateTime.toJavaOffsetDateTime(): OffsetDateTime

toNSDateComponents

darwin

Converts this date-time to an equivalent NSDateComponents object.

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

toOffsetTime

common

Returns the combined time and UTC offset.

fun OffsetDateTime.toOffsetTime(): OffsetTime

toYear

common

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

fun OffsetDateTime.toYear(): Year

toYearMonth

common

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

fun OffsetDateTime.toYearMonth(): YearMonth

toZonedDateTime

common

Converts this OffsetDateTime to a ZonedDateTime using the specified strategy to adjust it to a valid date, time, and offset in zone.

OffsetConversionStrategy.PRESERVE_INSTANT - Preserve the instant captured by the date, time, and offset, ignoring the local time.
OffsetConversionStrategy.PRESERVE_LOCAL_TIME - Preserve the local date and time in the new time zone, adjusting the offset if needed.

Alternatively, you can use asZonedDateTime to convert to a ZonedDateTime with an equivalent fixed-offset zone. However, this comes with the caveat that a fixed-offset zone lacks knowledge of any region and will not respond to daylight savings time changes.

fun OffsetDateTime.toZonedDateTime(zone: TimeZone, strategy: OffsetConversionStrategy): ZonedDateTime

truncatedTo

common

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

This is equivalent to roundedDownTo.

fun OffsetDateTime.truncatedTo(unit: TimeUnit): OffsetDateTime

until

common

Creates an OffsetDateTimeInterval from this date-time up to, but not including to.

infix fun OffsetDateTime.until(to: OffsetDateTime): OffsetDateTimeInterval

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 OffsetDateTime.week: OffsetDateTimeInterval

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 OffsetDateTime.week(settings: WeekSettings): OffsetDateTimeInterval

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 OffsetDateTime.week(locale: Locale): OffsetDateTimeInterval

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 OffsetDateTime.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 OffsetDateTime.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 OffsetDateTime.weekBasedYear(locale: Locale): Int

weekOfMonth

common

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

val OffsetDateTime.weekOfMonth: Int

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

fun OffsetDateTime.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 OffsetDateTime.weekOfMonth(locale: Locale): Int

weekOfWeekBasedYear

common

The week number used in the ISO week date system.

val OffsetDateTime.weekOfWeekBasedYear: Int

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

fun OffsetDateTime.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 OffsetDateTime.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 OffsetDateTime.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 OffsetDateTime.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 OffsetDateTime.weekOfYear(locale: Locale): Int