Skip to content

Implement YearMonth #457

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 3 commits into
base: master
Choose a base branch
from
Draft

Implement YearMonth #457

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
10a8a46
Implement YearMonth
dkhalanskyjb Nov 13, 2024
9540fa0
Implement java.io.Serializable for YearMonth
dkhalanskyjb Mar 20, 2025
77c4d23
Rewrite YearMonth on the JVM to wrap java.time.YearMonth
dkhalanskyjb Mar 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 18 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ The library provides a basic set of types for working with date and time:
- `Clock` to obtain the current instant;
- `LocalDateTime` to represent date and time components without a reference to the particular time zone;
- `LocalDate` to represent the components of date only;
- `YearMonth` to represent only the year and month components;
- `LocalTime` to represent the components of time only;
- `TimeZone` and `FixedOffsetTimeZone` provide time zone information to convert between `Instant` and `LocalDateTime`;
- `Month` and `DayOfWeek` enums;
Expand Down Expand Up @@ -67,6 +68,9 @@ Here is some basic advice on how to choose which of the date-carrying types to u

- Use `LocalDate` to represent the date of an event that does not have a specific time associated with it (like a birth date).

- Use `YearMonth` to represent the year and month of an event that does not have a specific day associated with it
or has a day-of-month that is inferred from the context (like a credit card expiration date).

- Use `LocalTime` to represent the time of an event that does not have a specific date associated with it.

## Operations
Expand Down Expand Up @@ -150,6 +154,16 @@ Note, that today's date really depends on the time zone in which you're observin
val knownDate = LocalDate(2020, 2, 21)
```

### Getting year and month components

A `YearMonth` represents a year and month without a day. You can obtain one from a `LocalDate`
by taking its `yearMonth` property.

```kotlin
val day = LocalDate(2020, 2, 21)
val yearMonth: YearMonth = day.yearMonth
```

### Getting local time components

A `LocalTime` represents local time without date. You can obtain one from an `Instant`
Expand Down Expand Up @@ -273,10 +287,10 @@ collection of all datetime fields, can be used instead.
```kotlin
// import kotlinx.datetime.format.*

val yearMonth = DateTimeComponents.Format { year(); char('-'); monthNumber() }
.parse("2024-01")
println(yearMonth.year)
println(yearMonth.monthNumber)
val monthDay = DateTimeComponents.Format { monthNumber(); char('/'); dayOfMonth() }
.parse("12/25")
println(monthDay.dayOfMonth) // 25
println(monthDay.monthNumber) // 12

