Generate createOrNull implementations using AI

Prompts:
"""
In the last commit, `LocalDate.createOrNull` was introduced,
along with a usage sample, and with the existing tests modified
to also check `createOrNull`.
You should introduce `LocalTime.createOrNull` in the same way.
***
Now, similarly, introduce `LocalDateTime.createOrNull`
with tests and a usage sample.
***
Now also introduce `UtcOffset.createOrNull`
(with tests and a usage sample), except that since the constructor
for `UtcOffset` is internal, use the behavior from `fun UtcOffset`.
"""

Author: dkhalanskyjb

core/common/src/LocalDateTime.kt

@@ -114,6 +114,68 @@ import kotlin.jvm.JvmName
 public expect class LocalDateTime : Comparable<LocalDateTime> {
     public companion object {
 
+        /**
+         * Constructs a [LocalDateTime] instance from the given date and time components
+         * or returns `null` if a value is out of range.
+         *
+         * The components [month] and [day] are 1-based.
+         *
+         * The supported ranges of components:
+         * - [year] the range is platform-dependent, but at least is 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
+         * - [hour] `0..23`
+         * - [minute] `0..59`
+         * - [second] `0..59`
+         * - [nanosecond] `0..999_999_999`
+         *
+         * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.createOrNull
+         */
+        public fun createOrNull(
+            year: Int,
+            month: Int,
+            day: Int,
+            hour: Int,
+            minute: Int,
+            second: Int = 0,
+            nanosecond: Int = 0
+        ): LocalDateTime?
+
+        /**
+         * Constructs a [LocalDateTime] instance from the given date and time components
+         * or returns `null` if a value is out of range.
+         *
+         * The supported ranges of components:
+         * - [year] the range is platform-dependent, but 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
+         * - [hour] `0..23`
+         * - [minute] `0..59`
+         * - [second] `0..59`
+         * - [nanosecond] `0..999_999_999`
+         *
+         * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.createOrNullWithMonth
+         */
+        public fun createOrNull(
+            year: Int,
+            month: Month,
+            day: Int,
+            hour: Int,
+            minute: Int,
+            second: Int = 0,
+            nanosecond: Int = 0
+        ): LocalDateTime?
+
+        /**
+         * Constructs a [LocalDateTime] instance by combining the given [date] and [time] parts
+         * or returns `null` if either [date] or [time] is `null`.
+         *
+         * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.createOrNullFromDateAndTime
+         */
+        public fun createOrNull(date: LocalDate?, time: LocalTime?): LocalDateTime?
+
         /**
          * A shortcut for calling [DateTimeFormat.parse].
          *

core/common/src/LocalTime.kt

@@ -84,6 +84,20 @@ import kotlin.jvm.JvmName
 public expect class LocalTime : Comparable<LocalTime> {
     public companion object {
 
+        /**
+         * Constructs a [LocalTime] instance from the given time components
+         * or returns `null` if a value is out of range.
+         *
+         * The supported ranges of components:
+         * - [hour] `0..23`
+         * - [minute] `0..59`
+         * - [second] `0..59`
+         * - [nanosecond] `0..999_999_999`
+         *
+         * @sample kotlinx.datetime.test.samples.LocalTimeSamples.createOrNull
+         */
+        public fun createOrNull(hour: Int, minute: Int, second: Int = 0, nanosecond: Int = 0): LocalTime?
+
         /**
          * A shortcut for calling [DateTimeFormat.parse].
          *

core/common/src/UtcOffset.kt

@@ -77,6 +77,26 @@ public expect class UtcOffset {
          */
         public val ZERO: UtcOffset
 
+        /**
+         * Constructs a [UtcOffset] from hours, minutes, and seconds components
+         * or returns `null` if a value is out of range or invalid.
+         *
+         * All components must have the same sign.
+         * Otherwise, `null` will be returned.
+         *
+         * The bounds are checked: it is invalid to pass something other than `±[0; 59]` as the number of seconds or minutes;
+         * `null` will be returned if this rule is violated.
+         * For example, `UtcOffset.createOrNull(hours = 3, minutes = 61)` returns `null`.
+         *
+         * However, the non-null component of the highest order can exceed these bounds,
+         * for example, `UtcOffset.createOrNull(minutes = 241)` and `UtcOffset.createOrNull(seconds = -3600)` are both valid.
+         *
+         * @return the [UtcOffset] with the specified components, or `null` if the components are invalid
+         * or the resulting `UtcOffset` value is outside of range `±18:00`.
+         * @sample kotlinx.datetime.test.samples.UtcOffsetSamples.createOrNull
+         */
+        public fun createOrNull(hours: Int? = null, minutes: Int? = null, seconds: Int? = null): UtcOffset?
+
         /**
          * A shortcut for calling [DateTimeFormat.parse].
          *

core/common/test/LocalDateTimeTest.kt

@@ -131,6 +131,65 @@ class LocalDateTimeTest {
         assertFailsWith<IllegalArgumentException> { localTime(0, 0, 0, 1_000_000_000) }
     }
 
+    @Test
+    fun createOrNull() {
+        // Test createOrNull with month number
+        val validDateTime1 = LocalDateTime.createOrNull(2020, 1, 1, 12, 30, 45, 500_000_000)
+        assertNotNull(validDateTime1)
+        assertEquals(2020, validDateTime1!!.year)
+        assertEquals(1, validDateTime1.month.number)
+        assertEquals(1, validDateTime1.day)
+        assertEquals(12, validDateTime1.hour)
+        assertEquals(30, validDateTime1.minute)
+        assertEquals(45, validDateTime1.second)
+        assertEquals(500_000_000, validDateTime1.nanosecond)
+
+        // Test createOrNull with Month enum
+        val validDateTime2 = LocalDateTime.createOrNull(2020, Month.FEBRUARY, 29, 23, 59, 59, 999_999_999)
+        assertNotNull(validDateTime2)
+        assertEquals(2020, validDateTime2!!.year)
+        assertEquals(Month.FEBRUARY, validDateTime2.month)
+        assertEquals(29, validDateTime2.day)
+        assertEquals(23, validDateTime2.hour)
+        assertEquals(59, validDateTime2.minute)
+        assertEquals(59, validDateTime2.second)
+        assertEquals(999_999_999, validDateTime2.nanosecond)
+
+        // Test createOrNull with LocalDate and LocalTime
+        val date = LocalDate(2020, 1, 1)
+        val time = LocalTime(12, 30, 45, 500_000_000)
+        val validDateTime3 = LocalDateTime.createOrNull(date, time)
+        assertNotNull(validDateTime3)
+        assertEquals(date, validDateTime3!!.date)
+        assertEquals(time, validDateTime3.time)
+
+        // Test invalid date components
+        assertNull(LocalDateTime.createOrNull(2021, 2, 29, 12, 30)) // Invalid day (not a leap year)
+        assertNull(LocalDateTime.createOrNull(2020, 13, 1, 12, 30)) // Invalid month
+        assertNull(LocalDateTime.createOrNull(2020, 0, 1, 12, 30)) // Invalid month
+        assertNull(LocalDateTime.createOrNull(2020, 1, 32, 12, 30)) // Invalid day
+        assertNull(LocalDateTime.createOrNull(2020, 1, 0, 12, 30)) // Invalid day
+
+        // Test invalid time components
+        assertNull(LocalDateTime.createOrNull(2020, 1, 1, -1, 30)) // Invalid hour
+        assertNull(LocalDateTime.createOrNull(2020, 1, 1, 24, 30)) // Invalid hour
+        assertNull(LocalDateTime.createOrNull(2020, 1, 1, 12, -1)) // Invalid minute
+        assertNull(LocalDateTime.createOrNull(2020, 1, 1, 12, 60)) // Invalid minute
+        assertNull(LocalDateTime.createOrNull(2020, 1, 1, 12, 30, -1)) // Invalid second
+        assertNull(LocalDateTime.createOrNull(2020, 1, 1, 12, 30, 60)) // Invalid second
+        assertNull(LocalDateTime.createOrNull(2020, 1, 1, 12, 30, 45, -1)) // Invalid nanosecond
+        assertNull(LocalDateTime.createOrNull(2020, 1, 1, 12, 30, 45, 1_000_000_000)) // Invalid nanosecond
+
+        // Test with Month enum
+        assertNull(LocalDateTime.createOrNull(2021, Month.FEBRUARY, 29, 12, 30)) // Invalid day (not a leap year)
+        assertNull(LocalDateTime.createOrNull(2020, Month.FEBRUARY, 30, 12, 30)) // Invalid day for February
+
+        // Test with null LocalDate or LocalTime
+        assertNull(LocalDateTime.createOrNull(null, time))
+        assertNull(LocalDateTime.createOrNull(date, null))
+        assertNull(LocalDateTime.createOrNull(null, null))
+    }
+
 }
 
 fun checkComponents(value: LocalDateTime, year: Int, month: Int, day: Int, hour: Int, minute: Int, second: Int = 0, nanosecond: Int = 0, dayOfWeek: Int? = null, dayOfYear: Int? = null) {

core/common/test/LocalTimeTest.kt

@@ -87,6 +87,41 @@ class LocalTimeTest {
         assertFailsWith<IllegalArgumentException> { LocalTime(0, 0, 0, 1_000_000_000) }
     }
 
+    @Test
+    fun createOrNull() {
+        // Valid times should be created correctly
+        val validTime1 = LocalTime.createOrNull(12, 30, 45, 500_000_000)
+        assertNotNull(validTime1)
+        assertEquals(12, validTime1!!.hour)
+        assertEquals(30, validTime1.minute)
+        assertEquals(45, validTime1.second)
+        assertEquals(500_000_000, validTime1.nanosecond)
+
+        val validTime2 = LocalTime.createOrNull(0, 0)
+        assertNotNull(validTime2)
+        assertEquals(0, validTime2!!.hour)
+        assertEquals(0, validTime2.minute)
+        assertEquals(0, validTime2.second)
+        assertEquals(0, validTime2.nanosecond)
+
+        val validTime3 = LocalTime.createOrNull(23, 59, 59, 999_999_999)
+        assertNotNull(validTime3)
+        assertEquals(23, validTime3!!.hour)
+        assertEquals(59, validTime3.minute)
+        assertEquals(59, validTime3.second)
+        assertEquals(999_999_999, validTime3.nanosecond)
+
+        // Invalid times should return null
+        assertNull(LocalTime.createOrNull(-1, 0))
+        assertNull(LocalTime.createOrNull(24, 0))
+        assertNull(LocalTime.createOrNull(0, -1))
+        assertNull(LocalTime.createOrNull(0, 60))
+        assertNull(LocalTime.createOrNull(0, 0, -1))
+        assertNull(LocalTime.createOrNull(0, 0, 60))
+        assertNull(LocalTime.createOrNull(0, 0, 0, -1))
+        assertNull(LocalTime.createOrNull(0, 0, 0, 1_000_000_000))
+    }
+
     @Test
     fun fromNanosecondOfDay() {
         val data = mapOf(

core/common/test/UtcOffsetTest.kt

@@ -161,4 +161,44 @@ class UtcOffsetTest {
         assertIs<FixedOffsetTimeZone>(timeZone)
         assertEquals(offset, timeZone.offset)
     }
+
+    @Test
+    fun createOrNull() {
+        // Valid cases
+        for (totalSeconds in offsetSecondsRange) {
+            val hours = totalSeconds / (60 * 60)
+            val totalMinutes = totalSeconds / 60
+            val minutes = totalMinutes % 60
+            val seconds = totalSeconds % 60
+            val offset = UtcOffset.createOrNull(hours, minutes, seconds)
+            val offsetSeconds = UtcOffset.createOrNull(seconds = totalSeconds)
+            val offsetMinutes = UtcOffset.createOrNull(minutes = totalMinutes, seconds = seconds)
+            assertNotNull(offset)
+            assertNotNull(offsetSeconds)
+            assertNotNull(offsetMinutes)
+            assertEquals(totalSeconds, offset!!.totalSeconds)
+            assertEquals(offset, offsetMinutes)
+            assertEquals(offset, offsetSeconds)
+        }
+
+        // Invalid cases
+        assertNull(UtcOffset.createOrNull(hours = -19))
+        assertNull(UtcOffset.createOrNull(hours = +19))
+        assertNull(UtcOffset.createOrNull(hours = -18, minutes = -1))
+        assertNull(UtcOffset.createOrNull(hours = -18, seconds = -1))
+        assertNull(UtcOffset.createOrNull(hours = +18, seconds = +1))
+        assertNull(UtcOffset.createOrNull(hours = +18, seconds = +1))
+        assertNull(UtcOffset.createOrNull(seconds = offsetSecondsRange.first - 1))
+        assertNull(UtcOffset.createOrNull(seconds = offsetSecondsRange.last + 1))
+        assertNull(UtcOffset.createOrNull(hours = 0, minutes = 60))
+        assertNull(UtcOffset.createOrNull(hours = 0, seconds = -60))
+        assertNull(UtcOffset.createOrNull(minutes = 90, seconds = 90))
+        assertNull(UtcOffset.createOrNull(minutes = 0, seconds = 90))
+        assertNull(UtcOffset.createOrNull(hours = +1, minutes = -1))
+        assertNull(UtcOffset.createOrNull(hours = +1, seconds = -1))
+        assertNull(UtcOffset.createOrNull(hours = -1, minutes = +1))
+        assertNull(UtcOffset.createOrNull(hours = -1, seconds = +1))
+        assertNull(UtcOffset.createOrNull(minutes = +1, seconds = -1))
+        assertNull(UtcOffset.createOrNull(minutes = -1, seconds = +1))
+    }
 }

core/common/test/samples/LocalDateTimeSamples.kt

@@ -183,6 +183,45 @@ class LocalDateTimeSamples {
         check(LocalDate(2024, 2, 15).atTime(16, 48, 15, 120_000_000).toString() == "2024-02-15T16:48:15.120")
     }
 
+    @Test
+    fun createOrNull() {
+        // Constructing a LocalDateTime value using `createOrNull`
+        val dateTime = LocalDateTime.createOrNull(2024, 2, 15, 16, 48, 59, 999_999_999)
+        // For valid values, `createOrNull` is equivalent to the constructor
+        check(dateTime == LocalDateTime(2024, 2, 15, 16, 48, 59, 999_999_999))
+        // If a value can not be constructed, null is returned
+        check(LocalDateTime.createOrNull(2024, 2, 31, 16, 48) == null) // Invalid day
+        check(LocalDateTime.createOrNull(2024, 2, 15, 24, 48) == null) // Invalid hour
+        check(LocalDateTime.createOrNull(2024, 2, 15, 16, 60) == null) // Invalid minute
+        check(LocalDateTime.createOrNull(2024, 2, 15, 16, 48, 60) == null) // Invalid second
+        check(LocalDateTime.createOrNull(2024, 2, 15, 16, 48, 59, 1_000_000_000) == null) // Invalid nanosecond
+    }
+
+    @Test
+    fun createOrNullWithMonth() {
+        // Constructing a LocalDateTime value using `createOrNull` with Month enum
+        val dateTime = LocalDateTime.createOrNull(2024, Month.FEBRUARY, 15, 16, 48, 59, 999_999_999)
+        // For valid values, `createOrNull` is equivalent to the constructor
+        check(dateTime == LocalDateTime(2024, Month.FEBRUARY, 15, 16, 48, 59, 999_999_999))
+        // If a value can not be constructed, null is returned
+        check(LocalDateTime.createOrNull(2024, Month.FEBRUARY, 31, 16, 48) == null) // Invalid day
+        check(LocalDateTime.createOrNull(2024, Month.FEBRUARY, 15, 24, 48) == null) // Invalid hour
+    }
+
+    @Test
+    fun createOrNullFromDateAndTime() {
+        // Constructing a LocalDateTime value using `createOrNull` with LocalDate and LocalTime
+        val date = LocalDate(2024, 2, 15)
+        val time = LocalTime(16, 48)
+        val dateTime = LocalDateTime.createOrNull(date, time)
+        // For valid values, `createOrNull` is equivalent to the constructor
+        check(dateTime == LocalDateTime(date, time))
+        // If either date or time is null, null is returned
+        check(LocalDateTime.createOrNull(null, time) == null)
+        check(LocalDateTime.createOrNull(date, null) == null)
+        check(LocalDateTime.createOrNull(null, null) == null)
+    }
+
     @Test
     fun formatting() {
         // Formatting LocalDateTime values using predefined and custom formats

core/common/test/samples/LocalTimeSamples.kt

@@ -133,6 +133,19 @@ class LocalTimeSamples {
         check(timeWithoutSeconds.nanosecond == 0)
     }
 
+    @Test
+    fun createOrNull() {
+        // Constructing a LocalTime value using `createOrNull`
+        val time = LocalTime.createOrNull(8, 30, 15, 123_456_789)
+        // For valid values, `createOrNull` is equivalent to the constructor
+        check(time == LocalTime(8, 30, 15, 123_456_789))
+        // If a value can not be constructed, null is returned
+        check(LocalTime.createOrNull(24, 30) == null)
+        check(LocalTime.createOrNull(8, 60) == null)
+        check(LocalTime.createOrNull(8, 30, 60) == null)
+        check(LocalTime.createOrNull(8, 30, 15, 1_000_000_000) == null)
+    }
+
     @Test
     fun hour() {
         // Getting the number of whole hours shown on the clock

core/common/test/samples/UtcOffsetSamples.kt

@@ -108,6 +108,24 @@ class UtcOffsetSamples {
         }
     }
 
+    @Test
+    fun createOrNull() {
+        // Using the createOrNull function to create UtcOffset values
+        val validOffset = UtcOffset.createOrNull(hours = 3, minutes = 30)
+        check(validOffset != null)
+        check(validOffset!!.totalSeconds == 12600)
+
+        // For valid inputs, createOrNull returns a non-null value
+        check(UtcOffset.createOrNull(seconds = -3600) == UtcOffset(hours = -1))
+
+        // For invalid inputs, createOrNull returns null
+        check(UtcOffset.createOrNull(hours = 1, minutes = 60) == null)
+        // Since `hours` is positive, `minutes` must also be positive
+        check(UtcOffset.createOrNull(hours = 1, minutes = -30) == null)
+        // The total offset must be within the range ±18:00
+        check(UtcOffset.createOrNull(hours = 19) == null)
+    }
+
     class Formats {
         @Test
         fun isoBasic() {