Repository: kevincianfarini/cardiologist (kotlin)

Issue:
Rename `intervalPulse` to `fixedPeriodPulse`
And clarify in the documentation that it's a fixed period interval. See https://github.com/Kotlin/kotlinx.coroutines/issues/3680#issuecomment-1468055283 for the rationale in this naming.

Pull request:
Closes #67.

Patch:
diff --git a/src/commonMain/kotlin/io/github/kevincianfarini/cardiologist/schedule.kt b/src/commonMain/kotlin/io/github/kevincianfarini/cardiologist/schedule.kt
index 2f6888e..ddd4997 100644
--- a/src/commonMain/kotlin/io/github/kevincianfarini/cardiologist/schedule.kt
+++ b/src/commonMain/kotlin/io/github/kevincianfarini/cardiologist/schedule.kt
@@ -14,26 +14,32 @@ import kotlinx.datetime.toInstant
 import kotlinx.datetime.toLocalDateTime
 
 /**
- * Return a [Pulse] which beats every [interval]. The returned [Pulse] will delay prior to its first
- * [Pulse.beat].
+ * Return a [Pulse] which beats every [period].
+ *
+ * The period cadence which this [Pulse] beats is defined as the time between the start of one [beat][Pulse.beat] and the
+ * scheduled start of the subsequent [beat][Pulse.beat]. The returned [Pulse] will delay for [period] prior to its first
+ * [beat][Pulse.beat].
  */
-public fun Clock.intervalPulse(interval: Duration): Pulse {
+public fun Clock.fixedPeriodPulse(period: Duration): Pulse {
     val flow = flow {
-        var nextPulse: Instant = now() + interval
+        var nextPulse: Instant = now() + period
         while (true) {
             delayUntil(nextPulse)
             emit(Pair(nextPulse, now()))
-            nextPulse += interval
+            nextPulse += period
         }
     }
     return Pulse(flow)
 }
 
 /**
- * Return a [Pulse] which beats every [period] in [timeZone]. The returned [Pulse] will delay prior to its first
- * [Pulse.beat].
+ * Return a [Pulse] which beats every [period] in [timeZone].
+ *
+ * The period cadence which this [Pulse] beats is defined as the time between the start of one [beat][Pulse.beat] and the
+ * scheduled start of the subsequent [beat][Pulse.beat]. The returned [Pulse] will delay for [period] prior to its first
+ * [beat][Pulse.beat].
  */
-public fun Clock.intervalPulse(period: DateTimePeriod, timeZone: TimeZone): Pulse {
+public fun Clock.fixedPeriodPulse(period: DateTimePeriod, timeZone: TimeZone): Pulse {
     val flow = flow {
         var nextPulse: Instant = now().plus(period, timeZone)
         while (true) {


Test patch:
diff --git a/src/commonTest/kotlin/io/github/kevincianfarini/cardiologist/PulseTests.kt b/src/commonTest/kotlin/io/github/kevincianfarini/cardiologist/PulseTests.kt
index 25ee29f..db122d3 100644
--- a/src/commonTest/kotlin/io/github/kevincianfarini/cardiologist/PulseTests.kt
+++ b/src/commonTest/kotlin/io/github/kevincianfarini/cardiologist/PulseTests.kt
@@ -16,13 +16,13 @@ class PulseTests {
         assertEquals(
             expected = 5.seconds,
             actual = testTimeSource.measureTime {
-                testClock.intervalPulse(5.seconds).take(1).beat { _, _ -> }
+                testClock.fixedPeriodPulse(5.seconds).take(1).beat { _, _ -> }
             }
         )
     }
 
     @Test fun intervalPulse_DateTimePeriod_emits_subsequent_instants_after_delaying() = runTest {
-        val pulse = testClock.intervalPulse(DateTimePeriod(seconds = 5), TimeZone.UTC).take(1)
+        val pulse = testClock.fixedPeriodPulse(DateTimePeriod(seconds = 5), TimeZone.UTC).take(1)
         assertEquals(
             expected = 5.seconds,
             actual = testTimeSource.measureTime { pulse.beat { _, _ -> } }
@@ -48,7 +48,7 @@ class PulseTests {
             Instant.fromEpochSeconds(120), // After delayUntil resumes.
             Instant.fromEpochSeconds(120), // Second emissions in intervalPulse.
         ).asClock()
-        val pulse = clock.intervalPulse(60.seconds)
+        val pulse = clock.fixedPeriodPulse(60.seconds)
         pulse.take(2).beat { scheduled, occurred ->
             assertEquals(expected = scheduledInstants[index], scheduled)
             assertEquals(expected = occurredInstants[index++], occurred)
@@ -76,7 +76,7 @@ class PulseTests {
             Instant.fromEpochSeconds(120), // After delayUntil resumes.
             Instant.fromEpochSeconds(120), // Second emissions in intervalPulse.
         ).asClock()
-        val pulse = clock.intervalPulse(60.seconds)
+        val pulse = clock.fixedPeriodPulse(60.seconds)
         pulse.take(2).beat { scheduled, occurred ->
             assertEquals(expected = scheduledInstants[index], scheduled)
             assertEquals(expected = occurredInstants[index++], occurred)
@@ -102,7 +102,7 @@ class PulseTests {
             Instant.fromEpochSeconds(120), // After delayUntil resumes.
             Instant.fromEpochSeconds(120), // Second emissions in intervalPulse.
         ).asClock()
-        val pulse = clock.intervalPulse(DateTimePeriod(minutes = 1), timeZone = TimeZone.UTC)
+        val pulse = clock.fixedPeriodPulse(DateTimePeriod(minutes = 1), timeZone = TimeZone.UTC)
         pulse.take(2).beat { scheduled, occurred ->
             assertEquals(expected = scheduledInstants[index], scheduled)
             assertEquals(expected = occurredInstants[index++], occurred)
@@ -130,7 +130,7 @@ class PulseTests {
             Instant.fromEpochSeconds(120), // After delayUntil resumes.
             Instant.fromEpochSeconds(120), // Second emissions in intervalPulse.
         ).asClock()
-        val pulse = clock.intervalPulse(DateTimePeriod(minutes = 1), timeZone = TimeZone.UTC)
+        val pulse = clock.fixedPeriodPulse(DateTimePeriod(minutes = 1), timeZone = TimeZone.UTC)
         pulse.take(2).beat { scheduled, occurred ->
             assertEquals(expected = scheduledInstants[index], scheduled)
             assertEquals(expected = occurredInstants[index++], occurred)