Merge pull request #11 from Whathecode/develop

Release 1.0.0-alpha.2

Author: Whathecode

README.md

@@ -10,12 +10,9 @@ _Values_ covered by the interval can be of a different type than _distances_ bet
 For example, `IntInterval` has `Int` values and `UInt` distances:
 
 ```kotlin
-val interval = IntInterval(
-    start = 0,
-    isStartIncluded = true,
-    end = 10,
-    isEndIncluded = false
-)
+val interval: IntInterval = interval( 0, 10, isEndIncluded = false )
+val areIncluded = 0 in interval && 5 in interval // true
+val areExcluded = 10 !in interval && 15 !in interval // true
 val size: UInt = interval.size // 10
 ```
 

build.gradle.kts

@@ -14,7 +14,7 @@ plugins {
 }
 
 group = "io.github.whathecode.kotlinx.interval"
-version = "1.0.0-alpha.1"
+version = "1.0.0-alpha.2"
 
 repositories {
     mavenCentral()

src/commonMain/kotlin/BasicTypeIntervals.kt

@@ -20,6 +20,14 @@ class ByteInterval( start: Byte, isStartIncluded: Boolean, end: Byte, isEndInclu
     }
 }
 
+/**
+ * Create a [ByteInterval] representing the set of all [Byte] values lying between [start] and [end].
+ * To exclude endpoints, set [isStartIncluded] or [isEndIncluded] to false; a closed interval is created by default.
+ */
+fun interval( start: Byte, end: Byte, isStartIncluded: Boolean = true, isEndIncluded: Boolean = true ) =
+    ByteInterval( start, isStartIncluded, end, isEndIncluded )
+
+
 /**
  * An [Interval] representing the set of all [Short] values lying between a provided [start] and [end] value.
  * The interval can be closed, open, or half-open, as determined by [isStartIncluded] and [isEndIncluded].
@@ -37,6 +45,14 @@ class ShortInterval( start: Short, isStartIncluded: Boolean, end: Short, isEndIn
     }
 }
 
+/**
+ * Create a [ShortInterval] representing the set of all [Short] values lying between [start] and [end].
+ * To exclude endpoints, set [isStartIncluded] or [isEndIncluded] to false; a closed interval is created by default.
+ */
+fun interval( start: Short, end: Short, isStartIncluded: Boolean = true, isEndIncluded: Boolean = true ) =
+    ShortInterval( start, isStartIncluded, end, isEndIncluded )
+
+
 /**
  * An [Interval] representing the set of all [Int] values lying between a provided [start] and [end] value.
  * The interval can be closed, open, or half-open, as determined by [isStartIncluded] and [isEndIncluded].
@@ -54,6 +70,14 @@ class IntInterval( start: Int, isStartIncluded: Boolean, end: Int, isEndIncluded
     }
 }
 
+/**
+ * Create a [IntInterval] representing the set of all [Int] values lying between [start] and [end].
+ * To exclude endpoints, set [isStartIncluded] or [isEndIncluded] to false; a closed interval is created by default.
+ */
+fun interval( start: Int, end: Int, isStartIncluded: Boolean = true, isEndIncluded: Boolean = true ) =
+    IntInterval( start, isStartIncluded, end, isEndIncluded )
+
+
 /**
  * An [Interval] representing the set of all [Long] values lying between a provided [start] and [end] value.
  * The interval can be closed, open, or half-open, as determined by [isStartIncluded] and [isEndIncluded].
@@ -71,6 +95,14 @@ class LongInterval( start: Long, isStartIncluded: Boolean, end: Long, isEndInclu
     }
 }
 
+/**
+ * Create a [LongInterval] representing the set of all [Long] values lying between [start] and [end].
+ * To exclude endpoints, set [isStartIncluded] or [isEndIncluded] to false; a closed interval is created by default.
+ */
+fun interval( start: Long, end: Long, isStartIncluded: Boolean = true, isEndIncluded: Boolean = true ) =
+    LongInterval( start, isStartIncluded, end, isEndIncluded )
+
+
 /**
  * An [Interval] representing the set of all [Float] values lying between a provided [start] and [end] value.
  * The interval can be closed, open, or half-open, as determined by [isStartIncluded] and [isEndIncluded].
@@ -84,6 +116,14 @@ class FloatInterval( start: Float, isStartIncluded: Boolean, end: Float, isEndIn
     }
 }
 
+/**
+ * Create a [FloatInterval] representing the set of all [Float] values lying between [start] and [end].
+ * To exclude endpoints, set [isStartIncluded] or [isEndIncluded] to false; a closed interval is created by default.
+ */
+fun interval( start: Float, end: Float, isStartIncluded: Boolean = true, isEndIncluded: Boolean = true ) =
+    FloatInterval( start, isStartIncluded, end, isEndIncluded )
+
+
 /**
  * An [Interval] representing the set of all [Double] values lying between a provided [start] and [end] value.
  * The interval can be closed, open, or half-open, as determined by [isStartIncluded] and [isEndIncluded].
@@ -99,6 +139,14 @@ class DoubleInterval( start: Double, isStartIncluded: Boolean, end: Double, isEn
     }
 }
 
+/**
+ * Create a [DoubleInterval] representing the set of all [Double] values lying between [start] and [end].
+ * To exclude endpoints, set [isStartIncluded] or [isEndIncluded] to false; a closed interval is created by default.
+ */
+fun interval( start: Double, end: Double, isStartIncluded: Boolean = true, isEndIncluded: Boolean = true ) =
+    DoubleInterval( start, isStartIncluded, end, isEndIncluded )
+
+
 /**
  * An [Interval] representing the set of all [UByte] values lying between a provided [start] and [end] value.
  * The interval can be closed, open, or half-open, as determined by [isStartIncluded] and [isEndIncluded].
@@ -112,6 +160,14 @@ class UByteInterval( start: UByte, isStartIncluded: Boolean, end: UByte, isEndIn
     }
 }
 
+/**
+ * Create a [UByteInterval] representing the set of all [UByte] values lying between [start] and [end].
+ * To exclude endpoints, set [isStartIncluded] or [isEndIncluded] to false; a closed interval is created by default.
+ */
+fun interval( start: UByte, end: UByte, isStartIncluded: Boolean = true, isEndIncluded: Boolean = true ) =
+    UByteInterval( start, isStartIncluded, end, isEndIncluded )
+
+
 /**
  * An [Interval] representing the set of all [UShort] values lying between a provided [start] and [end] value.
  * The interval can be closed, open, or half-open, as determined by [isStartIncluded] and [isEndIncluded].
@@ -125,6 +181,14 @@ class UShortInterval( start: UShort, isStartIncluded: Boolean, end: UShort, isEn
     }
 }
 
+/**
+ * Create a [UShortInterval] representing the set of all [UShort] values lying between [start] and [end].
+ * To exclude endpoints, set [isStartIncluded] or [isEndIncluded] to false; a closed interval is created by default.
+ */
+fun interval( start: UShort, end: UShort, isStartIncluded: Boolean = true, isEndIncluded: Boolean = true ) =
+    UShortInterval( start, isStartIncluded, end, isEndIncluded )
+
+
 /**
  * An [Interval] representing the set of all [UInt] values lying between a provided [start] and [end] value.
  * The interval can be closed, open, or half-open, as determined by [isStartIncluded] and [isEndIncluded].
@@ -138,6 +202,14 @@ class UIntInterval( start: UInt, isStartIncluded: Boolean, end: UInt, isEndInclu
     }
 }
 
+/**
+ * Create a [UIntInterval] representing the set of all [UInt] values lying between [start] and [end].
+ * To exclude endpoints, set [isStartIncluded] or [isEndIncluded] to false; a closed interval is created by default.
+ */
+fun interval( start: UInt, end: UInt, isStartIncluded: Boolean = true, isEndIncluded: Boolean = true ) =
+    UIntInterval( start, isStartIncluded, end, isEndIncluded )
+
+
 /**
  * An [Interval] representing the set of all [ULong] values lying between a provided [start] and [end] value.
  * The interval can be closed, open, or half-open, as determined by [isStartIncluded] and [isEndIncluded].
@@ -151,6 +223,14 @@ class ULongInterval( start: ULong, isStartIncluded: Boolean, end: ULong, isEndIn
     }
 }
 
+/**
+ * Create a [ULongInterval] representing the set of all [ULong] values lying between [start] and [end].
+ * To exclude endpoints, set [isStartIncluded] or [isEndIncluded] to false; a closed interval is created by default.
+ */
+fun interval( start: ULong, end: ULong, isStartIncluded: Boolean = true, isEndIncluded: Boolean = true ) =
+    ULongInterval( start, isStartIncluded, end, isEndIncluded )
+
+
 /**
  * An [Interval] representing the set of all [Char] values lying between a provided [start] and [end] value.
  * The interval can be closed, open, or half-open, as determined by [isStartIncluded] and [isEndIncluded].
@@ -163,3 +243,10 @@ class CharInterval( start: Char, isStartIncluded: Boolean, end: Char, isEndInclu
         internal val Operations = createIntervalTypeOperations<Char, UShort> { it.code.toUShort() }
     }
 }
+
+/**
+ * Create a [CharInterval] representing the set of all [Char] values lying between [start] and [end].
+ * To exclude endpoints, set [isStartIncluded] or [isEndIncluded] to false; a closed interval is created by default.
+ */
+fun interval( start: Char, end: Char, isStartIncluded: Boolean = true, isEndIncluded: Boolean = true ) =
+    CharInterval( start, isStartIncluded, end, isEndIncluded )

