Added initial user-defined integrals project.

Author: ianbrandt

settings.gradle.kts

@@ -56,3 +56,4 @@ include("subprojects:sorting-in-kotlin")
 include("subprojects:tdd-in-kotlin")
 include("subprojects:testing-with-mokkery")
 include("subprojects:typed-errors-in-kotlin")
+include("subprojects:user-defined-integrals-in-kotlin")

subprojects/user-defined-integrals-in-kotlin/build.gradle.kts

@@ -0,0 +1,16 @@
+plugins {
+	id("org.sdkotlin.buildlogic.kotlin-project")
+	id("org.sdkotlin.buildlogic.mockk-project")
+	id("org.sdkotlin.buildlogic.test.unit-test-suite")
+}
+
+dependencies {
+
+	testImplementation(platform("org.sdkotlin.platforms:test-platform"))
+
+	testImplementation(libs.equalsverifier)
+
+	testRuntimeOnly(libs.mockito) {
+		because("Used by EqualsVerifier for prefab value generation.")
+	}
+}

subprojects/user-defined-integrals-in-kotlin/src/main/kotlin/org/sdkotlin/integral/Integral.kt

@@ -0,0 +1,14 @@
+package org.sdkotlin.integral
+
+interface Integral<I> : Comparable<I> where I : Comparable<I> {
+
+	val minValue: I
+	val maxValue: I
+	val zero: I
+	val one: I
+
+	operator fun plus(other: I): I
+	operator fun minus(other: I): I
+	operator fun unaryMinus(): I
+	operator fun rem(other: I): I
+}

subprojects/user-defined-integrals-in-kotlin/src/main/kotlin/org/sdkotlin/integral/IntegralProgression.kt

@@ -0,0 +1,78 @@
+package org.sdkotlin.integral
+
+class IntegralProgression<I : Integral<I>> internal constructor(
+	start: I,
+	endInclusive: I,
+	override val step: I,
+) : Progression<I> {
+
+	init {
+		require(step != step.zero) { "Step must be non-zero." }
+		require(step != step.minValue) {
+			"Step must be greater than the type's minimum value to avoid overflow on negation."
+		}
+	}
+
+	override val first: I = start
+
+	override val last: I = getProgressionLastElement(start, endInclusive, step)
+
+	override fun iterator(): Iterator<I> =
+		IntegralProgressionIterator(first, last, step)
+
+	override fun isEmpty(): Boolean =
+		if (step > step.zero) first > last else first < last
+
+	override fun equals(other: Any?): Boolean =
+		other is IntegralProgression<*> && (isEmpty() && other.isEmpty() ||
+			first == other.first && last == other.last && step == other.step)
+
+	override fun hashCode(): Int =
+		if (isEmpty()) {
+			-1
+		} else {
+			(31 * (31 * first.hashCode() + last.hashCode()) + step.hashCode())
+		}
+
+	override fun toString(): String =
+		if (step > step.zero) {
+			"$first..$last step $step"
+		} else {
+			"$first downTo $last step ${-step}"
+		}
+
+	companion object {
+
+		fun <I : Integral<I>> fromClosedRange(
+			rangeStart: I,
+			rangeEnd: I,
+			step: I,
+		): IntegralProgression<I> =
+			IntegralProgression(rangeStart, rangeEnd, step)
+
+		private fun <I : Integral<I>> getProgressionLastElement(
+			start: I,
+			end: I,
+			step: I,
+		): I =
+			when {
+				step > step.zero -> if (start >= end) {
+					end
+				} else {
+					end - differenceModulo(end, start, step)
+				}
+				step < step.zero -> if (start <= end) {
+					end
+				} else {
+					end + differenceModulo(start, end, -step)
+				}
+				else -> throw IllegalArgumentException("Step is zero.")
+			}
+
+		private fun <I : Integral<I>> differenceModulo(a: I, b: I, c: I): I {
+			val ac = a % c
+			val bc = b % c
+			return if (ac >= bc) ac - bc else ac - bc + c
+		}
+	}
+}

subprojects/user-defined-integrals-in-kotlin/src/main/kotlin/org/sdkotlin/integral/IntegralProgressionIterator.kt

@@ -0,0 +1,30 @@
+package org.sdkotlin.integral
+
+internal class IntegralProgressionIterator<I : Integral<I>>(
+	first: I,
+	private val last: I,
+	private val step: I,
+) : Iterator<I> {
+
+	private var hasNext: Boolean =
+		if (step > step.zero) {
+			first <= last
+		} else {
+			first >= last
+		}
+
+	private var next = if (hasNext) first else last
+
+	override fun hasNext(): Boolean = hasNext
+
+	override fun next(): I {
+		val value = next
+		if (value == last) {
+			if (!hasNext) throw NoSuchElementException()
+			hasNext = false
+		} else {
+			next += step
+		}
+		return value
+	}
+}

subprojects/user-defined-integrals-in-kotlin/src/main/kotlin/org/sdkotlin/integral/IntegralRange.kt

