DateTime

A date and time of day in an ambiguous region.

class DateTime(date: Date,time: Time) : Comparable<DateTime>

Parameters

date

the date

time

the time

Constructors

DateTime

common

Creates a DateTime.

fun DateTime(year: Int, month: Month, day: Int, hour: Int, minute: Int, second: Int, nanosecond: Int)

DateTime

common

Creates a DateTime.

fun DateTime(year: Int, monthNumber: Int, day: Int, hour: Int, minute: Int, second: Int, nanosecond: Int)

DateTime

common

Creates a DateTime.

fun DateTime(year: Int, dayOfYear: Int, hour: Int, minute: Int, second: Int, nanosecond: Int)

DateTime

common

Creates a DateTime by combining a Date and Time.

fun DateTime(date: Date, time: Time)

Types

Companion

common

object Companion

Functions

compareTo

common

open operator override fun compareTo(other: DateTime): Int

component1

common

operator fun component1(): Date

component2

common

operator fun component2(): Time

copy

common

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

fun copy(date: Date, time: Time): DateTime

fun copy(year: Int, dayOfYear: Int, hour: Int, minute: Int, second: Int, nanosecond: Int): DateTime

fun copy(year: Int, month: Month, dayOfMonth: Int, hour: Int, minute: Int, second: Int, nanosecond: Int): DateTime

fun copy(year: Int, monthNumber: Int, dayOfMonth: Int, hour: Int, minute: Int, second: Int, nanosecond: Int): DateTime

equals

common

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

hashCode

common

open override fun hashCode(): Int

millisecondOfUnixEpochAt

common

The millisecond of the Unix epoch.

fun millisecondOfUnixEpochAt(offset: UtcOffset): Long

millisecondsSinceUnixEpochAt

common

The number of milliseconds relative to the Unix epoch of 1970-01-01T00:00Z at a particular offset. This is a "floor" value, so 1 nanosecond before the Unix epoch will be at a distance of 1 millisecond.

fun millisecondsSinceUnixEpochAt(offset: UtcOffset): LongMilliseconds

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

operator fun minus(duration: Duration): DateTime

operator fun minus(years: IntYears): DateTime

operator fun minus(years: LongYears): DateTime

operator fun minus(months: IntMonths): DateTime

operator fun minus(months: LongMonths): DateTime

operator fun minus(weeks: IntWeeks): DateTime

operator fun minus(weeks: LongWeeks): DateTime

operator fun minus(days: IntDays): DateTime

operator fun minus(days: LongDays): DateTime

operator fun minus(hours: IntHours): DateTime

operator fun minus(hours: LongHours): DateTime

operator fun minus(minutes: IntMinutes): DateTime

operator fun minus(minutes: LongMinutes): DateTime

operator fun minus(seconds: IntSeconds): DateTime

operator fun minus(seconds: LongSeconds): DateTime

operator fun minus(milliseconds: IntMilliseconds): DateTime

operator fun minus(milliseconds: LongMilliseconds): DateTime

operator fun minus(microseconds: IntMicroseconds): DateTime

operator fun minus(microseconds: LongMicroseconds): DateTime

operator fun minus(nanoseconds: IntNanoseconds): DateTime

operator fun minus(nanoseconds: LongNanoseconds): DateTime

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

operator fun plus(duration: Duration): DateTime

operator fun plus(years: IntYears): DateTime

operator fun plus(years: LongYears): DateTime

operator fun plus(months: IntMonths): DateTime

operator fun plus(months: LongMonths): DateTime

operator fun plus(weeks: IntWeeks): DateTime

operator fun plus(weeks: LongWeeks): DateTime

operator fun plus(days: IntDays): DateTime

operator fun plus(days: LongDays): DateTime

operator fun plus(hours: IntHours): DateTime

operator fun plus(hours: LongHours): DateTime

operator fun plus(minutes: IntMinutes): DateTime

operator fun plus(minutes: LongMinutes): DateTime

operator fun plus(seconds: IntSeconds): DateTime

operator fun plus(seconds: LongSeconds): DateTime

operator fun plus(milliseconds: IntMilliseconds): DateTime

operator fun plus(milliseconds: LongMilliseconds): DateTime

operator fun plus(microseconds: IntMicroseconds): DateTime

operator fun plus(microseconds: LongMicroseconds): DateTime

operator fun plus(nanoseconds: IntNanoseconds): DateTime

operator fun plus(nanoseconds: LongNanoseconds): DateTime

rangeTo

common

operator fun rangeTo(other: DateTime): DateTimeInterval

secondOfUnixEpochAt

common

The second of the Unix epoch.

fun secondOfUnixEpochAt(offset: UtcOffset): Long

secondsSinceUnixEpochAt

common

The number of seconds relative to the Unix epoch of 1970-01-01T00:00Z at a particular offset. This is a "floor" value, so 1 nanosecond before the Unix epoch will be at a distance of 1 second.

fun secondsSinceUnixEpochAt(offset: UtcOffset): LongSeconds

toString

common

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

open override fun toString(): String

Properties

