Skip to content

Commit 86db174

Browse files
dkhalanskyjbdkhalanskyjb
committed
Implement YearMonth
Fixes #168 Fixes #184
1 parent d15ec21 commit 86db174

26 files changed

+1887
-463
lines changed

‎README.md

Lines changed: 18 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ The library provides a basic set of types for working with date and time:
4040
- `Clock` to obtain the current instant;
4141
- `LocalDateTime` to represent date and time components without a reference to the particular time zone;
4242
- `LocalDate` to represent the components of date only;
43+
- `YearMonth` to represent only the year and month components;
4344
- `LocalTime` to represent the components of time only;
4445
- `TimeZone` and `FixedOffsetTimeZone` provide time zone information to convert between `Instant` and `LocalDateTime`;
4546
- `Month` and `DayOfWeek` enums;
@@ -67,6 +68,9 @@ Here is some basic advice on how to choose which of the date-carrying types to u
6768

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

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

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

157+
### Getting year and month components
158+
159+
A `YearMonth` represents a year and month without a day. You can obtain one from a `LocalDate`
160+
by taking its `yearMonth` property.
161+
162+
```kotlin
163+
val day = LocalDate(2020, 2, 21)
164+
val yearMonth: YearMonth = day.yearMonth
165+
```
166+
153167
### Getting local time components
154168

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

276-
val yearMonth = DateTimeComponents.Format { year(); char('-'); monthNumber() }
277-
.parse("2024-01")
278-
println(yearMonth.year)
279-
println(yearMonth.monthNumber)
290+
val monthDay = DateTimeComponents.Format { monthNumber(); char('/'); dayOfMonth() }
291+
.parse("12/25")
292+
println(monthDay.dayOfMonth) // 25
293+
println(monthDay.monthNumber) // 12
280294

281295
val dateTimeOffset = DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET
282296
.parse("2023-01-07T23:16:15.53+02:00")

‎core/api/kotlinx-datetime.api

