Local
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:
LocalDate.plus and LocalDate.minus allow expressing concepts like "two months later".
LocalDate.until and its shortcuts LocalDate.daysUntil, LocalDate.monthsUntil, and LocalDate.yearsUntil can be used to find the number of days, months, or years between two dates.
LocalDate.periodUntil (and LocalDate.minus that accepts a LocalDate) can be used to find the DatePeriod between two dates.
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:
LocalDateIso8601Serializer for the ISO 8601 extended format.
LocalDateComponentSerializer for an object with components.
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
}Constructors
Properties
Functions
Combines this date's components with the specified LocalTime components into a LocalDateTime value.
Combines this date's components with the specified time components into a LocalDateTime value.
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.
Formats this value using the given format. Equivalent to calling DateTimeFormat.format on format with this.
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.
Returns a DatePeriod representing the difference between other and this dates.
Returns the number of whole months between two dates.
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 the number of days since the epoch day 1970-01-01.
Converts this kotlinx.datetime.LocalDate value to a java.time.LocalDate value.
Converts the given LocalDate to NSDateComponents.
Returns the number of whole years between two dates.