Skip to content

Commit 10a8a46

Browse files
dkhalanskyjbdkhalanskyjb
committed
Implement YearMonth
Fixes #168 Fixes #184
1 parent 98c3e53 commit 10a8a46

26 files changed

+1887
-463
lines changed

‎README.md

+18-4
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

+81-7
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

@@ -552,6 +554,51 @@ public final class kotlinx/datetime/UtcOffsetKt {
552554
public static final fun format (Lkotlinx/datetime/UtcOffset;Lkotlinx/datetime/format/DateTimeFormat;)Ljava/lang/String;
553555
}
554556

557+
public final class kotlinx/datetime/YearMonth : java/lang/Comparable {
558+
public static final field Companion Lkotlinx/datetime/YearMonth$Companion;
559+
public fun <init> (II)V
560+
public fun <init> (ILkotlinx/datetime/Month;)V
561+
public synthetic fun compareTo (Ljava/lang/Object;)I
562+
public fun compareTo (Lkotlinx/datetime/YearMonth;)I
563+
public fun equals (Ljava/lang/Object;)Z
564+
public final fun getFirstDay ()Lkotlinx/datetime/LocalDate;
565+
public final fun getLastDay ()Lkotlinx/datetime/LocalDate;
566+
public final fun getMonth ()Lkotlinx/datetime/Month;
567+
public final fun getNumberOfDays ()I
568+
public final fun getYear ()I
569+
public fun hashCode ()I
570+
public fun toString ()Ljava/lang/String;
571+
}
572+
573+
public final class kotlinx/datetime/YearMonth$Companion {
574+
public final fun Format (Lkotlin/jvm/functions/Function1;)Lkotlinx/datetime/format/DateTimeFormat;
575+
public final fun parse (Ljava/lang/CharSequence;Lkotlinx/datetime/format/DateTimeFormat;)Lkotlinx/datetime/YearMonth;
576+
public static synthetic fun parse$default (Lkotlinx/datetime/YearMonth$Companion;Ljava/lang/CharSequence;Lkotlinx/datetime/format/DateTimeFormat;ILjava/lang/Object;)Lkotlinx/datetime/YearMonth;
577+
public final fun serializer ()Lkotlinx/serialization/KSerializer;
578+
}
579+
580+
public final class kotlinx/datetime/YearMonth$Formats {
581+
public static final field INSTANCE Lkotlinx/datetime/YearMonth$Formats;
582+
public final fun getISO ()Lkotlinx/datetime/format/DateTimeFormat;
583+
}
584+
585+
public final class kotlinx/datetime/YearMonthKt {
586+
public static final fun format (Lkotlinx/datetime/YearMonth;Lkotlinx/datetime/format/DateTimeFormat;)Ljava/lang/String;
587+
public static final fun getYearMonth (Lkotlinx/datetime/LocalDate;)Lkotlinx/datetime/YearMonth;
588+
public static final fun minus (Lkotlinx/datetime/YearMonth;ILkotlinx/datetime/DateTimeUnit$MonthBased;)Lkotlinx/datetime/YearMonth;
589+
public static final fun minus (Lkotlinx/datetime/YearMonth;JLkotlinx/datetime/DateTimeUnit$MonthBased;)Lkotlinx/datetime/YearMonth;
590+
public static final fun minusMonth (Lkotlinx/datetime/YearMonth;)Lkotlinx/datetime/YearMonth;
591+
public static final fun minusYear (Lkotlinx/datetime/YearMonth;)Lkotlinx/datetime/YearMonth;
592+
public static final fun monthsUntil (Lkotlinx/datetime/YearMonth;Lkotlinx/datetime/YearMonth;)I
593+
public static final fun onDay (Lkotlinx/datetime/YearMonth;I)Lkotlinx/datetime/LocalDate;
594+
public static final fun plus (Lkotlinx/datetime/YearMonth;ILkotlinx/datetime/DateTimeUnit$MonthBased;)Lkotlinx/datetime/YearMonth;
595+
public static final fun plus (Lkotlinx/datetime/YearMonth;JLkotlinx/datetime/DateTimeUnit$MonthBased;)Lkotlinx/datetime/YearMonth;
596+
public static final fun plusMonth (Lkotlinx/datetime/YearMonth;)Lkotlinx/datetime/YearMonth;
597+
public static final fun plusYear (Lkotlinx/datetime/YearMonth;)Lkotlinx/datetime/YearMonth;
598+
public static final fun until (Lkotlinx/datetime/YearMonth;Lkotlinx/datetime/YearMonth;Lkotlinx/datetime/DateTimeUnit$MonthBased;)J
599+
public static final fun yearsUntil (Lkotlinx/datetime/YearMonth;Lkotlinx/datetime/YearMonth;)I
600+
}
601+
555602
public final class kotlinx/datetime/format/AmPmMarker : java/lang/Enum {
556603
public static final field AM Lkotlinx/datetime/format/AmPmMarker;
557604
public static final field PM Lkotlinx/datetime/format/AmPmMarker;
@@ -605,11 +652,13 @@ public final class kotlinx/datetime/format/DateTimeComponents {
605652
public final fun setTime (Lkotlinx/datetime/LocalTime;)V
606653
public final fun setTimeZoneId (Ljava/lang/String;)V
607654
public final fun setYear (Ljava/lang/Integer;)V
655+
public final fun setYearMonth (Lkotlinx/datetime/YearMonth;)V
608656
public final fun toInstantUsingOffset ()Lkotlinx/datetime/Instant;
609657
public final fun toLocalDate ()Lkotlinx/datetime/LocalDate;
610658
public final fun toLocalDateTime ()Lkotlinx/datetime/LocalDateTime;
611659
public final fun toLocalTime ()Lkotlinx/datetime/LocalTime;
612660
public final fun toUtcOffset ()Lkotlinx/datetime/UtcOffset;
661+
public final fun toYearMonth ()Lkotlinx/datetime/YearMonth;
613662
}
614663

615664
public final class kotlinx/datetime/format/DateTimeComponents$Companion {
@@ -643,25 +692,19 @@ public abstract interface class kotlinx/datetime/format/DateTimeFormatBuilder {
643692
public abstract fun chars (Ljava/lang/String;)V
644693
}
645694

646-
public abstract interface class kotlinx/datetime/format/DateTimeFormatBuilder$WithDate : kotlinx/datetime/format/DateTimeFormatBuilder {
695+
public abstract interface class kotlinx/datetime/format/DateTimeFormatBuilder$WithDate : kotlinx/datetime/format/DateTimeFormatBuilder$WithYearMonth {
647696
public abstract fun date (Lkotlinx/datetime/format/DateTimeFormat;)V
648697
public abstract fun day (Lkotlinx/datetime/format/Padding;)V
649698
public abstract fun dayOfMonth (Lkotlinx/datetime/format/Padding;)V
650699
public abstract fun dayOfWeek (Lkotlinx/datetime/format/DayOfWeekNames;)V
651700
public abstract fun dayOfYear (Lkotlinx/datetime/format/Padding;)V
652-
public abstract fun monthName (Lkotlinx/datetime/format/MonthNames;)V
653-
public abstract fun monthNumber (Lkotlinx/datetime/format/Padding;)V
654-
public abstract fun year (Lkotlinx/datetime/format/Padding;)V
655-
public abstract fun yearTwoDigits (I)V
656701
}
657702

658703
public final class kotlinx/datetime/format/DateTimeFormatBuilder$WithDate$DefaultImpls {
659704
public static synthetic fun day$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithDate;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
660705
public static fun dayOfMonth (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithDate;Lkotlinx/datetime/format/Padding;)V
661706
public static synthetic fun dayOfMonth$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithDate;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
662707
public static synthetic fun dayOfYear$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithDate;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
663-
public static synthetic fun monthNumber$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithDate;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
664-
public static synthetic fun year$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithDate;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
665708
}
666709

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

762+
public abstract interface class kotlinx/datetime/format/DateTimeFormatBuilder$WithYearMonth : kotlinx/datetime/format/DateTimeFormatBuilder {
763+
public abstract fun monthName (Lkotlinx/datetime/format/MonthNames;)V
764+
public abstract fun monthNumber (Lkotlinx/datetime/format/Padding;)V
765+
public abstract fun year (Lkotlinx/datetime/format/Padding;)V
766+
public abstract fun yearMonth (Lkotlinx/datetime/format/DateTimeFormat;)V
767+
public abstract fun yearTwoDigits (I)V
768+
}
769+
770+
public final class kotlinx/datetime/format/DateTimeFormatBuilder$WithYearMonth$DefaultImpls {
771+
public static synthetic fun monthNumber$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithYearMonth;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
772+
public static synthetic fun year$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithYearMonth;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
773+
}
774+
719775
public final class kotlinx/datetime/format/DateTimeFormatBuilderKt {
720776
public static final fun alternativeParsing (Lkotlinx/datetime/format/DateTimeFormatBuilder;[Lkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function1;)V
721777
public static final fun char (Lkotlinx/datetime/format/DateTimeFormatBuilder;C)V
@@ -967,3 +1023,21 @@ public final class kotlinx/datetime/serializers/UtcOffsetSerializer : kotlinx/se
9671023
public fun serialize (Lkotlinx/serialization/encoding/Encoder;Lkotlinx/datetime/UtcOffset;)V
9681024
}
9691025

1026+
public final class kotlinx/datetime/serializers/YearMonthComponentSerializer : kotlinx/serialization/KSerializer {
1027+
public static final field INSTANCE Lkotlinx/datetime/serializers/YearMonthComponentSerializer;
1028+
public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
1029+
public fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lkotlinx/datetime/YearMonth;
1030+
public fun getDescriptor ()Lkotlinx/serialization/descriptors/SerialDescriptor;
1031+
public synthetic fun serialize (Lkotlinx/serialization/encoding/Encoder;Ljava/lang/Object;)V
1032+
public fun serialize (Lkotlinx/serialization/encoding/Encoder;Lkotlinx/datetime/YearMonth;)V
1033+
}
1034+
1035+
public final class kotlinx/datetime/serializers/YearMonthIso8601Serializer : kotlinx/serialization/KSerializer {
1036+
public static final field INSTANCE Lkotlinx/datetime/serializers/YearMonthIso8601Serializer;
1037+
public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
1038+
public fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lkotlinx/datetime/YearMonth;
1039+
public fun getDescriptor ()Lkotlinx/serialization/descriptors/SerialDescriptor;
1040+
public synthetic fun serialize (Lkotlinx/serialization/encoding/Encoder;Ljava/lang/Object;)V
1041+
public fun serialize (Lkotlinx/serialization/encoding/Encoder;Lkotlinx/datetime/YearMonth;)V
1042+
}
1043+

0 commit comments

Comments
 (0)