Lines changed: 81 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ public final class kotlinx/datetime/ConvertersKt {
2626
public static final fun toJavaLocalTime (Lkotlinx/datetime/LocalTime;)Ljava/time/LocalTime;
2727
public static final fun toJavaMonth (Lkotlinx/datetime/Month;)Ljava/time/Month;
2828
public static final fun toJavaPeriod (Lkotlinx/datetime/DatePeriod;)Ljava/time/Period;
29+
public static final fun toJavaYearMonth (Lkotlinx/datetime/YearMonth;)Ljava/time/YearMonth;
2930
public static final fun toJavaZoneId (Lkotlinx/datetime/TimeZone;)Ljava/time/ZoneId;
3031
public static final fun toJavaZoneOffset (Lkotlinx/datetime/FixedOffsetTimeZone;)Ljava/time/ZoneOffset;
3132
public static final fun toJavaZoneOffset (Lkotlinx/datetime/UtcOffset;)Ljava/time/ZoneOffset;
@@ -39,6 +40,7 @@ public final class kotlinx/datetime/ConvertersKt {
3940
public static final fun toKotlinMonth (Ljava/time/Month;)Lkotlinx/datetime/Month;
4041
public static final fun toKotlinTimeZone (Ljava/time/ZoneId;)Lkotlinx/datetime/TimeZone;
4142
public static final fun toKotlinUtcOffset (Ljava/time/ZoneOffset;)Lkotlinx/datetime/UtcOffset;
43+
public static final fun toKotlinYearMonth (Ljava/time/YearMonth;)Lkotlinx/datetime/YearMonth;
4244
public static final fun toKotlinZoneOffset (Ljava/time/ZoneOffset;)Lkotlinx/datetime/FixedOffsetTimeZone;
4345
}
4446

@@ -615,6 +617,51 @@ public final class kotlinx/datetime/UtcOffsetKt {
615617
public static final fun format (Lkotlinx/datetime/UtcOffset;Lkotlinx/datetime/format/DateTimeFormat;)Ljava/lang/String;
616618
}
617619

620+
public final class kotlinx/datetime/YearMonth : java/lang/Comparable {
621+
public static final field Companion Lkotlinx/datetime/YearMonth$Companion;
622+
public fun <init> (II)V
623+
public fun <init> (ILkotlinx/datetime/Month;)V
624+
public synthetic fun compareTo (Ljava/lang/Object;)I
625+
public fun compareTo (Lkotlinx/datetime/YearMonth;)I
626+
public fun equals (Ljava/lang/Object;)Z
627+
public final fun getFirstDay ()Lkotlinx/datetime/LocalDate;
628+
public final fun getLastDay ()Lkotlinx/datetime/LocalDate;
629+
public final fun getMonth ()Lkotlinx/datetime/Month;
630+
public final fun getNumberOfDays ()I
631+
public final fun getYear ()I
632+
public fun hashCode ()I
633+
public fun toString ()Ljava/lang/String;
634+
}
635+
636+
public final class kotlinx/datetime/YearMonth$Companion {
637+
public final fun Format (Lkotlin/jvm/functions/Function1;)Lkotlinx/datetime/format/DateTimeFormat;
638+
public final fun parse (Ljava/lang/CharSequence;Lkotlinx/datetime/format/DateTimeFormat;)Lkotlinx/datetime/YearMonth;
639+
public static synthetic fun parse$default (Lkotlinx/datetime/YearMonth$Companion;Ljava/lang/CharSequence;Lkotlinx/datetime/format/DateTimeFormat;ILjava/lang/Object;)Lkotlinx/datetime/YearMonth;
640+
public final fun serializer ()Lkotlinx/serialization/KSerializer;
641+
}
642+
643+
public final class kotlinx/datetime/YearMonth$Formats {
644+
public static final field INSTANCE Lkotlinx/datetime/YearMonth$Formats;
645+
public final fun getISO ()Lkotlinx/datetime/format/DateTimeFormat;
646+
}
647+
648+
public final class kotlinx/datetime/YearMonthKt {
649+
public static final fun format (Lkotlinx/datetime/YearMonth;Lkotlinx/datetime/format/DateTimeFormat;)Ljava/lang/String;
650+
public static final fun getYearMonth (Lkotlinx/datetime/LocalDate;)Lkotlinx/datetime/YearMonth;
651+
public static final fun minus (Lkotlinx/datetime/YearMonth;ILkotlinx/datetime/DateTimeUnit$MonthBased;)Lkotlinx/datetime/YearMonth;
652+
public static final fun minus (Lkotlinx/datetime/YearMonth;JLkotlinx/datetime/DateTimeUnit$MonthBased;)Lkotlinx/datetime/YearMonth;
653+
public static final fun minusMonth (Lkotlinx/datetime/YearMonth;)Lkotlinx/datetime/YearMonth;
654+
public static final fun minusYear (Lkotlinx/datetime/YearMonth;)Lkotlinx/datetime/YearMonth;
655+
public static final fun monthsUntil (Lkotlinx/datetime/YearMonth;Lkotlinx/datetime/YearMonth;)I
656+
public static final fun onDay (Lkotlinx/datetime/YearMonth;I)Lkotlinx/datetime/LocalDate;
657+
public static final fun plus (Lkotlinx/datetime/YearMonth;ILkotlinx/datetime/DateTimeUnit$MonthBased;)Lkotlinx/datetime/YearMonth;
658+
public static final fun plus (Lkotlinx/datetime/YearMonth;JLkotlinx/datetime/DateTimeUnit$MonthBased;)Lkotlinx/datetime/YearMonth;
659+
public static final fun plusMonth (Lkotlinx/datetime/YearMonth;)Lkotlinx/datetime/YearMonth;
660+
public static final fun plusYear (Lkotlinx/datetime/YearMonth;)Lkotlinx/datetime/YearMonth;
661+
public static final fun until (Lkotlinx/datetime/YearMonth;Lkotlinx/datetime/YearMonth;Lkotlinx/datetime/DateTimeUnit$MonthBased;)J
662+
public static final fun yearsUntil (Lkotlinx/datetime/YearMonth;Lkotlinx/datetime/YearMonth;)I
663+
}
664+
618665
public final class kotlinx/datetime/format/AmPmMarker : java/lang/Enum {
619666
public static final field AM Lkotlinx/datetime/format/AmPmMarker;
620667
public static final field PM Lkotlinx/datetime/format/AmPmMarker;
@@ -668,11 +715,13 @@ public final class kotlinx/datetime/format/DateTimeComponents {
668715
public final fun setTime (Lkotlinx/datetime/LocalTime;)V
669716
public final fun setTimeZoneId (Ljava/lang/String;)V
670717
public final fun setYear (Ljava/lang/Integer;)V
718+
public final fun setYearMonth (Lkotlinx/datetime/YearMonth;)V
671719
public final fun toInstantUsingOffset ()Lkotlinx/datetime/Instant;
672720
public final fun toLocalDate ()Lkotlinx/datetime/LocalDate;
673721
public final fun toLocalDateTime ()Lkotlinx/datetime/LocalDateTime;
674722
public final fun toLocalTime ()Lkotlinx/datetime/LocalTime;
675723
public final fun toUtcOffset ()Lkotlinx/datetime/UtcOffset;
724+
public final fun toYearMonth ()Lkotlinx/datetime/YearMonth;
676725
}
677726

678727
public final class kotlinx/datetime/format/DateTimeComponents$Companion {
@@ -706,25 +755,19 @@ public abstract interface class kotlinx/datetime/format/DateTimeFormatBuilder {
706755
public abstract fun chars (Ljava/lang/String;)V
707756
}
708757

709-
public abstract interface class kotlinx/datetime/format/DateTimeFormatBuilder$WithDate : kotlinx/datetime/format/DateTimeFormatBuilder {
758+
public abstract interface class kotlinx/datetime/format/DateTimeFormatBuilder$WithDate : kotlinx/datetime/format/DateTimeFormatBuilder$WithYearMonth {
710759
public abstract fun date (Lkotlinx/datetime/format/DateTimeFormat;)V
711760
public abstract fun day (Lkotlinx/datetime/format/Padding;)V
712761
public abstract fun dayOfMonth (Lkotlinx/datetime/format/Padding;)V
713762
public abstract fun dayOfWeek (Lkotlinx/datetime/format/DayOfWeekNames;)V
714763
public abstract fun dayOfYear (Lkotlinx/datetime/format/Padding;)V
715-
public abstract fun monthName (Lkotlinx/datetime/format/MonthNames;)V
716-
public abstract fun monthNumber (Lkotlinx/datetime/format/Padding;)V
717-
public abstract fun year (Lkotlinx/datetime/format/Padding;)V
718-
public abstract fun yearTwoDigits (I)V
719764
}
720765

721766
public final class kotlinx/datetime/format/DateTimeFormatBuilder$WithDate$DefaultImpls {
722767
public static synthetic fun day$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithDate;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
723768
public static fun dayOfMonth (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithDate;Lkotlinx/datetime/format/Padding;)V
724769
public static synthetic fun dayOfMonth$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithDate;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
725770
public static synthetic fun dayOfYear$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithDate;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
726-
public static synthetic fun monthNumber$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithDate;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
727-
public static synthetic fun year$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithDate;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
728771
}
729772

730773
public abstract interface class kotlinx/datetime/format/DateTimeFormatBuilder$WithDateTime : kotlinx/datetime/format/DateTimeFormatBuilder$WithDate, kotlinx/datetime/format/DateTimeFormatBuilder$WithTime {
@@ -779,6 +822,19 @@ public final class kotlinx/datetime/format/DateTimeFormatBuilder$WithUtcOffset$D
779822
public static synthetic fun offsetSecondsOfMinute$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithUtcOffset;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
780823
}
781824

825+
public abstract interface class kotlinx/datetime/format/DateTimeFormatBuilder$WithYearMonth : kotlinx/datetime/format/DateTimeFormatBuilder {
826+
public abstract fun monthName (Lkotlinx/datetime/format/MonthNames;)V
827+
public abstract fun monthNumber (Lkotlinx/datetime/format/Padding;)V
828+
public abstract fun year (Lkotlinx/datetime/format/Padding;)V
829+
public abstract fun yearMonth (Lkotlinx/datetime/format/DateTimeFormat;)V
830+
public abstract fun yearTwoDigits (I)V
831+
}
832+
833+
public final class kotlinx/datetime/format/DateTimeFormatBuilder$WithYearMonth$DefaultImpls {
834+
public static synthetic fun monthNumber$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithYearMonth;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
835+
public static synthetic fun year$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithYearMonth;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
836+
}
837+
782838
public final class kotlinx/datetime/format/DateTimeFormatBuilderKt {
783839
public static final fun alternativeParsing (Lkotlinx/datetime/format/DateTimeFormatBuilder;[Lkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function1;)V
784840
public static final fun char (Lkotlinx/datetime/format/DateTimeFormatBuilder;C)V
@@ -1030,3 +1086,21 @@ public final class kotlinx/datetime/serializers/UtcOffsetSerializer : kotlinx/se
10301086
public fun serialize (Lkotlinx/serialization/encoding/Encoder;Lkotlinx/datetime/UtcOffset;)V
10311087
}
10321088

1089+
public final class kotlinx/datetime/serializers/YearMonthComponentSerializer : kotlinx/serialization/KSerializer {
1090+
public static final field INSTANCE Lkotlinx/datetime/serializers/YearMonthComponentSerializer;
1091+
public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
1092+
public fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lkotlinx/datetime/YearMonth;
1093+
public fun getDescriptor ()Lkotlinx/serialization/descriptors/SerialDescriptor;
1094+
public synthetic fun serialize (Lkotlinx/serialization/encoding/Encoder;Ljava/lang/Object;)V
1095+
public fun serialize (Lkotlinx/serialization/encoding/Encoder;Lkotlinx/datetime/YearMonth;)V
1096+
}
1097+
1098+
public final class kotlinx/datetime/serializers/YearMonthIso8601Serializer : kotlinx/serialization/KSerializer {
1099+
public static final field INSTANCE Lkotlinx/datetime/serializers/YearMonthIso8601Serializer;
1100+
public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
1101+
public fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lkotlinx/datetime/YearMonth;
1102+
public fun getDescriptor ()Lkotlinx/serialization/descriptors/SerialDescriptor;
1103+
public synthetic fun serialize (Lkotlinx/serialization/encoding/Encoder;Ljava/lang/Object;)V
1104+
public fun serialize (Lkotlinx/serialization/encoding/Encoder;Lkotlinx/datetime/YearMonth;)V
1105+
}
1106+

0 commit comments

Comments
 (0)