additionalNanosecondsSinceUnixEpoch

common

The number of additional nanoseconds that should be applied on top of the number of seconds since the Unix epoch returned by secondsSinceUnixEpochAt.

val additionalNanosecondsSinceUnixEpoch: IntNanoseconds

date

common

The date.

val date: Date

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

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.

val nanosecond: Int

second

common

The second of the minute.

val second: Int

time

common

The time of day.

val time: Time

year

common

The year.

val year: Int

Extensions

common

Combines a local date and time with a UTC offset to create an OffsetDateTime.

infix fun DateTime.at(offset: UtcOffset): OffsetDateTime

Combines a local date and time with a time zone to create a ZonedDateTime.

Due to daylight savings time transitions, there a few complexities to be aware of. If the 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 earlier offset will be used.

infix fun DateTime.at(zone: TimeZone): ZonedDateTime

endOfMonth

common

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

val DateTime.endOfMonth: DateTime

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

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 system settings. This may differ from the first day of the week associated with the default locale on platforms that allow this to be customized.

fun DateTime.endOfWeek(settings: WeekSettings): DateTime

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

endOfYear

common

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

val DateTime.endOfYear: DateTime

isInLeapDay

common

Checks if this date-time falls within February 29.

val DateTime.isInLeapDay: Boolean

isInLeapYear

common

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

val DateTime.isInLeapYear: Boolean

lengthOfMonth

common

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

val DateTime.lengthOfMonth: IntDays

lengthOfWeekBasedYear

common

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

val DateTime.lengthOfWeekBasedYear: IntWeeks

lengthOfYear

common

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

val DateTime.lengthOfYear: IntDays

common

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

fun DateTime.next(dayOfWeek: DayOfWeek): DateTime

nextOrSame

common

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

fun DateTime.nextOrSame(dayOfWeek: DayOfWeek): DateTime

common

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

fun DateTime.previous(dayOfWeek: DayOfWeek): DateTime

previousOrSame

common

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

fun DateTime.previousOrSame(dayOfWeek: DayOfWeek): DateTime

roundedDownTo

common

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

This is equivalent to truncatedTo.

fun DateTime.roundedDownTo(unit: TimeUnit): DateTime

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

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

The increment must multiply evenly into an hour.

fun DateTime.roundedDownToNearest(increment: IntMinutes): DateTime

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

The increment must multiply evenly into a minute.

fun DateTime.roundedDownToNearest(increment: IntSeconds): DateTime

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

The increment must multiply evenly into a second.

fun DateTime.roundedDownToNearest(increment: IntMilliseconds): DateTime

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

The increment must multiply evenly into a second.

fun DateTime.roundedDownToNearest(increment: IntMicroseconds): DateTime

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

The increment must multiply evenly into a second.

fun DateTime.roundedDownToNearest(increment: IntNanoseconds): DateTime

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

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

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

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

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

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

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

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

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

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

The increment must multiply evenly into an hour.

fun DateTime.roundedUpToNearest(increment: IntMinutes): DateTime

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

The increment must multiply evenly into a minute.

fun DateTime.roundedUpToNearest(increment: IntSeconds): DateTime

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

The increment must multiply evenly into a second.

fun DateTime.roundedUpToNearest(increment: IntMilliseconds): DateTime

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

The increment must multiply evenly into a second.

fun DateTime.roundedUpToNearest(increment: IntMicroseconds): DateTime

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

The increment must multiply evenly into a second.

fun DateTime.roundedUpToNearest(increment: IntNanoseconds): DateTime

startOfMonth

common

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

val DateTime.startOfMonth: DateTime

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

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 system settings. This may differ from the first day of the week associated with the default locale on platforms that allow this to be customized.

fun DateTime.startOfWeek(settings: WeekSettings): DateTime

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

startOfYear

common

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

val DateTime.startOfYear: DateTime

toInstantAt

common

Converts this date-time to the corresponding Instant at offset.

fun DateTime.toInstantAt(offset: UtcOffset): Instant

toJavaLocalDateTime

jvm

Converts this date-time to an equivalent Java LocalDateTime.

fun DateTime.toJavaLocalDateTime(): LocalDateTime

toNSDateComponents

darwin

Converts this date-time to an equivalent NSDateComponents object.

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

toYear

common

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

fun DateTime.toYear(): Year

toYearMonth

common

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

fun DateTime.toYearMonth(): YearMonth

truncatedTo

common

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

This is equivalent to roundedDownTo.

fun DateTime.truncatedTo(unit: TimeUnit): DateTime

until

common

Creates a DateTimeInterval from this date-time up to, but not including the nanosecond represented by to.

infix fun DateTime.until(to: DateTime): DateTimeInterval

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 DateTime.week: DateTimeInterval

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 DateTime.week(settings: WeekSettings): DateTimeInterval

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 DateTime.week(locale: Locale): DateTimeInterval

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

weekOfMonth

common

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

val DateTime.weekOfMonth: Int

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

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

weekOfWeekBasedYear

common

The week number used in the ISO week date system.

val DateTime.weekOfWeekBasedYear: Int

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

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