Skip to content

Commit 186a5fc

Browse files
dkhalanskyjbdkhalanskyjb
committed
Implement YearMonth
Fixes #168 Fixes #184
1 parent 021c97b commit 186a5fc

26 files changed

+1887
-467
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
@@ -24,6 +24,7 @@ public final class kotlinx/datetime/ConvertersKt {
2424
public static final fun toJavaLocalDateTime (Lkotlinx/datetime/LocalDateTime;)Ljava/time/LocalDateTime;
2525
public static final fun toJavaLocalTime (Lkotlinx/datetime/LocalTime;)Ljava/time/LocalTime;
2626
public static final fun toJavaPeriod (Lkotlinx/datetime/DatePeriod;)Ljava/time/Period;
27+
public static final fun toJavaYearMonth (Lkotlinx/datetime/YearMonth;)Ljava/time/YearMonth;
2728
public static final fun toJavaZoneId (Lkotlinx/datetime/TimeZone;)Ljava/time/ZoneId;
2829
public static final fun toJavaZoneOffset (Lkotlinx/datetime/FixedOffsetTimeZone;)Ljava/time/ZoneOffset;
2930
public static final fun toJavaZoneOffset (Lkotlinx/datetime/UtcOffset;)Ljava/time/ZoneOffset;
@@ -35,6 +36,7 @@ public final class kotlinx/datetime/ConvertersKt {
3536
public static final fun toKotlinLocalTime (Ljava/time/LocalTime;)Lkotlinx/datetime/LocalTime;
3637
public static final fun toKotlinTimeZone (Ljava/time/ZoneId;)Lkotlinx/datetime/TimeZone;
3738
public static final fun toKotlinUtcOffset (Ljava/time/ZoneOffset;)Lkotlinx/datetime/UtcOffset;
39+
public static final fun toKotlinYearMonth (Ljava/time/YearMonth;)Lkotlinx/datetime/YearMonth;
3840
public static final fun toKotlinZoneOffset (Ljava/time/ZoneOffset;)Lkotlinx/datetime/FixedOffsetTimeZone;
3941
}
4042

@@ -484,6 +486,51 @@ public final class kotlinx/datetime/UtcOffsetKt {
484486
public static final fun format (Lkotlinx/datetime/UtcOffset;Lkotlinx/datetime/format/DateTimeFormat;)Ljava/lang/String;
485487
}
486488

489+
public final class kotlinx/datetime/YearMonth : java/lang/Comparable {
490+
public static final field Companion Lkotlinx/datetime/YearMonth$Companion;
491+
public fun <init> (II)V
492+
public fun <init> (ILjava/time/Month;)V
493+
public synthetic fun compareTo (Ljava/lang/Object;)I
494+
public fun compareTo (Lkotlinx/datetime/YearMonth;)I
495+
public fun equals (Ljava/lang/Object;)Z
496+
public final fun getFirstDay ()Lkotlinx/datetime/LocalDate;
497+
public final fun getLastDay ()Lkotlinx/datetime/LocalDate;
498+
public final fun getMonth ()Ljava/time/Month;
499+
public final fun getNumberOfDays ()I
500+
public final fun getYear ()I
501+
public fun hashCode ()I
502+
public fun toString ()Ljava/lang/String;
503+
}
504+
505+
public final class kotlinx/datetime/YearMonth$Companion {
506+
public final fun Format (Lkotlin/jvm/functions/Function1;)Lkotlinx/datetime/format/DateTimeFormat;
507+
public final fun parse (Ljava/lang/CharSequence;Lkotlinx/datetime/format/DateTimeFormat;)Lkotlinx/datetime/YearMonth;
508+
public static synthetic fun parse$default (Lkotlinx/datetime/YearMonth$Companion;Ljava/lang/CharSequence;Lkotlinx/datetime/format/DateTimeFormat;ILjava/lang/Object;)Lkotlinx/datetime/YearMonth;
509+
public final fun serializer ()Lkotlinx/serialization/KSerializer;
510+
}
511+
512+
public final class kotlinx/datetime/YearMonth$Formats {
513+
public static final field INSTANCE Lkotlinx/datetime/YearMonth$Formats;
514+
public final fun getISO ()Lkotlinx/datetime/format/DateTimeFormat;
515+
}
516+
517+
public final class kotlinx/datetime/YearMonthKt {
518+
public static final fun format (Lkotlinx/datetime/YearMonth;Lkotlinx/datetime/format/DateTimeFormat;)Ljava/lang/String;
519+
public static final fun getYearMonth (Lkotlinx/datetime/LocalDate;)Lkotlinx/datetime/YearMonth;
520+
public static final fun minus (Lkotlinx/datetime/YearMonth;ILkotlinx/datetime/DateTimeUnit$MonthBased;)Lkotlinx/datetime/YearMonth;
521+
public static final fun minus (Lkotlinx/datetime/YearMonth;JLkotlinx/datetime/DateTimeUnit$MonthBased;)Lkotlinx/datetime/YearMonth;
522+
public static final fun minusMonth (Lkotlinx/datetime/YearMonth;)Lkotlinx/datetime/YearMonth;
523+
public static final fun minusYear (Lkotlinx/datetime/YearMonth;)Lkotlinx/datetime/YearMonth;
524+
public static final fun monthsUntil (Lkotlinx/datetime/YearMonth;Lkotlinx/datetime/YearMonth;)I
525+
public static final fun onDay (Lkotlinx/datetime/YearMonth;I)Lkotlinx/datetime/LocalDate;
526+
public static final fun plus (Lkotlinx/datetime/YearMonth;ILkotlinx/datetime/DateTimeUnit$MonthBased;)Lkotlinx/datetime/YearMonth;
527+
public static final fun plus (Lkotlinx/datetime/YearMonth;JLkotlinx/datetime/DateTimeUnit$MonthBased;)Lkotlinx/datetime/YearMonth;
528+
public static final fun plusMonth (Lkotlinx/datetime/YearMonth;)Lkotlinx/datetime/YearMonth;
529+
public static final fun plusYear (Lkotlinx/datetime/YearMonth;)Lkotlinx/datetime/YearMonth;
530+
public static final fun until (Lkotlinx/datetime/YearMonth;Lkotlinx/datetime/YearMonth;Lkotlinx/datetime/DateTimeUnit$MonthBased;)J
531+
public static final fun yearsUntil (Lkotlinx/datetime/YearMonth;Lkotlinx/datetime/YearMonth;)I
532+
}
533+
487534
public final class kotlinx/datetime/format/AmPmMarker : java/lang/Enum {
488535
public static final field AM Lkotlinx/datetime/format/AmPmMarker;
489536
public static final field PM Lkotlinx/datetime/format/AmPmMarker;
@@ -537,11 +584,13 @@ public final class kotlinx/datetime/format/DateTimeComponents {
537584
public final fun setTime (Lkotlinx/datetime/LocalTime;)V
538585
public final fun setTimeZoneId (Ljava/lang/String;)V
539586
public final fun setYear (Ljava/lang/Integer;)V
587+
public final fun setYearMonth (Lkotlinx/datetime/YearMonth;)V
540588
public final fun toInstantUsingOffset ()Lkotlinx/datetime/Instant;
541589
public final fun toLocalDate ()Lkotlinx/datetime/LocalDate;
542590
public final fun toLocalDateTime ()Lkotlinx/datetime/LocalDateTime;
543591
public final fun toLocalTime ()Lkotlinx/datetime/LocalTime;
544592
public final fun toUtcOffset ()Lkotlinx/datetime/UtcOffset;
593+
public final fun toYearMonth ()Lkotlinx/datetime/YearMonth;
545594
}
546595

547596
public final class kotlinx/datetime/format/DateTimeComponents$Companion {
@@ -575,25 +624,19 @@ public abstract interface class kotlinx/datetime/format/DateTimeFormatBuilder {
575624
public abstract fun chars (Ljava/lang/String;)V
576625
}
577626

578-
public abstract interface class kotlinx/datetime/format/DateTimeFormatBuilder$WithDate : kotlinx/datetime/format/DateTimeFormatBuilder {
627+
public abstract interface class kotlinx/datetime/format/DateTimeFormatBuilder$WithDate : kotlinx/datetime/format/DateTimeFormatBuilder$WithYearMonth {
579628
public abstract fun date (Lkotlinx/datetime/format/DateTimeFormat;)V
580629
public abstract fun day (Lkotlinx/datetime/format/Padding;)V
581630
public abstract fun dayOfMonth (Lkotlinx/datetime/format/Padding;)V
582631
public abstract fun dayOfWeek (Lkotlinx/datetime/format/DayOfWeekNames;)V
583632
public abstract fun dayOfYear (Lkotlinx/datetime/format/Padding;)V
584-
public abstract fun monthName (Lkotlinx/datetime/format/MonthNames;)V
585-
public abstract fun monthNumber (Lkotlinx/datetime/format/Padding;)V
586-
public abstract fun year (Lkotlinx/datetime/format/Padding;)V
587-
public abstract fun yearTwoDigits (I)V
588633
}
589634

590635
public final class kotlinx/datetime/format/DateTimeFormatBuilder$WithDate$DefaultImpls {
591636
public static synthetic fun day$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithDate;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
592637
public static fun dayOfMonth (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithDate;Lkotlinx/datetime/format/Padding;)V
593638
public static synthetic fun dayOfMonth$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithDate;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
594639
public static synthetic fun dayOfYear$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithDate;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
595-
public static synthetic fun monthNumber$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithDate;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
596-
public static synthetic fun year$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithDate;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
597640
}
598641

599642
public abstract interface class kotlinx/datetime/format/DateTimeFormatBuilder$WithDateTime : kotlinx/datetime/format/DateTimeFormatBuilder$WithDate, kotlinx/datetime/format/DateTimeFormatBuilder$WithTime {
@@ -648,6 +691,19 @@ public final class kotlinx/datetime/format/DateTimeFormatBuilder$WithUtcOffset$D
648691
public static synthetic fun offsetSecondsOfMinute$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithUtcOffset;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
649692
}
650693

694+
public abstract interface class kotlinx/datetime/format/DateTimeFormatBuilder$WithYearMonth : kotlinx/datetime/format/DateTimeFormatBuilder {
695+
public abstract fun monthName (Lkotlinx/datetime/format/MonthNames;)V
696+
public abstract fun monthNumber (Lkotlinx/datetime/format/Padding;)V
697+
public abstract fun year (Lkotlinx/datetime/format/Padding;)V
698+
public abstract fun yearMonth (Lkotlinx/datetime/format/DateTimeFormat;)V
699+
public abstract fun yearTwoDigits (I)V
700+
}
701+
702+
public final class kotlinx/datetime/format/DateTimeFormatBuilder$WithYearMonth$DefaultImpls {
703+
public static synthetic fun monthNumber$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithYearMonth;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
704+
public static synthetic fun year$default (Lkotlinx/datetime/format/DateTimeFormatBuilder$WithYearMonth;Lkotlinx/datetime/format/Padding;ILjava/lang/Object;)V
705+
}
706+
651707
public final class kotlinx/datetime/format/DateTimeFormatBuilderKt {
652708
public static final fun alternativeParsing (Lkotlinx/datetime/format/DateTimeFormatBuilder;[Lkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function1;)V
653709
public static final fun char (Lkotlinx/datetime/format/DateTimeFormatBuilder;C)V
@@ -899,3 +955,21 @@ public final class kotlinx/datetime/serializers/UtcOffsetSerializer : kotlinx/se
899955
public fun serialize (Lkotlinx/serialization/encoding/Encoder;Lkotlinx/datetime/UtcOffset;)V
900956
}
901957

958+
public final class kotlinx/datetime/serializers/YearMonthComponentSerializer : kotlinx/serialization/KSerializer {
959+
public static final field INSTANCE Lkotlinx/datetime/serializers/YearMonthComponentSerializer;
960+
public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
961+
public fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lkotlinx/datetime/YearMonth;
962+
public fun getDescriptor ()Lkotlinx/serialization/descriptors/SerialDescriptor;
963+
public synthetic fun serialize (Lkotlinx/serialization/encoding/Encoder;Ljava/lang/Object;)V
964+
public fun serialize (Lkotlinx/serialization/encoding/Encoder;Lkotlinx/datetime/YearMonth;)V
965+
}
966+
967+
public final class kotlinx/datetime/serializers/YearMonthIso8601Serializer : kotlinx/serialization/KSerializer {
968+
public static final field INSTANCE Lkotlinx/datetime/serializers/YearMonthIso8601Serializer;
969+
public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
970+
public fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lkotlinx/datetime/YearMonth;
971+
public fun getDescriptor ()Lkotlinx/serialization/descriptors/SerialDescriptor;
972+
public synthetic fun serialize (Lkotlinx/serialization/encoding/Encoder;Ljava/lang/Object;)V
973+
public fun serialize (Lkotlinx/serialization/encoding/Encoder;Lkotlinx/datetime/YearMonth;)V
974+
}
975+

0 commit comments

Comments
 (0)