val dateTimeOffset = DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET
.parse("2023-01-07T23:16:15.53+02:00")
Expand Down
89 changes: 82 additions & 7 deletions core/api/kotlinx-datetime.api
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ public final class kotlinx/datetime/ConvertersKt {
public static final fun toJavaLocalTime (Lkotlinx/datetime/LocalTime;)Ljava/time/LocalTime;
public static final fun toJavaMonth (Lkotlinx/datetime/Month;)Ljava/time/Month;
public static final fun toJavaPeriod (Lkotlinx/datetime/DatePeriod;)Ljava/time/Period;
public static final fun toJavaYearMonth (Lkotlinx/datetime/YearMonth;)Ljava/time/YearMonth;
public static final fun toJavaZoneId (Lkotlinx/datetime/TimeZone;)Ljava/time/ZoneId;
public static final fun toJavaZoneOffset (Lkotlinx/datetime/FixedOffsetTimeZone;)Ljava/time/ZoneOffset;
public static final fun toJavaZoneOffset (Lkotlinx/datetime/UtcOffset;)Ljava/time/ZoneOffset;
Expand All @@ -39,6 +40,7 @@ public final class kotlinx/datetime/ConvertersKt {
public static final fun toKotlinMonth (Ljava/time/Month;)Lkotlinx/datetime/Month;
public static final fun toKotlinTimeZone (Ljava/time/ZoneId;)Lkotlinx/datetime/TimeZone;
public static final fun toKotlinUtcOffset (Ljava/time/ZoneOffset;)Lkotlinx/datetime/UtcOffset;
public static final fun toKotlinYearMonth (Ljava/time/YearMonth;)Lkotlinx/datetime/YearMonth;
public static final fun toKotlinZoneOffset (Ljava/time/ZoneOffset;)Lkotlinx/datetime/FixedOffsetTimeZone;
}

Expand Down Expand Up @@ -480,6 +482,7 @@ public final class kotlinx/datetime/Ser : java/io/Externalizable {
public static final field DATE_TIME_TAG I
public static final field TIME_TAG I
public static final field UTC_OFFSET_TAG I
public static final field YEAR_MONTH_TAG I
public fun <init> ()V
public fun <init> (ILjava/lang/Object;)V
public fun readExternal (Ljava/io/ObjectInput;)V
Expand Down Expand Up @@ -552,6 +555,51 @@ public final class kotlinx/datetime/UtcOffsetKt {
public static final fun format (Lkotlinx/datetime/UtcOffset;Lkotlinx/datetime/format/DateTimeFormat;)Ljava/lang/String;
}

public final class kotlinx/datetime/YearMonth : java/io/Serializable, java/lang/Comparable {
public static final field Companion Lkotlinx/datetime/YearMonth$Companion;
public fun <init> (II)V
public fun <init> (ILkotlinx/datetime/Month;)V
public synthetic fun compareTo (Ljava/lang/Object;)I
public fun compareTo (Lkotlinx/datetime/YearMonth;)I
public fun equals (Ljava/lang/Object;)Z
public final fun getFirstDay ()Lkotlinx/datetime/LocalDate;
public final fun getLastDay ()Lkotlinx/datetime/LocalDate;
public final fun getMonth ()Lkotlinx/datetime/Month;
public final fun getNumberOfDays ()I
public final fun getYear ()I
public fun hashCode ()I
public fun toString ()Ljava/lang/String;
}

public final class kotlinx/datetime/YearMonth$Companion {
public final fun Format (Lkotlin/jvm/functions/Function1;)Lkotlinx/datetime/format/DateTimeFormat;
public final fun parse (Ljava/lang/CharSequence;Lkotlinx/datetime/format/DateTimeFormat;)Lkotlinx/datetime/YearMonth;
public static synthetic fun parse$default (Lkotlinx/datetime/YearMonth$Companion;Ljava/lang/CharSequence;Lkotlinx/datetime/format/DateTimeFormat;ILjava/lang/Object;)Lkotlinx/datetime/YearMonth;
public final fun serializer ()Lkotlinx/serialization/KSerializer;
}

public final class kotlinx/datetime/YearMonth$Formats {
public static final field INSTANCE Lkotlinx/datetime/YearMonth$Formats;
public final fun getISO ()Lkotlinx/datetime/format/DateTimeFormat;
}

public final class kotlinx/datetime/YearMonthKt {
public static final fun format (Lkotlinx/datetime/YearMonth;Lkotlinx/datetime/format/DateTimeFormat;)Ljava/lang/String;
public static final fun getYearMonth (Lkotlinx/datetime/LocalDate;)Lkotlinx/datetime/YearMonth;
public static final fun minus (Lkotlinx/datetime/YearMonth;ILkotlinx/datetime/DateTimeUnit$MonthBased;)Lkotlinx/datetime/YearMonth;
public static final fun minus (Lkotlinx/datetime/YearMonth;JLkotlinx/datetime/DateTimeUnit$MonthBased;)Lkotlinx/datetime/YearMonth;
public static final fun minusMonth (Lkotlinx/datetime/YearMonth;)Lkotlinx/datetime/YearMonth;
public static final fun minusYear (Lkotlinx/datetime/YearMonth;)Lkotlinx/datetime/YearMonth;
public static final fun monthsUntil (Lkotlinx/datetime/YearMonth;Lkotlinx/datetime/YearMonth;)I
public static final fun onDay (Lkotlinx/datetime/YearMonth;I)Lkotlinx/datetime/LocalDate;
public static final fun plus (Lkotlinx/datetime/YearMonth;ILkotlinx/datetime/DateTimeUnit$MonthBased;)Lkotlinx/datetime/YearMonth;
public static final fun plus (Lkotlinx/datetime/YearMonth;JLkotlinx/datetime/DateTimeUnit$MonthBased;)Lkotlinx/datetime/YearMonth;
public static final fun plusMonth (Lkotlinx/datetime/YearMonth;)Lkotlinx/datetime/YearMonth;
public static final fun plusYear (Lkotlinx/datetime/YearMonth;)Lkotlinx/datetime/YearMonth;
public static final fun until (Lkotlinx/datetime/YearMonth;Lkotlinx/datetime/YearMonth;Lkotlinx/datetime/DateTimeUnit$MonthBased;)J
public static final fun yearsUntil (Lkotlinx/datetime/YearMonth;Lkotlinx/datetime/YearMonth;)I
}

public final class kotlinx/datetime/format/AmPmMarker : java/lang/Enum {
public static final field AM Lkotlinx/datetime/format/AmPmMarker;
public static final field PM Lkotlinx/datetime/format/AmPmMarker;
Expand Down Expand Up @@ -605,11 +653,13 @@ public final class kotlinx/datetime/format/DateTimeComponents {
public final fun setTime (Lkotlinx/datetime/LocalTime;)V
public final fun setTimeZoneId (Ljava/lang/String;)V
public final fun setYear (Ljava/lang/Integer;)V
public final fun setYearMonth (Lkotlinx/datetime/YearMonth;)V
public final fun toInstantUsingOffset ()Lkotlinx/datetime/Instant;
public final fun toLocalDate ()Lkotlinx/datetime/LocalDate;
public final fun toLocalDateTime ()Lkotlinx/datetime/LocalDateTime;
public final fun toLocalTime ()Lkotlinx/datetime/LocalTime;
public final fun toUtcOffset ()Lkotlinx/datetime/UtcOffset;
public final fun toYearMonth ()Lkotlinx/datetime/YearMonth;
}

public final class kotlinx/datetime/format/DateTimeComponents$Companion {
Expand Down Expand Up @@ -643,25 +693,19 @@ public abstract interface class kotlinx/datetime/format/DateTimeFormatBuilder {
public abstract fun chars (Ljava/lang/String;)V
}

public abstract interface class kotlinx/datetime/format/DateTimeFormatBuilder$WithDate : kotlinx/datetime/format/DateTimeFormatBuilder {
public abstract interface class kotlinx/datetime/format/DateTimeFormatBuilder$WithDate : kotlinx/datetime/format/DateTimeFormatBuilder$WithYearMonth {
public abstract fun date (Lkotlinx/datetime/format/DateTimeFormat;)V
public abstract fun day (Lkotlinx/datetime/format/Padding;)V
public abstract fun dayOfMonth (Lkotlinx/datetime/format/Padding;)V
public abstract fun dayOfWeek (Lkotlinx/datetime/format/DayOfWeekNames;)V
public abstract fun dayOfYear (Lkotlinx/datetime/format/Padding;)V
public abstract fun monthName (Lkotlinx/datetime/format/MonthNames;)V
public abstract fun monthNumber (Lkotlinx/datetime/format/Padding;)V
public abstract fun year (Lkotlinx/datetime/format/Padding;)V
public abstract fun yearTwoDigits (I)V
}

public final class kotlinx/datetime/format/DateTimeFormatBuilder$WithDate$DefaultImpls {
public static synthetic fun day$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithDate;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
public static fun dayOfMonth (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithDate;Lkotlinx/datetime/format/Padding;)V
public static synthetic fun dayOfMonth$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithDate;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
public static synthetic fun dayOfYear$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithDate;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
public static synthetic fun monthNumber$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithDate;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
public static synthetic fun year$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithDate;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
}

public abstract interface class kotlinx/datetime/format/DateTimeFormatBuilder$WithDateTime : kotlinx/datetime/format/DateTimeFormatBuilder$WithDate, kotlinx/datetime/format/DateTimeFormatBuilder$WithTime {
Expand Down Expand Up @@ -716,6 +760,19 @@ public final class kotlinx/datetime/format/DateTimeFormatBuilder$WithUtcOffset$D
public static synthetic fun offsetSecondsOfMinute$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithUtcOffset;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
}

public abstract interface class kotlinx/datetime/format/DateTimeFormatBuilder$WithYearMonth : kotlinx/datetime/format/DateTimeFormatBuilder {
public abstract fun monthName (Lkotlinx/datetime/format/MonthNames;)V
public abstract fun monthNumber (Lkotlinx/datetime/format/Padding;)V
public abstract fun year (Lkotlinx/datetime/format/Padding;)V
public abstract fun yearMonth (Lkotlinx/datetime/format/DateTimeFormat;)V
public abstract fun yearTwoDigits (I)V
}

public final class kotlinx/datetime/format/DateTimeFormatBuilder$WithYearMonth$DefaultImpls {
public static synthetic fun monthNumber$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithYearMonth;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
public static synthetic fun year$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithYearMonth;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
}

public final class kotlinx/datetime/format/DateTimeFormatBuilderKt {
public static final fun alternativeParsing (Lkotlinx/datetime/format/DateTimeFormatBuilder;[Lkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function1;)V
public static final fun char (Lkotlinx/datetime/format/DateTimeFormatBuilder;C)V
Expand Down Expand Up @@ -967,3 +1024,21 @@ public final class kotlinx/datetime/serializers/UtcOffsetSerializer : kotlinx/se
public fun serialize (Lkotlinx/serialization/encoding/Encoder;Lkotlinx/datetime/UtcOffset;)V
}

public final class kotlinx/datetime/serializers/YearMonthComponentSerializer : kotlinx/serialization/KSerializer {
public static final field INSTANCE Lkotlinx/datetime/serializers/YearMonthComponentSerializer;
public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
public fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lkotlinx/datetime/YearMonth;
public fun getDescriptor ()Lkotlinx/serialization/descriptors/SerialDescriptor;
public synthetic fun serialize (Lkotlinx/serialization/encoding/Encoder;Ljava/lang/Object;)V
public fun serialize (Lkotlinx/serialization/encoding/Encoder;Lkotlinx/datetime/YearMonth;)V
}

public final class kotlinx/datetime/serializers/YearMonthIso8601Serializer : kotlinx/serialization/KSerializer {
public static final field INSTANCE Lkotlinx/datetime/serializers/YearMonthIso8601Serializer;
public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
public fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lkotlinx/datetime/YearMonth;
public fun getDescriptor ()Lkotlinx/serialization/descriptors/SerialDescriptor;
public synthetic fun serialize (Lkotlinx/serialization/encoding/Encoder;Ljava/lang/Object;)V
public fun serialize (Lkotlinx/serialization/encoding/Encoder;Lkotlinx/datetime/YearMonth;)V
}

Loading