@@ -0,0 +1,37 @@
+package org.sdkotlin.integral
+
+class IntegralRange<I : Integral<I>>(
+	start: I,
+	endInclusive: I,
+) : ClosedRange<I>, OpenEndRange<I>,
+	Progression<I> by IntegralProgression(
+		start,
+		endInclusive,
+		step = start.one
+	) {
+
+	override val start: I = first
+
+	override val endInclusive: I = last
+
+	override val endExclusive: I by lazy {
+		check(endInclusive == start.maxValue) {
+			"Cannot return the exclusive upper bound of a range that includes MAX_VALUE."
+		}
+		endInclusive + endInclusive.one
+	}
+
+	override fun contains(value: I): Boolean =
+		start <= value && value <= endInclusive
+
+	override fun isEmpty(): Boolean = start > endInclusive
+
+	override fun equals(other: Any?): Boolean =
+		other is IntegralRange<*> && (isEmpty() && other.isEmpty() ||
+			start == other.start && endInclusive == other.endInclusive)
+
+	override fun hashCode(): Int =
+		if (isEmpty()) -1 else (31 * start.hashCode() + endInclusive.hashCode())
+
+	override fun toString(): String = "$start..$endInclusive"
+}

subprojects/user-defined-integrals-in-kotlin/src/main/kotlin/org/sdkotlin/integral/Progression.kt

@@ -0,0 +1,9 @@
+package org.sdkotlin.integral
+
+interface Progression<out I> : Iterable<I> {
+	val first: I
+	val last: I
+	val step: I
+
+	fun isEmpty(): Boolean
+}

subprojects/user-defined-integrals-in-kotlin/src/test/kotlin/org/sdkotlin/integral/IntegralProgressionTest.kt

@@ -0,0 +1,20 @@
+package org.sdkotlin.integral
+
+import io.mockk.mockk
+import nl.jqno.equalsverifier.EqualsVerifier
+import org.junit.jupiter.api.Test
+
+class IntegralProgressionTest {
+
+	@Test
+	fun `test equals, hashCode, and toString`() {
+		EqualsVerifier.forClass(IntegralProgression::class.java)
+			// Required per https://github.com/jqno/equalsverifier/issues/1082.
+			.withPrefabValues(
+				Integral::class.java,
+				mockk(relaxed = true),
+				mockk(relaxed = true),
+			)
+			.verify()
+	}
+}

subprojects/user-defined-integrals-in-kotlin/src/test/kotlin/org/sdkotlin/integral/IntegralRangeTest.kt

@@ -0,0 +1,36 @@
+package org.sdkotlin.integral
+
+import io.mockk.mockk
+import nl.jqno.equalsverifier.EqualsVerifier
+import org.junit.jupiter.api.Test
+
+class IntegralRangeTest {
+
+	@Test
+	fun `test equals, hashCode, and toString`() {
+
+		EqualsVerifier.forClass(IntegralRange::class.java)
+			.withIgnoredFields("endExclusive\$delegate")
+			// Required per https://github.com/jqno/equalsverifier/issues/1082.
+			.withPrefabValues(
+				Integral::class.java,
+				mockk(relaxed = true),
+				mockk(relaxed = true),
+			)
+			.verify()
+	}
+
+	@Test
+	fun `test equals, hashCode, and toString with examples`() {
+
+		val zero = SignedIntegral(0)
+		val one = SignedIntegral(1)
+		val two = SignedIntegral(2)
+		val red: ClosedRange<SignedIntegral> = zero..one
+		val blue: ClosedRange<SignedIntegral> = one..two
+
+		EqualsVerifier.forExamples(red, blue)
+			.withIgnoredFields("endExclusive\$delegate")
+			.verify()
+	}
+}

subprojects/user-defined-integrals-in-kotlin/src/test/kotlin/org/sdkotlin/integral/SignedIntegral.kt

@@ -0,0 +1,49 @@
+package org.sdkotlin.integral
+
+@JvmInline
+value class SignedIntegral(private val i: Int) : Integral<SignedIntegral> {
+
+	companion object {
+
+		val MIN_VALUE: SignedIntegral = SignedIntegral(Int.MIN_VALUE)
+
+		val MAX_VALUE: SignedIntegral = SignedIntegral(Int.MAX_VALUE)
+
+		val ZERO: SignedIntegral = SignedIntegral(0)
+
+		val ONE: SignedIntegral = SignedIntegral(1)
+	}
+
+	override val minValue: SignedIntegral
+		get() = MIN_VALUE
+
+	override val maxValue: SignedIntegral
+		get() = MAX_VALUE
+
+	override val zero: SignedIntegral
+		get() = ZERO
+
+	override val one: SignedIntegral
+		get() = ONE
+
+	override fun plus(other: SignedIntegral): SignedIntegral =
+		SignedIntegral(i + other.i)
+
+	override fun minus(other: SignedIntegral): SignedIntegral =
+		SignedIntegral(i - other.i)
+
+	override fun unaryMinus(): SignedIntegral =
+		SignedIntegral(-i)
+
+	override fun rem(other: SignedIntegral): SignedIntegral =
+		SignedIntegral(i % other.i)
+
+	override fun compareTo(other: SignedIntegral): Int =
+		i.compareTo(other.i)
+
+	operator fun rangeTo(other: SignedIntegral): ClosedRange<SignedIntegral> =
+		IntegralRange(this, other)
+
+	operator fun rangeUntil(other: SignedIntegral): OpenEndRange<SignedIntegral> =
+		IntegralRange(this, other - ONE)
+}