OffsetDateTime¶

@Serializable(with = OffsetDateTimeIsoSerializer::class)

class OffsetDateTime(val dateTime: DateTime, val offset: UtcOffset) : TimePoint<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.

Parameters¶

common


dateTime	the local date and time of day
offset	the offset from UTC

Throws¶


DateTimeException	if the offset is invalid

Constructors¶

OffsetDateTime

common

constructor(date: Date, time: Time, offset: UtcOffset)

Creates an OffsetDateTime.

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

Creates an OffsetDateTime.

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

Creates an OffsetDateTime.

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

Creates an OffsetDateTime.

constructor(dateTime: DateTime, offset: UtcOffset)

Creates an OffsetDateTime by combining a DateTime and UtcOffset.

Types¶

Name	Summary
Companion	common `object Companion`

Properties¶

Name	Summary
additionalNanosecondsSinceUnixEpoch	common `open val additionalNanosecondsSinceUnixEpoch: Nanoseconds` The number of additional nanoseconds on top of secondsSinceUnixEpoch.
date	common `val date: Date` The local date.
dateTime	common `val dateTime: DateTime` The local date and time of day.
dayOfMonth	common `val dayOfMonth: Int` The day of the month.
dayOfWeek	common `val dayOfWeek: DayOfWeek` The day of the week.
dayOfYear	common `val dayOfYear: Int` The day of the year.
endOfMonth	common `val OffsetDateTime.endOfMonth: OffsetDateTime` The date-time at the last representable instant of the month that this date-time falls in.
endOfWeek	common `val OffsetDateTime.endOfWeek: OffsetDateTime` The date-time at the last representable instant of the ISO week that this date-time falls in.
endOfYear	common `val OffsetDateTime.endOfYear: OffsetDateTime` The date-time at the last representable instant of the year that this date-time falls in.
hour	common `val hour: Int` The hour of the day.
isInLeapDay	common `val OffsetDateTime.isInLeapDay: Boolean` Checks if this date-time falls within February 29.
isInLeapYear	common `val OffsetDateTime.isInLeapYear: Boolean` Checks if this date-time falls within a leap year.
lengthOfMonth	common `val OffsetDateTime.lengthOfMonth: Days` The length of this date-time's month in days.
lengthOfWeekBasedYear	common `val OffsetDateTime.lengthOfWeekBasedYear: Weeks` The length of the ISO week-based year that this date-time falls in, either 52 or 53 weeks.
lengthOfYear	common `val OffsetDateTime.lengthOfYear: Days` The length of this date-time's year in days.
millisecondOfUnixEpoch	common `open override val millisecondOfUnixEpoch: Long` The millisecond of the Unix epoch.
millisecondsSinceUnixEpoch	common `open val millisecondsSinceUnixEpoch: Milliseconds` The number of milliseconds since the Unix epoch of 1970-01-01T00:00Z.
minute	common `val minute: Int` The minute of the hour.
month	common `val month: Month` The month of the year.
monthNumber	common `val monthNumber: Int` The ISO month number, from 1-12.
nanosecond	common `open override val nanosecond: Int` The nanosecond of the second.
offset	common `val offset: UtcOffset` The offset from UTC.
second	common `val second: Int` The second of the minute.
secondOfUnixEpoch	common `open override val secondOfUnixEpoch: Long` The second of the Unix epoch.
secondsSinceUnixEpoch	common `open val secondsSinceUnixEpoch: Seconds` The number of seconds since the Unix epoch of 1970-01-01T00:00Z.
startOfMonth	common `val OffsetDateTime.startOfMonth: OffsetDateTime` The date-time at the first instant of the month that this date-time falls in.
startOfWeek	common `val OffsetDateTime.startOfWeek: OffsetDateTime` The date-time at the first instant of the ISO week that this date-time falls in.
startOfYear	common `val OffsetDateTime.startOfYear: OffsetDateTime` The date-time at the first instant of the year that this date-time falls in.
time	common `val time: Time` The local time of day.
week	common `val OffsetDateTime.week: OffsetDateTimeInterval` The interval defining the ISO week that this date-time falls within.
weekBasedYear	common `val OffsetDateTime.weekBasedYear: Int` 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.
weekOfMonth	common `val OffsetDateTime.weekOfMonth: Int` The week of the month, from 0-6, calculated using the ISO week definition.
weekOfWeekBasedYear	common `val OffsetDateTime.weekOfWeekBasedYear: Int` The week number used in the ISO week date system.
weekOfYear	common `val OffsetDateTime.weekOfYear: Int` 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.
year	common `val year: Int` The year.

