LocalDate

@Serializable(with = LocalDateIso8601Serializer::class)
actual class LocalDate(year: Int, monthNumber: Int, dayOfMonth: Int) : Comparable<LocalDate> (source)
@Serializable(with = LocalDateIso8601Serializer::class)
expect class LocalDate(year: Int, monthNumber: Int, dayOfMonth: Int) : Comparable<LocalDate> (source)

The date part of LocalDateTime.

This class represents dates without a reference to a particular time zone. As such, these objects may denote different time intervals in different time zones: for someone in Berlin, 2020-08-30 started and ended at different moments from those for someone in Tokyo.

The arithmetic on LocalDate values is defined independently of the time zone (so 2020-08-30 plus one day is 2020-08-31 everywhere): see various LocalDate.plus and LocalDate.minus functions, as well as LocalDate.periodUntil and various other *until functions.

Arithmetic operations

Operations with DateTimeUnit.DateBased and DatePeriod are provided for LocalDate:

Platform specifics

The range of supported years is platform-dependent, but at least is enough to represent dates of all instants between Instant.DISTANT_PAST and Instant.DISTANT_FUTURE.

On the JVM, there are LocalDate.toJavaLocalDate() and java.time.LocalDate.toKotlinLocalDate() extension functions to convert between kotlinx.datetime and java.time objects used for the same purpose. Similarly, on the Darwin platforms, there is a LocalDate.toNSDateComponents() extension function.

Construction, serialization, and deserialization

LocalDate can be constructed directly from its components using the constructor. See sample 1.

fromEpochDays can be used to obtain a LocalDate from the number of days since the epoch day 1970-01-01; toEpochDays is the inverse operation. See sample 2.

parse and toString methods can be used to obtain a LocalDate from and convert it to a string in the ISO 8601 extended format. See sample 3.

parse and LocalDate.format both support custom formats created with Format or defined in Formats. See sample 4.

Additionally, there are several kotlinx-serialization serializers for LocalDate:

Samples

import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.random.*
import kotlin.test.*

fun main() { 
   //sampleStart 
   // Constructing a LocalDate value using its constructor
val date = LocalDate(2024, 4, 16)
check(date.year == 2024)
check(date.monthNumber == 4)
check(date.month == Month.APRIL)
check(date.dayOfMonth == 16) 
   //sampleEnd
}
import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.random.*
import kotlin.test.*

fun main() { 
   //sampleStart 
   // Converting LocalDate values to the number of days since 1970-01-01 and back
check(LocalDate.fromEpochDays(0) == LocalDate(1970, Month.JANUARY, 1))
val randomEpochDay = Random.nextInt(-50_000..50_000)
val randomDate = LocalDate.fromEpochDays(randomEpochDay)
check(randomDate.toEpochDays() == randomEpochDay) 
   //sampleEnd
}
import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.random.*
import kotlin.test.*

fun main() { 
   //sampleStart 
   // Parsing and formatting LocalDate values
check(LocalDate.parse("2023-01-02") == LocalDate(2023, Month.JANUARY, 2))
check(LocalDate(2023, Month.JANUARY, 2).toString() == "2023-01-02") 
   //sampleEnd
}
import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.random.*
import kotlin.test.*

fun main() { 
   //sampleStart 
   // Parsing and formatting LocalDate values using a custom format
val customFormat = LocalDate.Format {
    monthName(MonthNames.ENGLISH_ABBREVIATED); char(' '); dayOfMonth(); chars(", "); year()
}
val date = customFormat.parse("Apr 16, 2024")
check(date == LocalDate(2024, Month.APRIL, 16))
val formatted = date.format(customFormat)
check(formatted == "Apr 16, 2024") 
   //sampleEnd
}
@Serializable(with = LocalDateIso8601Serializer::class)
actual class LocalDate(year: Int, monthNumber: Int, dayOfMonth: Int) : Comparable<LocalDate> (source)
@Serializable(with = LocalDateIso8601Serializer::class)
actual class LocalDate(val year: Int, val monthNumber: Int, val dayOfMonth: Int) : Comparable<LocalDate> (source)

Constructors

Link copied to clipboard
actual constructor(year: Int, monthNumber: Int, dayOfMonth: Int)
actual constructor(year: Int, month: Month, dayOfMonth: Int)
expect constructor(year: Int, monthNumber: Int, dayOfMonth: Int)

Constructs a LocalDate instance from the given date components.

expect constructor(year: Int, month: Month, dayOfMonth: Int)

Constructs a LocalDate instance from the given date components.

actual constructor(year: Int, monthNumber: Int, dayOfMonth: Int)
actual constructor(year: Int, monthNumber: Int, dayOfMonth: Int)
actual constructor(year: Int, month: Month, dayOfMonth: Int)

Types

Link copied to clipboard
actual object Companion
expect object Companion
actual object Companion
actual object Companion
Link copied to clipboard
actual object Formats
expect object Formats

A collection of predefined formats for parsing and formatting LocalDate values.

actual object Formats
actual object Formats

Properties

Link copied to clipboard
actual val dayOfMonth: Int
expect val dayOfMonth: Int

Returns the day-of-month (1..31) component of the date.