src/commonMain/kotlin/Interval.kt

@@ -44,7 +44,7 @@ open class Interval<T : Comparable<T>, TSize : Comparable<TSize>>(
     /**
      * Determines whether the [start] of the interval is greater than the [end].
      */
-    inline val isReversed: Boolean get() =  start > end
+    inline val isReversed: Boolean get() = start > end
 
     /**
      * The absolute difference between [start] and [end].
@@ -67,6 +67,25 @@ open class Interval<T : Comparable<T>, TSize : Comparable<TSize>>(
         }
     }
 
+
+    /**
+     * Checks whether [value] lies within this interval.
+     */
+    operator fun contains( value: T ): Boolean
+    {
+        class Endpoint( val value: T, val isIncluded: Boolean )
+
+        val a = Endpoint( start, isStartIncluded )
+        val b = Endpoint( end, isEndIncluded )
+        val (smallest, greatest) = if ( isReversed ) b to a else a to b
+
+        val smallestComp = value.compareTo( smallest.value )
+        val greatestComp = value.compareTo( greatest.value )
+
+        return ( smallestComp > 0 || (smallestComp == 0 && smallest.isIncluded) )
+            && ( greatestComp < 0 || (greatestComp == 0 && greatest.isIncluded) )
+    }
+
     /**
      * Determines whether this interval equals [other]'s constructor parameters exactly,
      * i.e., not whether they represent the same set of [T] values, such as matching inverse intervals.

src/commonTest/kotlin/IntervalTest.kt

@@ -112,4 +112,28 @@ abstract class IntervalTest<T : Comparable<T>, TSize : Comparable<TSize>>(
             sizeOperations.unsafeAdd( rangeBelowIdentity, rangeAboveIdentity )
         )
     }
+
+    @Test
+    fun contains_for_values_within_interval()
+    {
+        val acIntervals = createAllInclusionTypeIntervals( a, c ) + createAllInclusionTypeIntervals( c, a )
+        acIntervals.forEach { assertTrue( b in it ) }
+    }
+
+    @Test
+    fun contains_for_values_on_endpoints_of_half_open_intervals()
+    {
+        val onlyAIncluded = listOf(
+            createInterval( a, true, b, false ),
+            createInterval( b, false, a, true )
+        )
+        onlyAIncluded.forEach { assertTrue(a in it && b !in it ) }
+    }
+
+    @Test
+    fun contains_for_values_on_endpoints_of_open_intervals()
+    {
+        val openIntervals = listOf( createOpenInterval( a, b ), createOpenInterval( b, a ) )
+        openIntervals.forEach { assertTrue( a !in it && b !in it ) }
+    }
 }

src/commonTest/kotlin/Readme.kt

@@ -8,12 +8,9 @@ class Readme
     @Test
     fun introduction_example()
     {
-        val interval = IntInterval(
-            start = 0,
-            isStartIncluded = true,
-            end = 10,
-            isEndIncluded = false
-        )
+        val interval: IntInterval = interval( 0, 10, isEndIncluded = false )
+        val areIncluded = 0 in interval && 5 in interval // true
+        val areExcluded = 10 !in interval && 15 !in interval // true
         val size: UInt = interval.size // 10
     }
 }