Functions¶

Name	Summary
adjustedTo	common `fun adjustedTo(newOffset: UtcOffset): OffsetDateTime` Returns this date-time with a new UTC offset, adjusting the date and time components such that the instant represented by it remains the same.
asZonedDateTime	common `fun OffsetDateTime.asZonedDateTime(): ZonedDateTime` Converts this OffsetDateTime to an equivalent ZonedDateTime using a fixed-offset time zone.
compareTo	common `open operator fun compareTo(other: TimePoint<*>): Int` Compares this time point with another time point.
copy	common `fun copy(dateTime: DateTime = this.dateTime, offset: UtcOffset = this.offset): OffsetDateTime` `fun copy(date: Date = this.date, time: Time = this.time, offset: UtcOffset = this.offset): OffsetDateTime` `fun copy(year: Int = this.year, dayOfYear: Int, hour: Int = this.hour, minute: Int = this.minute, second: Int = this.second, nanosecond: Int = this.nanosecond, offset: UtcOffset = this.offset): OffsetDateTime` `fun copy(year: Int = this.year, month: Month = this.month, dayOfMonth: Int = this.dayOfMonth, hour: Int = this.hour, minute: Int = this.minute, second: Int = this.second, nanosecond: Int = this.nanosecond, offset: UtcOffset = this.offset): OffsetDateTime` Returns a copy of this date-time with the values of any individual components replaced by the new values specified.
endOfWeek	common `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 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. common `fun OffsetDateTime.endOfWeek(locale: Locale): 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.
equals	common `open operator override fun equals(other: Any?): Boolean`
hashCode	common `open override fun hashCode(): Int`
isSameInstantAs	common `open fun isSameInstantAs(other: TimePoint<*>): Boolean` Checks if this time point represents the same instant as other. Unlike the equals operator, equality is determined solely by timeline order.
minus	common `operator fun minus(centuries: Centuries): OffsetDateTime` Returns this date-time with centuries subtracted from it. common `operator fun minus(days: Days): OffsetDateTime` Returns this date-time with days subtracted from it. common `operator fun minus(decades: Decades): OffsetDateTime` Returns this date-time with decades subtracted from it. common `operator fun minus(duration: Duration): OffsetDateTime` common `open operator override fun minus(hours: Hours): OffsetDateTime` Returns this date-time with hours subtracted from it. common `open operator override fun minus(microseconds: Microseconds): OffsetDateTime` Returns this date-time with microseconds subtracted from it. common `open operator override fun minus(milliseconds: Milliseconds): OffsetDateTime` Returns this date-time with milliseconds subtracted from it. common `open operator override fun minus(minutes: Minutes): OffsetDateTime` Returns this date-time with minutes subtracted from it. common `operator fun minus(months: Months): OffsetDateTime` Returns this date-time with months subtracted from it. common `open operator override fun minus(nanoseconds: Nanoseconds): OffsetDateTime` Returns this date-time with nanoseconds subtracted from it. common `operator fun minus(period: Period): OffsetDateTime` Returns this date-time with period subtracted from it. common `open operator override fun minus(seconds: Seconds): OffsetDateTime` Returns this date-time with seconds subtracted from it. common `operator fun minus(weeks: Weeks): OffsetDateTime` Returns this date-time with weeks subtracted from it. common `operator fun minus(years: Years): OffsetDateTime` Returns this date-time with years subtracted from it. common `operator fun minus(duration: Duration): OffsetDateTime` Returns this date-time with duration subtracted from it.
next	common `fun OffsetDateTime.next(dayOfWeek: DayOfWeek): OffsetDateTime` The next date-time after this one that falls on dayOfWeek.
nextOrSame	common `fun OffsetDateTime.nextOrSame(dayOfWeek: DayOfWeek): OffsetDateTime` The next date-time that falls on dayOfWeek, or this date-time if it falls on the same day.
plus	common `operator fun plus(centuries: Centuries): OffsetDateTime` Returns this date-tme with centuries added to it. common `operator fun plus(days: Days): OffsetDateTime` Returns this date-time with days added to it. common `operator fun plus(decades: Decades): OffsetDateTime` Returns this date-time with decades added to it. common `operator fun plus(duration: Duration): OffsetDateTime` common `open operator override fun plus(hours: Hours): OffsetDateTime` Returns this date-time with hours added to it. common `open operator override fun plus(microseconds: Microseconds): OffsetDateTime` Returns this date-time with microseconds added to it. common `open operator override fun plus(milliseconds: Milliseconds): OffsetDateTime` Returns this date-time with milliseconds added to it. common `open operator override fun plus(minutes: Minutes): OffsetDateTime` Returns this date-time with minutes added to it. common `operator fun plus(months: Months): OffsetDateTime` Returns this date-time with months added to it. common `open operator override fun plus(nanoseconds: Nanoseconds): OffsetDateTime` Returns this date-time with nanoseconds added to it. common `operator fun plus(period: Period): OffsetDateTime` Returns this date-time with period added to it. common `open operator override fun plus(seconds: Seconds): OffsetDateTime` Returns this date-time with seconds added to it. common `operator fun plus(weeks: Weeks): OffsetDateTime` Returns this date-time with weeks added to it. common `operator fun plus(years: Years): OffsetDateTime` Returns this date-time with years added to it. common `operator fun plus(duration: Duration): OffsetDateTime` Returns this date-time with duration added to it.
previous	common `fun OffsetDateTime.previous(dayOfWeek: DayOfWeek): OffsetDateTime` The last date-time before this one that falls on dayOfWeek.
previousOrSame	common `fun OffsetDateTime.previousOrSame(dayOfWeek: DayOfWeek): OffsetDateTime` The previous date-time that falls on dayOfWeek, or this date-time if it falls on the same day.
rangeTo	common `operator fun rangeTo(other: OffsetDateTime): OffsetDateTimeInterval`
roundedDownTo	common `fun OffsetDateTime.roundedDownTo(unit: TimeUnit): OffsetDateTime` Returns this date-time, rounded down to match the precision of a given unit.
roundedDownToNearest	common `fun OffsetDateTime.roundedDownToNearest(increment: Hours): OffsetDateTime` Returns this date-time, rounded down to the nearest hour that satisfies the increment. common `fun OffsetDateTime.roundedDownToNearest(increment: Microseconds): OffsetDateTime` Returns this date-time, rounded down to the nearest microsecond that satisfies the increment. common `fun OffsetDateTime.roundedDownToNearest(increment: Milliseconds): OffsetDateTime` Returns this date-time, rounded down to the nearest millisecond that satisfies the increment. common `fun OffsetDateTime.roundedDownToNearest(increment: Minutes): OffsetDateTime` Returns this date-time, rounded down to the nearest minute that satisfies the increment. common `fun OffsetDateTime.roundedDownToNearest(increment: Nanoseconds): OffsetDateTime` Returns this date-time, rounded down to the nearest nanosecond that satisfies the increment. common `fun OffsetDateTime.roundedDownToNearest(increment: Seconds): OffsetDateTime` Returns this date-time, rounded down to the nearest second that satisfies the increment.
roundedTo	common `fun OffsetDateTime.roundedTo(unit: TimeUnit): OffsetDateTime` 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.
roundedToNearest	common `fun OffsetDateTime.roundedToNearest(increment: Hours): OffsetDateTime` 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. common `fun OffsetDateTime.roundedToNearest(increment: Microseconds): 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. common `fun OffsetDateTime.roundedToNearest(increment: Milliseconds): 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. common `fun OffsetDateTime.roundedToNearest(increment: Minutes): 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. common `fun OffsetDateTime.roundedToNearest(increment: Nanoseconds): 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. common `fun OffsetDateTime.roundedToNearest(increment: Seconds): 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.
roundedUpTo	common `fun OffsetDateTime.roundedUpTo(unit: TimeUnit): OffsetDateTime` Returns this date-time, rounded up to match the precision of a given unit.
roundedUpToNearest	common `fun OffsetDateTime.roundedUpToNearest(increment: Hours): OffsetDateTime` Returns this date-time, rounded up to the nearest hour that satisfies the increment. common `fun OffsetDateTime.roundedUpToNearest(increment: Microseconds): OffsetDateTime` Returns this date-time, rounded up to the nearest microsecond that satisfies the increment. common `fun OffsetDateTime.roundedUpToNearest(increment: Milliseconds): OffsetDateTime` Returns this date-time, rounded up to the nearest millisecond that satisfies the increment. common `fun OffsetDateTime.roundedUpToNearest(increment: Minutes): OffsetDateTime` Returns this date-time, rounded up to the nearest minute that satisfies the increment. common `fun OffsetDateTime.roundedUpToNearest(increment: Nanoseconds): OffsetDateTime` Returns this date-time, rounded up to the nearest nanosecond that satisfies the increment. common `fun OffsetDateTime.roundedUpToNearest(increment: Seconds): OffsetDateTime` Returns this date-time, rounded up to the nearest second that satisfies the increment.
startOfWeek	common `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 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. common `fun OffsetDateTime.startOfWeek(locale: Locale): 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.
toInstant	common `fun OffsetDateTime.toInstant(): Instant` Converts this date-time to an Instant representing the same time point.
toJavaOffsetDateTime	jvm `fun OffsetDateTime.toJavaOffsetDateTime(): OffsetDateTime` Converts this date-time to an equivalent Java `OffsetDateTime`.
toNSDate	darwin `fun <T> TimePoint<T>.toNSDate(): <Error class: unknown class>` Converts this time point to an `NSDate`.
toNSDateComponents	darwin `fun OffsetDateTime.toNSDateComponents(includeCalendar: Boolean = false): <Error class: unknown class>` Converts this date-time to an equivalent `NSDateComponents` object.
toOffsetTime	common `fun OffsetDateTime.toOffsetTime(): OffsetTime` Returns the combined time and UTC offset.
toString	common `open override fun toString(): String` 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`.
toYear	common `fun OffsetDateTime.toYear(): Year` Returns this date-time with the precision reduced to the year.
toYearMonth	common `fun OffsetDateTime.toYearMonth(): YearMonth` Returns this date-time with the precision reduced to the month.
toZonedDateTime	common `fun OffsetDateTime.toZonedDateTime(zone: TimeZone, strategy: OffsetConversionStrategy): ZonedDateTime` Converts this OffsetDateTime to a ZonedDateTime using the specified strategy to adjust it to a valid date, time, and offset in zone.
truncatedTo	common `fun OffsetDateTime.truncatedTo(unit: TimeUnit): OffsetDateTime` Returns this date-time, rounded down to match the precision of a given unit.
until	common `infix fun OffsetDateTime.until(to: OffsetDateTime): OffsetDateTimeInterval` Creates an OffsetDateTimeInterval from this date-time up to, but not including to.
week	common `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 determined by the provided settings. common `fun OffsetDateTime.week(locale: Locale): 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.
weekBasedYear	common `fun OffsetDateTime.weekBasedYear(settings: WeekSettings): 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. common `fun OffsetDateTime.weekBasedYear(locale: Locale): 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.
weekOfMonth	common `fun OffsetDateTime.weekOfMonth(settings: WeekSettings): Int` The week of the month, from 0-6, calculated using the week definition in settings. common `fun OffsetDateTime.weekOfMonth(locale: Locale): Int` The week of the month, from 0-6, calculated using the default week definition associated with the provided locale.
weekOfWeekBasedYear	common `fun OffsetDateTime.weekOfWeekBasedYear(settings: WeekSettings): Int` The week number of the week-based year, calculated using the week definition in settings. common `fun OffsetDateTime.weekOfWeekBasedYear(locale: Locale): Int` The week number of the week-based year, calculated using the week definition associated with the provided locale.
weekOfYear	common `fun OffsetDateTime.weekOfYear(settings: WeekSettings): 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. common `fun OffsetDateTime.weekOfYear(locale: Locale): 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.