YearMonth

The year-month part of LocalDate, without a day-of-month.

This class represents years and months 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 started and ended at different moments from those for someone in Tokyo.

Arithmetic operations

The arithmetic on YearMonth values is defined independently of the time zone (so 2020-08 plus one month is 2020-09 everywhere).

Operations with DateTimeUnit.MonthBased are provided for YearMonth:

• YearMonth.plus and YearMonth.minus allow expressing concepts like "two months later".

• YearMonth.until and its shortcuts YearMonth.monthsUntil and YearMonth.yearsUntil can be used to find the number of months or years between two dates.

Platform specifics

The range of supported years is unspecified, but at least is enough to represent year-months of all instants between Instant.DISTANT_PAST and Instant.DISTANT_FUTURE in any time zone.

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

Construction, serialization, and deserialization

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

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

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

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

• The default serializer, delegating to toString and parse.

• YearMonthIso8601Serializer for the ISO 8601 extended format.

• YearMonthComponentSerializer for an object with components.

Samples

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

fun main() { 
   //sampleStart 
   // Constructing a YearMonth value using its constructor
val yearMonth = YearMonth(2024, 4)
check(yearMonth.year == 2024)
check(yearMonth.month == Month.APRIL) 
   //sampleEnd
}

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

fun main() { 
   //sampleStart 
   // Parsing and formatting YearMonth values
check(YearMonth.parse("2023-01") == YearMonth(2023, Month.JANUARY))
check(YearMonth(2023, Month.JANUARY).toString() == "2023-01") 
   //sampleEnd
}

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

fun main() { 
   //sampleStart 
   // Parsing and formatting YearMonth values using a custom format
val customFormat = YearMonth.Format {
    monthName(MonthNames.ENGLISH_ABBREVIATED); chars(", "); year()
}
val yearMonth = customFormat.parse("Apr, 2024")
check(yearMonth == YearMonth(2024, Month.APRIL))
val formatted = yearMonth.format(customFormat)
check(formatted == "Apr, 2024") 
   //sampleEnd
}