Add LocalDate.createOrNull

Author: dkhalanskyjb

core/api/kotlinx-datetime.api

@@ -335,6 +335,8 @@ public final class kotlinx/datetime/LocalDate : java/io/Serializable, java/lang/
 
 public final class kotlinx/datetime/LocalDate$Companion {
 	public final fun Format (Lkotlin/jvm/functions/Function1;)Lkotlinx/datetime/format/DateTimeFormat;
+	public final fun createOrNull (III)Lkotlinx/datetime/LocalDate;
+	public final fun createOrNull (ILkotlinx/datetime/Month;I)Lkotlinx/datetime/LocalDate;
 	public final fun fromEpochDays (I)Lkotlinx/datetime/LocalDate;
 	public final fun fromEpochDays (J)Lkotlinx/datetime/LocalDate;
 	public final fun parse (Ljava/lang/CharSequence;Lkotlinx/datetime/format/DateTimeFormat;)Lkotlinx/datetime/LocalDate;

core/api/kotlinx-datetime.klib.api

@@ -431,6 +431,8 @@ final class kotlinx.datetime/LocalDate : kotlin/Comparable<kotlinx.datetime/Loca
 
     final object Companion { // kotlinx.datetime/LocalDate.Companion|null[0]
         final fun Format(kotlin/Function1<kotlinx.datetime.format/DateTimeFormatBuilder.WithDate, kotlin/Unit>): kotlinx.datetime.format/DateTimeFormat<kotlinx.datetime/LocalDate> // kotlinx.datetime/LocalDate.Companion.Format|Format(kotlin.Function1<kotlinx.datetime.format.DateTimeFormatBuilder.WithDate,kotlin.Unit>){}[0]
+        final fun createOrNull(kotlin/Int, kotlin/Int, kotlin/Int): kotlinx.datetime/LocalDate? // kotlinx.datetime/LocalDate.Companion.createOrNull|createOrNull(kotlin.Int;kotlin.Int;kotlin.Int){}[0]
+        final fun createOrNull(kotlin/Int, kotlinx.datetime/Month, kotlin/Int): kotlinx.datetime/LocalDate? // kotlinx.datetime/LocalDate.Companion.createOrNull|createOrNull(kotlin.Int;kotlinx.datetime.Month;kotlin.Int){}[0]
         final fun fromEpochDays(kotlin/Int): kotlinx.datetime/LocalDate // kotlinx.datetime/LocalDate.Companion.fromEpochDays|fromEpochDays(kotlin.Int){}[0]
         final fun fromEpochDays(kotlin/Long): kotlinx.datetime/LocalDate // kotlinx.datetime/LocalDate.Companion.fromEpochDays|fromEpochDays(kotlin.Long){}[0]
         final fun parse(kotlin/CharSequence, kotlinx.datetime.format/DateTimeFormat<kotlinx.datetime/LocalDate> = ...): kotlinx.datetime/LocalDate // kotlinx.datetime/LocalDate.Companion.parse|parse(kotlin.CharSequence;kotlinx.datetime.format.DateTimeFormat<kotlinx.datetime.LocalDate>){}[0]

core/common/src/LocalDate.kt

@@ -72,6 +72,35 @@ import kotlin.internal.*
 @Serializable(with = LocalDateSerializer::class)
 public expect class LocalDate : Comparable<LocalDate> {
     public companion object {
+        /**
+         * Constructs a [LocalDate] instance from the given date components
+         * or returns `null` if a value is out of range or invalid.
+         *
+         * The components [month] and [day] are 1-based.
+         *
+         * The supported ranges of components:
+         * - [year] the range is at least enough to represent dates of all instants between
+         *          [Instant.DISTANT_PAST] and [Instant.DISTANT_FUTURE]
+         * - [month] `1..12`
+         * - [day] `1..31`, the upper bound can be less, depending on the month
+         *
+         * @sample kotlinx.datetime.test.samples.LocalDateSamples.createOrNullMonthNumber
+         */
+        public fun createOrNull(year: Int, month: Int, day: Int): LocalDate?
+
+        /**
+         * Constructs a [LocalDate] instance from the given date components
+         * or returns `null` if a value is out of range or invalid.
+         *
+         * The supported ranges of components:
+         * - [year] the range at least is enough to represent dates of all instants between
+         *          [Instant.DISTANT_PAST] and [Instant.DISTANT_FUTURE]
+         * - [month] all values of the [Month] enum
+         * - [day] `1..31`, the upper bound can be less, depending on the month
+         *
+         * @sample kotlinx.datetime.test.samples.LocalDateSamples.createOrNull
+         */
+        public fun createOrNull(year: Int, month: Month, day: Int): LocalDate?
         /**
          * A shortcut for calling [DateTimeFormat.parse].
          *

core/common/test/LocalDateTest.kt

@@ -231,6 +231,21 @@ class LocalDateTest {
         }
     }
 
+    @Test
+    fun createOrNull() {
+        validDates.forEach { (year, month, day) ->
+            val expected = LocalDate(year, month, day)
+            assertEquals(expected, LocalDate.createOrNull(year, month, day))
+            assertEquals(expected, LocalDate.createOrNull(year, Month(month), day))
+        }
+        invalidDates.forEach { (year, month, day) ->
+            assertNull(LocalDate.createOrNull(year, month, day))
+            runCatching { Month(month) }.onSuccess { monthEnum ->
+                assertNull(LocalDate.createOrNull(year, monthEnum, day))
+            }
+        }
+    }
+
     @Test
     fun fromEpochDays() {
         /** This test uses [LocalDate.next] and [LocalDate.previous] and not [LocalDate.plus] because, on Native,
@@ -286,17 +301,44 @@ class LocalDateTest {
 }
 
 fun checkInvalidDate(constructor: (year: Int, month: Int, day: Int) -> LocalDate) {
-    assertFailsWith<IllegalArgumentException> { constructor(2007, 2, 29) }
-    assertEquals(29, constructor(2008, 2, 29).day)
-    assertFailsWith<IllegalArgumentException> { constructor(2007, 4, 31) }
-    assertFailsWith<IllegalArgumentException> { constructor(2007, 1, 0) }
-    assertFailsWith<IllegalArgumentException> { constructor(2007,1, 32) }
-    assertFailsWith<IllegalArgumentException> { constructor(Int.MIN_VALUE, 1, 1) }
-    assertFailsWith<IllegalArgumentException> { constructor(2007, 1, 32) }
-    assertFailsWith<IllegalArgumentException> { constructor(2007, 0, 1) }
-    assertFailsWith<IllegalArgumentException> { constructor(2007, 13, 1) }
+    invalidDates.forEach { (year, month, day) ->
+        assertFailsWith<IllegalArgumentException> { constructor(year, month, day) }
+    }
+    validDates.forEach { (year, month, day) ->
+        val date = constructor(year, month, day)
+        assertEquals(year, date.year)
+        assertEquals(month, date.month.number)
+        assertEquals(day, date.day)
+    }
 }
 
+val invalidDates = listOf(
+    Triple(2007, 2, 29),
+    Triple(2007, 4, 31),
+    Triple(2007, 1, 0),
+    Triple(2007, 1, 32),
+    Triple(Int.MIN_VALUE, 1, 1),
+    Triple(2007, 1, 32),
+    Triple(2007, 0, 1),
+    Triple(2007, 13, 1),
+)
+
+val validDates = listOf(
+    Triple(2007, 1, 1),
+    Triple(2007, 2, 28),
+    Triple(2008, 2, 29),
+    Triple(2007, 3, 31),
+    Triple(2007, 4, 30),
+    Triple(2007, 5, 31),
+    Triple(2007, 6, 30),
+    Triple(2007, 7, 31),
+    Triple(2007, 8, 31),
+    Triple(2007, 9, 30),
+    Triple(2007, 10, 31),
+    Triple(2007, 11, 30),
+    Triple(2007, 12, 31),
+)
+
 private val LocalDate.next: LocalDate get() =
     if (day != month.number.monthLength(isLeapYear(year))) {
         LocalDate(year, month.number, day + 1)

core/common/test/samples/LocalDateSamples.kt

@@ -69,6 +69,26 @@ class LocalDateSamples {
         check(date.day == 16)
     }
 
+    @Test
+    fun createOrNullMonthNumber() {
+        // Constructing a LocalDate value using `createOrNull`
+        val date = LocalDate.createOrNull(2024, 4, 16)
+        // For valid values, `createOrNull` is equivalent to the constructor
+        check(date == LocalDate(2024, 4, 16))
+        // If a value can not be constructed, null is returned
+        check(LocalDate.createOrNull(2024, 1, 99) == null)
+    }
+
+    @Test
+    fun createOrNull() {
+        // Constructing a LocalDate value using `createOrNull`
+        val date = LocalDate.createOrNull(2024, Month.APRIL, 16)
+        // For valid values, `createOrNull` is equivalent to the constructor
+        check(date == LocalDate(2024, Month.APRIL, 16))
+        // If a value can not be constructed, null is returned
+        check(LocalDate.createOrNull(2024, Month.FEBRUARY, 31) == null)
+    }
+
     @Test
     fun year() {
         // Getting the year

core/commonKotlin/src/LocalDate.kt

@@ -53,6 +53,17 @@ public actual class LocalDate actual constructor(public actual val year: Int, mo
         @Deprecated("This overload is only kept for binary compatibility", level = DeprecationLevel.HIDDEN)
         public fun parse(isoString: String): LocalDate = parse(input = isoString)
 
+        public actual fun createOrNull(year: Int, month: Int, day: Int): LocalDate? =
+            if (!isValidYear(year) || month !in 1..12 || day !in 1..31 ||
+                (day > 28 && day > month.monthLength(isLeapYear(year)))) {
+                null
+            } else {
+                LocalDate(year, month, day)
+            }
+
+        public actual fun createOrNull(year: Int, month: Month, day: Int): LocalDate? =
+            createOrNull(year, month.number, day)
+
         // org.threeten.bp.LocalDate#toEpochDay
         public actual fun fromEpochDays(epochDays: Long): LocalDate {
             // LocalDate(-999_999_999, 1, 1).toEpochDay(), LocalDate(999_999_999, 12, 31).toEpochDay()

core/jvm/src/LocalDate.kt

@@ -22,6 +22,20 @@ public actual class LocalDate internal constructor(
     internal val value: jtLocalDate
 ) : Comparable<LocalDate>, java.io.Serializable {
     public actual companion object {
+        public actual fun createOrNull(year: Int, month: Int, day: Int): LocalDate? =
+            try {
+                LocalDate(year, month, day)
+            } catch (e: IllegalArgumentException) {
+                null
+            }
+
+        public actual fun createOrNull(year: Int, month: Month, day: Int): LocalDate? =
+            try {
+                LocalDate(year, month, day)
+            } catch (e: IllegalArgumentException) {
+                null
+            }
+
         public actual fun parse(input: CharSequence, format: DateTimeFormat<LocalDate>): LocalDate =
             if (format === Formats.ISO) {
                 try {