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.
A non-throwing version of the constructor is the orNull function.
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:
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
}Constructs a YearMonth instance from the given year-month components.
The range for year 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.
See also
for a version that returns null instead of throwing an exception when the parameters are invalid.
Throws
if year is out of range.
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, Month.APRIL)
check(yearMonth.year == 2024)
check(yearMonth.month == Month.APRIL)
//sampleEnd
}Constructs a YearMonth instance from the given year-month components.
The range for year 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.
See also
for a version that returns null instead of throwing an exception when the parameters are invalid.
Throws
if year is out of range.
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, Month.APRIL)
check(yearMonth.year == 2024)
check(yearMonth.month == Month.APRIL)
//sampleEnd
}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.
A non-throwing version of the constructor is the orNull function.
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:
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
}Constructs a YearMonth instance from the given year-month components.
The range for year 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.
See also
for a version that returns null instead of throwing an exception when the parameters are invalid.
Throws
if year is out of range.
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, Month.APRIL)
check(yearMonth.year == 2024)
check(yearMonth.month == Month.APRIL)
//sampleEnd
}