actual val dayOfMonth: Int
actual val dayOfMonth: Int
Link copied to clipboard
actual val dayOfWeek: DayOfWeek
expect val dayOfWeek: DayOfWeek

Returns the day-of-week component of the date.

actual val dayOfWeek: DayOfWeek
actual val dayOfWeek: DayOfWeek
Link copied to clipboard
actual val dayOfYear: Int
expect val dayOfYear: Int

Returns the day-of-year (1..366) component of the date.

actual val dayOfYear: Int
actual val dayOfYear: Int
Link copied to clipboard
actual val month: Month
expect val month: Month

Returns the month (Month) component of the date.

actual val month: Month
actual val month: Month
Link copied to clipboard
actual val monthNumber: Int
expect val monthNumber: Int

Returns the number-of-the-month (1..12) component of the date.

actual val monthNumber: Int
actual val monthNumber: Int
Link copied to clipboard
actual val year: Int
expect val year: Int

Returns the year component of the date.

actual val year: Int
actual val year: Int

Functions

Link copied to clipboard
actual fun LocalDate.atStartOfDayIn(timeZone: TimeZone): Instant
expect fun LocalDate.atStartOfDayIn(timeZone: TimeZone): Instant

Returns an instant that corresponds to the start of this date in the specified timeZone.

actual fun LocalDate.atStartOfDayIn(timeZone: TimeZone): Instant
actual fun LocalDate.atStartOfDayIn(timeZone: TimeZone): Instant
Link copied to clipboard

Combines this date's components with the specified LocalTime components into a LocalDateTime value.

fun LocalDate.atTime(hour: Int, minute: Int, second: Int = 0, nanosecond: Int = 0): LocalDateTime

Combines this date's components with the specified time components into a LocalDateTime value.

Link copied to clipboard
actual open operator override fun compareTo(other: LocalDate): Int
expect open operator override fun compareTo(other: LocalDate): Int

Compares this date with the other date. Returns zero if this date represents the same day as the other (meaning they are equal to one other), a negative number if this date is earlier than the other, and a positive number if this date is later than the other.

actual open operator override fun compareTo(other: LocalDate): Int
actual open operator override fun compareTo(other: LocalDate): Int
Link copied to clipboard
actual fun LocalDate.daysUntil(other: LocalDate): Int
expect fun LocalDate.daysUntil(other: LocalDate): Int

Returns the number of whole days between two dates.

actual fun LocalDate.daysUntil(other: LocalDate): Int
actual fun LocalDate.daysUntil(other: LocalDate): Int
equals
Link copied to clipboard
open operator override fun equals(other: Any?): Boolean
open operator override fun equals(other: Any?): Boolean
open operator override fun equals(other: Any?): Boolean
Link copied to clipboard

Formats this value using the given format. Equivalent to calling DateTimeFormat.format on format with this.

hashCode
Link copied to clipboard
open override fun hashCode(): Int
open override fun hashCode(): Int
open override fun hashCode(): Int
Link copied to clipboard
operator fun LocalDate.minus(period: DatePeriod): LocalDate

Returns a date that results from subtracting components of DatePeriod from this date. The components are subtracted in the order from the largest units to the smallest: first years and months, then days.

operator fun LocalDate.minus(other: LocalDate): DatePeriod

Returns a DatePeriod representing the difference between other and this dates.

Returns a LocalDate that results from subtracting the value number of the specified unit from this date.

Link copied to clipboard
actual fun LocalDate.monthsUntil(other: LocalDate): Int
expect fun LocalDate.monthsUntil(other: LocalDate): Int

Returns the number of whole months between two dates.

actual fun LocalDate.monthsUntil(other: LocalDate): Int
actual fun LocalDate.monthsUntil(other: LocalDate): Int
Link copied to clipboard

Returns a DatePeriod representing the difference between this and other dates.

Link copied to clipboard
actual operator fun LocalDate.plus(period: DatePeriod): LocalDate
expect operator fun LocalDate.plus(period: DatePeriod): LocalDate

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.

Returns a LocalDate that results from adding the value number of the specified unit to this date.

actual operator fun LocalDate.plus(period: DatePeriod): LocalDate
actual operator fun LocalDate.plus(period: DatePeriod): LocalDate
Link copied to clipboard
actual fun toEpochDays(): Int
expect fun toEpochDays(): Int

Returns the number of days since the epoch day 1970-01-01.

actual fun toEpochDays(): Int
actual fun toEpochDays(): Int
Link copied to clipboard
Link copied to clipboard
fun LocalDate.toNSDateComponents(): <Error class: unknown class>

Converts the given LocalDate to NSDateComponents.

Link copied to clipboard
actual open override fun toString(): String
expect open override fun toString(): String

Converts this date to the extended ISO 8601 string representation.

actual open override fun toString(): String
actual open override fun toString(): String
Link copied to clipboard

Returns the whole number of the specified date units between this and other dates.

Link copied to clipboard
actual fun LocalDate.yearsUntil(other: LocalDate): Int
expect fun LocalDate.yearsUntil(other: LocalDate): Int

Returns the number of whole years between two dates.

actual fun LocalDate.yearsUntil(other: LocalDate): Int
actual fun LocalDate.yearsUntil(other: LocalDate): Int