Add documentation for public helper functions

kizitonwose · Jul 18, 2024 · d207d53 · d207d53
1 parent 2881ba6
commit d207d53
Show file tree

Hide file tree

Showing 17 changed files with 157 additions and 96 deletions.
diff --git a/compose-multiplatform/library/api/android/library.api b/compose-multiplatform/library/api/android/library.api
@@ -173,7 +173,6 @@ public final class com/kizitonwose/calendar/compose/weekcalendar/WeekCalendarSta
 }
 
 public final class com/kizitonwose/calendar/compose/weekcalendar/WeekCalendarState$Companion {
-	public final fun getSaver ()Landroidx/compose/runtime/saveable/Saver;
 }
 
 public final class com/kizitonwose/calendar/compose/weekcalendar/WeekCalendarStateKt {
@@ -222,18 +221,11 @@ public final class com/kizitonwose/calendar/core/DayPosition : java/lang/Enum {
 }
 
 public final class com/kizitonwose/calendar/core/ExtensionsKt {
-	public static final fun atDay (Lcom/kizitonwose/calendar/core/YearMonth;I)Lkotlinx/datetime/LocalDate;
-	public static final fun atEndOfMonth (Lcom/kizitonwose/calendar/core/YearMonth;)Lkotlinx/datetime/LocalDate;
-	public static final fun atStartOfMonth (Lcom/kizitonwose/calendar/core/YearMonth;)Lkotlinx/datetime/LocalDate;
 	public static final fun daysOfWeek (Ljava/time/DayOfWeek;)Ljava/util/List;
 	public static synthetic fun daysOfWeek$default (Ljava/time/DayOfWeek;ILjava/lang/Object;)Ljava/util/List;
-	public static final fun getNextMonth (Lcom/kizitonwose/calendar/core/YearMonth;)Lcom/kizitonwose/calendar/core/YearMonth;
-	public static final fun getPreviousMonth (Lcom/kizitonwose/calendar/core/YearMonth;)Lcom/kizitonwose/calendar/core/YearMonth;
 	public static final fun getYearMonth (Lkotlinx/datetime/LocalDate;)Lcom/kizitonwose/calendar/core/YearMonth;
-	public static final fun minusMonths (Lcom/kizitonwose/calendar/core/YearMonth;I)Lcom/kizitonwose/calendar/core/YearMonth;
-	public static final fun now (Lcom/kizitonwose/calendar/core/YearMonth$Companion;)Lcom/kizitonwose/calendar/core/YearMonth;
-	public static final fun now (Lkotlinx/datetime/LocalDate$Companion;)Lkotlinx/datetime/LocalDate;
-	public static final fun plusMonths (Lcom/kizitonwose/calendar/core/YearMonth;I)Lcom/kizitonwose/calendar/core/YearMonth;
+	public static final fun now (Lkotlinx/datetime/LocalDate$Companion;Lkotlinx/datetime/Clock;Lkotlinx/datetime/TimeZone;)Lkotlinx/datetime/LocalDate;
+	public static synthetic fun now$default (Lkotlinx/datetime/LocalDate$Companion;Lkotlinx/datetime/Clock;Lkotlinx/datetime/TimeZone;ILjava/lang/Object;)Lkotlinx/datetime/LocalDate;
 }
 
 public final class com/kizitonwose/calendar/core/Extensions_jvmKt {
@@ -302,6 +294,18 @@ public final class com/kizitonwose/calendar/core/YearMonth : java/io/Serializabl
 }
 
 public final class com/kizitonwose/calendar/core/YearMonth$Companion {
+	public final fun now (Lkotlinx/datetime/Clock;Lkotlinx/datetime/TimeZone;)Lcom/kizitonwose/calendar/core/YearMonth;
+	public static synthetic fun now$default (Lcom/kizitonwose/calendar/core/YearMonth$Companion;Lkotlinx/datetime/Clock;Lkotlinx/datetime/TimeZone;ILjava/lang/Object;)Lcom/kizitonwose/calendar/core/YearMonth;
+}
+
+public final class com/kizitonwose/calendar/core/YearMonthKt {
+	public static final fun atDay (Lcom/kizitonwose/calendar/core/YearMonth;I)Lkotlinx/datetime/LocalDate;
+	public static final fun atEndOfMonth (Lcom/kizitonwose/calendar/core/YearMonth;)Lkotlinx/datetime/LocalDate;
+	public static final fun atStartOfMonth (Lcom/kizitonwose/calendar/core/YearMonth;)Lkotlinx/datetime/LocalDate;
+	public static final fun lengthOfMonth (Lcom/kizitonwose/calendar/core/YearMonth;)I
+	public static final fun minus (Lcom/kizitonwose/calendar/core/YearMonth;ILkotlinx/datetime/DateTimeUnit$MonthBased;)Lcom/kizitonwose/calendar/core/YearMonth;
+	public static final fun monthsUntil (Lcom/kizitonwose/calendar/core/YearMonth;Lcom/kizitonwose/calendar/core/YearMonth;)I
+	public static final fun plus (Lcom/kizitonwose/calendar/core/YearMonth;ILkotlinx/datetime/DateTimeUnit$MonthBased;)Lcom/kizitonwose/calendar/core/YearMonth;
 }
 
 public final class com/kizitonwose/calendar/data/WeekData {

diff --git a/compose-multiplatform/library/api/desktop/library.api b/compose-multiplatform/library/api/desktop/library.api
@@ -173,7 +173,6 @@ public final class com/kizitonwose/calendar/compose/weekcalendar/WeekCalendarSta
 }
 
 public final class com/kizitonwose/calendar/compose/weekcalendar/WeekCalendarState$Companion {
-	public final fun getSaver ()Landroidx/compose/runtime/saveable/Saver;
 }
 
 public final class com/kizitonwose/calendar/compose/weekcalendar/WeekCalendarStateKt {
@@ -222,18 +221,11 @@ public final class com/kizitonwose/calendar/core/DayPosition : java/lang/Enum {
 }
 
 public final class com/kizitonwose/calendar/core/ExtensionsKt {
-	public static final fun atDay (Lcom/kizitonwose/calendar/core/YearMonth;I)Lkotlinx/datetime/LocalDate;
-	public static final fun atEndOfMonth (Lcom/kizitonwose/calendar/core/YearMonth;)Lkotlinx/datetime/LocalDate;
-	public static final fun atStartOfMonth (Lcom/kizitonwose/calendar/core/YearMonth;)Lkotlinx/datetime/LocalDate;
 	public static final fun daysOfWeek (Ljava/time/DayOfWeek;)Ljava/util/List;
 	public static synthetic fun daysOfWeek$default (Ljava/time/DayOfWeek;ILjava/lang/Object;)Ljava/util/List;
-	public static final fun getNextMonth (Lcom/kizitonwose/calendar/core/YearMonth;)Lcom/kizitonwose/calendar/core/YearMonth;
-	public static final fun getPreviousMonth (Lcom/kizitonwose/calendar/core/YearMonth;)Lcom/kizitonwose/calendar/core/YearMonth;
 	public static final fun getYearMonth (Lkotlinx/datetime/LocalDate;)Lcom/kizitonwose/calendar/core/YearMonth;
-	public static final fun minusMonths (Lcom/kizitonwose/calendar/core/YearMonth;I)Lcom/kizitonwose/calendar/core/YearMonth;
-	public static final fun now (Lcom/kizitonwose/calendar/core/YearMonth$Companion;)Lcom/kizitonwose/calendar/core/YearMonth;
-	public static final fun now (Lkotlinx/datetime/LocalDate$Companion;)Lkotlinx/datetime/LocalDate;
-	public static final fun plusMonths (Lcom/kizitonwose/calendar/core/YearMonth;I)Lcom/kizitonwose/calendar/core/YearMonth;
+	public static final fun now (Lkotlinx/datetime/LocalDate$Companion;Lkotlinx/datetime/Clock;Lkotlinx/datetime/TimeZone;)Lkotlinx/datetime/LocalDate;
+	public static synthetic fun now$default (Lkotlinx/datetime/LocalDate$Companion;Lkotlinx/datetime/Clock;Lkotlinx/datetime/TimeZone;ILjava/lang/Object;)Lkotlinx/datetime/LocalDate;
 }
 
 public final class com/kizitonwose/calendar/core/Extensions_jvmKt {
@@ -302,6 +294,18 @@ public final class com/kizitonwose/calendar/core/YearMonth : java/io/Serializabl
 }
 
 public final class com/kizitonwose/calendar/core/YearMonth$Companion {
+	public final fun now (Lkotlinx/datetime/Clock;Lkotlinx/datetime/TimeZone;)Lcom/kizitonwose/calendar/core/YearMonth;
+	public static synthetic fun now$default (Lcom/kizitonwose/calendar/core/YearMonth$Companion;Lkotlinx/datetime/Clock;Lkotlinx/datetime/TimeZone;ILjava/lang/Object;)Lcom/kizitonwose/calendar/core/YearMonth;
+}
+
+public final class com/kizitonwose/calendar/core/YearMonthKt {
+	public static final fun atDay (Lcom/kizitonwose/calendar/core/YearMonth;I)Lkotlinx/datetime/LocalDate;
+	public static final fun atEndOfMonth (Lcom/kizitonwose/calendar/core/YearMonth;)Lkotlinx/datetime/LocalDate;
+	public static final fun atStartOfMonth (Lcom/kizitonwose/calendar/core/YearMonth;)Lkotlinx/datetime/LocalDate;
+	public static final fun lengthOfMonth (Lcom/kizitonwose/calendar/core/YearMonth;)I
+	public static final fun minus (Lcom/kizitonwose/calendar/core/YearMonth;ILkotlinx/datetime/DateTimeUnit$MonthBased;)Lcom/kizitonwose/calendar/core/YearMonth;
+	public static final fun monthsUntil (Lcom/kizitonwose/calendar/core/YearMonth;Lcom/kizitonwose/calendar/core/YearMonth;)I
+	public static final fun plus (Lcom/kizitonwose/calendar/core/YearMonth;ILkotlinx/datetime/DateTimeUnit$MonthBased;)Lcom/kizitonwose/calendar/core/YearMonth;
 }
 
 public final class com/kizitonwose/calendar/data/WeekData {

diff --git a/.../src/commonMain/kotlin/com/kizitonwose/calendar/compose/weekcalendar/WeekCalendarState.kt b/.../src/commonMain/kotlin/com/kizitonwose/calendar/compose/weekcalendar/WeekCalendarState.kt
@@ -265,7 +265,7 @@ public class WeekCalendarState internal constructor(
     }
 
     public companion object {
-        public val Saver: Saver<WeekCalendarState, Any> = listSaver(
+        internal val Saver: Saver<WeekCalendarState, Any> = listSaver(
             save = {
                 listOf(
                     it.startDate.toJvmSerializableLocalDate(),

diff --git a/...e-multiplatform/library/src/commonMain/kotlin/com/kizitonwose/calendar/core/Extensions.kt b/...e-multiplatform/library/src/commonMain/kotlin/com/kizitonwose/calendar/core/Extensions.kt
@@ -6,12 +6,10 @@ import kotlinx.datetime.DateTimeUnit
 import kotlinx.datetime.DayOfWeek
 import kotlinx.datetime.LocalDate
 import kotlinx.datetime.TimeZone
-import kotlinx.datetime.daysUntil
 import kotlinx.datetime.isoDayNumber
 import kotlinx.datetime.minus
-import kotlinx.datetime.monthsUntil
 import kotlinx.datetime.plus
-import kotlinx.datetime.toLocalDateTime
+import kotlinx.datetime.todayIn
 import kotlinx.datetime.until
 
 /**
@@ -32,33 +30,26 @@ public fun daysOfWeek(firstDayOfWeek: DayOfWeek = firstDayOfWeekFromLocale()): L
  */
 public expect fun firstDayOfWeekFromLocale(locale: Locale = Locale.current): DayOfWeek
 
-public fun YearMonth.atStartOfMonth(): LocalDate = atDay(1)
-
-public fun YearMonth.atEndOfMonth(): LocalDate = atDay(lengthOfMonth())
-
-public fun YearMonth.atDay(day: Int): LocalDate = LocalDate(year, month, day)
-
-public val YearMonth.nextMonth: YearMonth
-    get() = this.plusMonths(1)
-
-public val YearMonth.previousMonth: YearMonth
-    get() = this.minusMonths(1)
-
-public fun LocalDate.Companion.now(): LocalDate = Clock.System.now()
-    .toLocalDateTime(TimeZone.currentSystemDefault())
-    .date
-
-public fun YearMonth.Companion.now(): YearMonth = LocalDate.now().yearMonth
-
-public fun YearMonth.plusMonths(value: Int): YearMonth =
-    atStartOfMonth().plusMonths(value).yearMonth
-
-public fun YearMonth.minusMonths(value: Int): YearMonth =
-    atStartOfMonth().minusMonths(value).yearMonth
+/**
+ * Obtains the current [LocalDate] from the specified [clock] and [timeZone].
+ *
+ * Using this method allows the use of an alternate clock or timezone for testing.
+ */
+public fun LocalDate.Companion.now(
+    clock: Clock = Clock.System,
+    timeZone: TimeZone = TimeZone.currentSystemDefault(),
+): LocalDate = clock.todayIn(timeZone)
 
+/**
+ * Returns the [YearMonth] value for this date.
+ */
 public val LocalDate.yearMonth: YearMonth
     get() = YearMonth(year, month)
 
+internal fun YearMonth.plusMonths(value: Int): YearMonth = plus(value, DateTimeUnit.MONTH)
+
+internal fun YearMonth.minusMonths(value: Int): YearMonth = minus(value, DateTimeUnit.MONTH)
+
 internal fun LocalDate.plusDays(value: Int): LocalDate = plus(value, DateTimeUnit.DAY)
 
 internal fun LocalDate.minusDays(value: Int): LocalDate = minus(value, DateTimeUnit.DAY)
@@ -71,15 +62,6 @@ internal fun LocalDate.plusMonths(value: Int): LocalDate = plus(value, DateTimeU
 
 internal fun LocalDate.minusMonths(value: Int): LocalDate = minus(value, DateTimeUnit.MONTH)
 
-internal fun YearMonth.lengthOfMonth(): Int {
-    val thisMonthStart = atStartOfMonth()
-    val nextMonthStart = thisMonthStart.plusMonths(1)
-    return thisMonthStart.daysUntil(nextMonthStart)
-}
-
-internal fun YearMonth.monthsUntil(other: YearMonth): Int =
-    atStartOfMonth().monthsUntil(other.atStartOfMonth())
-
 internal fun LocalDate.weeksUntil(other: LocalDate): Int =
     until(other, DateTimeUnit.WEEK)
 

diff --git a/...se-multiplatform/library/src/commonMain/kotlin/com/kizitonwose/calendar/core/YearMonth.kt b/...se-multiplatform/library/src/commonMain/kotlin/com/kizitonwose/calendar/core/YearMonth.kt
@@ -1,8 +1,17 @@
 package com.kizitonwose.calendar.core
 
 import androidx.compose.runtime.Immutable
+import kotlinx.datetime.Clock
+import kotlinx.datetime.DateTimeArithmeticException
+import kotlinx.datetime.DateTimeUnit
+import kotlinx.datetime.LocalDate
 import kotlinx.datetime.Month
+import kotlinx.datetime.TimeZone
+import kotlinx.datetime.daysUntil
+import kotlinx.datetime.minus
+import kotlinx.datetime.monthsUntil
 import kotlinx.datetime.number
+import kotlinx.datetime.plus
 
 @Immutable
 public data class YearMonth(val year: Int, val month: Month) : Comparable<YearMonth>, JvmSerializable {
@@ -13,7 +22,7 @@ public data class YearMonth(val year: Int, val month: Month) : Comparable<YearMo
         try {
             atStartOfMonth()
         } catch (e: IllegalArgumentException) {
-            throw IllegalArgumentException("Year value $year is out of range", e)
+            throw IllegalArgumentException("YearMonth value ${month.number}-$year is out of range", e)
         }
     }
 
@@ -28,5 +37,84 @@ public data class YearMonth(val year: Int, val month: Month) : Comparable<YearMo
         return cmp
     }
 
-    public companion object
+    public companion object {
+        /**
+         * Obtains the current [YearMonth] from the specified [clock] and [timeZone].
+         *
+         * Using this method allows the use of an alternate clock or timezone for testing.
+         */
+        public fun now(
+            clock: Clock = Clock.System,
+            timeZone: TimeZone = TimeZone.currentSystemDefault(),
+        ): YearMonth = LocalDate.now(clock, timeZone).yearMonth
+    }
 }
+
+/**
+ * Returns the first [LocalDate] in this year-month.
+ *
+ * @see YearMonth.atDay
+ */
+public fun YearMonth.atStartOfMonth(): LocalDate = atDay(1)
+
+/**
+ * Returns the last [LocalDate] in this year-month.
+ *
+ * @see YearMonth.atDay
+ */
+public fun YearMonth.atEndOfMonth(): LocalDate = atDay(lengthOfMonth())
+
+/**
+ * Returns the [LocalDate] at the specified [day] in this year-month.
+ */
+public fun YearMonth.atDay(day: Int): LocalDate = LocalDate(year, month, day)
+
+/**
+ * Returns the number of days in this month, taking account of the year.
+ *
+ * For example, a date in February would return 29 in a leap year and 28 otherwise.
+ */
+public fun YearMonth.lengthOfMonth(): Int {
+    val thisMonthStart = atStartOfMonth()
+    val nextMonthStart = thisMonthStart.plusMonths(1)
+    return thisMonthStart.daysUntil(nextMonthStart)
+}
+
+/**
+ * Returns the number of whole months between two year-month values.
+ *
+ * The value is rounded toward zero.
+ *
+ * If the result does not fit in [Int], returns [Int.MAX_VALUE] for a
+ * positive result or [Int.MIN_VALUE] for a negative result.
+ *
+ * @see LocalDate.monthsUntil
+ */
+public fun YearMonth.monthsUntil(other: YearMonth): Int =
+    atStartOfMonth().monthsUntil(other.atStartOfMonth())
+
+/**
+ * Returns a [YearMonth] that results from adding the [value] number of the
+ * specified [unit] to this year-month.
+ *
+ * If the [value] is positive, the returned year-month is later than this year-month.
+ * If the [value] is negative, the returned year-month is earlier than this year-month.
+ *
+ * @throws DateTimeArithmeticException if the result exceeds the boundaries
+ * of [YearMonth] which is essentially the [LocalDate] boundaries.
+ */
+public fun YearMonth.plus(value: Int, unit: DateTimeUnit.MonthBased): YearMonth =
+    atStartOfMonth().plus(value, unit).yearMonth
+
+/**
+ * Returns a [YearMonth] that results from subtracting the [value] number of the
+ * specified [unit] from this year-month.
+ *
+ * If the [value] is positive, the returned year-month is earlier than this year-month.
+ * If the [value] is negative, the returned year-month is later than this year-month.
+ *
+ * @throws DateTimeArithmeticException if the result exceeds the boundaries
+ * of [YearMonth] which is essentially the [LocalDate] boundaries.
+ */
+public fun YearMonth.minus(value: Int, unit: DateTimeUnit.MonthBased): YearMonth =
+    atStartOfMonth().minus(value, unit).yearMonth
diff --git a/...se-multiplatform/library/src/commonMain/kotlin/com/kizitonwose/calendar/data/MonthData.kt b/...se-multiplatform/library/src/commonMain/kotlin/com/kizitonwose/calendar/data/MonthData.kt
@@ -9,11 +9,10 @@ import com.kizitonwose.calendar.core.atStartOfMonth
 import com.kizitonwose.calendar.core.daysUntil
 import com.kizitonwose.calendar.core.lengthOfMonth
 import com.kizitonwose.calendar.core.minusDays
+import com.kizitonwose.calendar.core.minusMonths
 import com.kizitonwose.calendar.core.monthsUntil
-import com.kizitonwose.calendar.core.nextMonth
 import com.kizitonwose.calendar.core.plusDays
 import com.kizitonwose.calendar.core.plusMonths
-import com.kizitonwose.calendar.core.previousMonth
 import com.kizitonwose.calendar.core.yearMonth
 import kotlinx.datetime.DayOfWeek
 
@@ -28,9 +27,9 @@ internal data class MonthData internal constructor(
 
     private val rows = (0 until totalDays).chunked(7)
 
-    private val previousMonth = month.previousMonth
+    private val previousMonth = month.minusMonths(1)
 
-    private val nextMonth = month.nextMonth
+    private val nextMonth = month.plusMonths(1)
 
     val calendarMonth = CalendarMonth(month, rows.map { week -> week.map { dayOffset -> getDay(dayOffset) } })
 

diff --git a/compose-multiplatform/sample/src/commonMain/kotlin/ContinuousSelectionHelper.kt b/compose-multiplatform/sample/src/commonMain/kotlin/ContinuousSelectionHelper.kt
@@ -1,7 +1,5 @@
 import com.kizitonwose.calendar.core.atEndOfMonth
 import com.kizitonwose.calendar.core.atStartOfMonth
-import com.kizitonwose.calendar.core.nextMonth
-import com.kizitonwose.calendar.core.previousMonth
 import com.kizitonwose.calendar.core.yearMonth
 import kotlinx.datetime.LocalDate
 import kotlinx.datetime.daysUntil
@@ -48,7 +46,7 @@ object ContinuousSelectionHelper {
     ): Boolean {
         if (startDate.yearMonth == endDate.yearMonth) return false
         if (inDate.yearMonth == startDate.yearMonth) return true
-        val firstDateInThisMonth = inDate.yearMonth.nextMonth.atStartOfMonth()
+        val firstDateInThisMonth = inDate.yearMonth.next.atStartOfMonth()
         return firstDateInThisMonth in startDate..endDate && startDate != firstDateInThisMonth
     }
 
@@ -59,7 +57,7 @@ object ContinuousSelectionHelper {
     ): Boolean {
         if (startDate.yearMonth == endDate.yearMonth) return false
         if (outDate.yearMonth == endDate.yearMonth) return true
-        val lastDateInThisMonth = outDate.yearMonth.previousMonth.atEndOfMonth()
+        val lastDateInThisMonth = outDate.yearMonth.previous.atEndOfMonth()
         return lastDateInThisMonth in startDate..endDate && endDate != lastDateInThisMonth
     }
 }
diff --git a/compose-multiplatform/sample/src/commonMain/kotlin/Example1Page.kt b/compose-multiplatform/sample/src/commonMain/kotlin/Example1Page.kt
@@ -27,11 +27,6 @@ import com.kizitonwose.calendar.core.CalendarDay
 import com.kizitonwose.calendar.core.DayPosition
 import com.kizitonwose.calendar.core.YearMonth
 import com.kizitonwose.calendar.core.daysOfWeek
-import com.kizitonwose.calendar.core.minusMonths
-import com.kizitonwose.calendar.core.nextMonth
-import com.kizitonwose.calendar.core.now
-import com.kizitonwose.calendar.core.plusMonths
-import com.kizitonwose.calendar.core.previousMonth
 import kotlinx.coroutines.launch
 import kotlinx.datetime.DayOfWeek
 import org.jetbrains.compose.ui.tooling.preview.Preview
@@ -61,12 +56,12 @@ fun Example1Page(adjacentMonths: Int = 500) {
             currentMonth = visibleMonth.yearMonth,
             goToPrevious = {
                 coroutineScope.launch {
-                    state.animateScrollToMonth(state.firstVisibleMonth.yearMonth.previousMonth)
+                    state.animateScrollToMonth(state.firstVisibleMonth.yearMonth.previous)
                 }
             },
             goToNext = {
                 coroutineScope.launch {
-                    state.animateScrollToMonth(state.firstVisibleMonth.yearMonth.nextMonth)
+                    state.animateScrollToMonth(state.firstVisibleMonth.yearMonth.next)
                 }
             },
         )

diff --git a/compose-multiplatform/sample/src/commonMain/kotlin/Example2Page.kt b/compose-multiplatform/sample/src/commonMain/kotlin/Example2Page.kt
@@ -46,7 +46,6 @@ import com.kizitonwose.calendar.core.DayPosition
 import com.kizitonwose.calendar.core.YearMonth
 import com.kizitonwose.calendar.core.daysOfWeek
 import com.kizitonwose.calendar.core.now
-import com.kizitonwose.calendar.core.plusMonths
 import kotlinx.datetime.DayOfWeek
 import kotlinx.datetime.LocalDate
 import org.jetbrains.compose.ui.tooling.preview.Preview