Merge branch 'develop'

Author: Whathecode

.gitignore

@@ -9,3 +9,6 @@ out/
 
 # Ignore files with secrets
 publish.properties
+
+# Kotlin build files
+.kotlin

README.md

@@ -26,6 +26,71 @@ val areIncluded = now + 50.seconds in interval // true
 val size: Duration = interval.size // 100 seconds
 ```
 
+## Interval Unions
+
+Intervals are a subset of _interval unions_, which represent a collection of intervals.
+The result of operations on an interval can result in an interval union.
+Since operations are generally defined on the base interface, you can easily chain operations without caring about the concrete type.
+
+```kotlin
+val start = interval( 0, 100 ) // Interval: [0, 100]
+val areIncluded = 50 in start && 100 in start // true
+val splitInTwo = start - interval( 25, 85 ) // Union: [[0, 25), (85, 100]]
+val areExcluded = 50 !in splitInTwo && 85 !in splitInTwo // true
+val unite = splitInTwo + interval( 10, 90 ) // Interval: [0, 100]
+val backToStart = start == unite // true
+```
+
+An interval union contains any number of intervals.
+
+| Intervals in a union |             Description             | 
+|:--------------------:|:-----------------------------------:|
+|          0           |            An empty set             |
+|          1           |             An interval             |
+|         > 1          | Disjoint and non-adjacent intervals |
+
+Intervals in a union can be iterated over in order and don't intersect (are disjoint), and will always have _some_ values lying in between them (are non-adjacent).
+E.g., `[4, 5]` and `[6, 7]` are adjacent intervals in case they use integer types.
+Two non-intersecting intervals with a shared endpoint are also adjacent, regardless of type, if one of the intervals includes the endpoint.
+E.g., `[4.0, 5.0)` and `[5.0, 7.0]` are adjacent.
+Instead, these are represented as a single interval: `[4, 7]` and `[4.0, 7.0]` respectively.
+
+## Operations
+
+Intervals and interval unions are immutable.
+Operations don't modify the instance the operation is executed on.
+Instead, new instances are returned if the operation results in a different set of values.
+
+The following operations are available for any `IntervalUnion<T, TSize>`:
+
+|      Operation      |                                         Description                                          | 
+|:-------------------:|:--------------------------------------------------------------------------------------------:|
+|     `isEmpty()`     |                           Determines whether this is an empty set.                           |
+|    `getBounds()`    |                          Gets the upper and lower bound of the set.                          |
+| `contains()` (`in`) |                         Determines whether a value lies in the set.                          |
+|   `minus()` (`-`)   |                              Subtract an interval from the set.                              |
+|   `plus()` (`+`)    |                                Add an interval from the set.                                 |
+|   `intersects()`    |                Determines whether another interval intersects with this set.                 |
+|    `setEquals()`    |                     Determines whether a set represents the same values.                     |
+|    `iterator()`     |                      Iterate over all intervals in the union, in order.                      |
+|    `toString()`     | Output as a string using common interval notation, e.g., `[0, 10]` or `[[0, 10), (10, 20]]`. |
+
+The following operations are specific to `Interval<T, TSize>`:
+
+|                   Operation                    |                                                Description                                                 | 
+|:----------------------------------------------:|:----------------------------------------------------------------------------------------------------------:|
+|                 `start`, `end`                 |                     The values originally passed as the start and end of the interval.                     |
+|       `isStartIncluded`, `isEndIncluded`       |              Determines whether `start` and `end` respectively are included in the interval.               |
+|               `isClosedInterval`               |                  Determines whether both `start` and `end` are included in the interval.                   |
+|                `isOpenInterval`                |                 Determines whether both `start` and `end` are excluded from the interval.                  |
+|                  `isReversed`                  |                             Determines whether `start` is greater than `end`.                              |
+|           `lowerBound`, `upperBound`           |                       Corresponds to `start` and `end`, but swapped if `isReversed`.                       |
+| `isLowerBoundIncluded`, `isUpperBoundIncluded` |             Corresponds to `isStartIncluded` and `isEndIncluded`, but swapped if `isReversed`.             |
+|                     `size`                     |                             The absolute difference between `start` and `end`.                             |
+|                `nonReversed()`                 |                             `reverse()` the interval in case it `isReversed`.                              |
+|                  `reverse()`                   |             Return an interval which swaps `start` with `end`, as well as boundary inclusions.             |
+|                `canonicalize()`                | Return the interval in canonical form. E.g., The canonical form of `[5, 1)` is `[2, 5]` for integer types. |
+
 ## Interval Types
 
 This library includes a generic base class `Interval<T, TSize>` which can be used to create intervals for any type.

build-logic/build.gradle.kts

@@ -8,6 +8,6 @@ repositories {
 }
 
 dependencies {
-    implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.23")
+    implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:2.0.0")
     implementation("org.jetbrains.dokka:dokka-gradle-plugin:1.9.20")
 }

build-logic/src/main/kotlin/interval.library-conventions.gradle.kts

@@ -2,6 +2,8 @@ import java.io.FileInputStream
 import java.util.Properties
 import org.jetbrains.dokka.Platform
 import org.jetbrains.dokka.gradle.DokkaTask
+import org.jetbrains.kotlin.gradle.ExperimentalKotlinGradlePluginApi
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
 
 
 plugins {
@@ -18,8 +20,9 @@ repositories {
 
 kotlin {
     jvm {
-        compilations.all {
-            kotlinOptions.jvmTarget = "1.8"
+        @OptIn(ExperimentalKotlinGradlePluginApi::class)
+        compilerOptions {
+            jvmTarget = JvmTarget.JVM_1_8
         }
         testRuns["test"].executionTask.configure {
             useJUnitPlatform()

build.gradle.kts

@@ -1,5 +1,5 @@
 plugins {
-    id("io.github.gradle-nexus.publish-plugin") version "1.1.0"
+    id("io.github.gradle-nexus.publish-plugin") version "2.0.0"
 }
 
 repositories {
@@ -21,7 +21,7 @@ if (publishPropertiesFile.exists()) {
     publishProperties.load(java.io.FileInputStream(publishPropertiesFile))
 }
 group = "io.github.whathecode.kotlinx.interval"
-version = "1.0.0-alpha.5"
+version = "1.0.0"
 nexusPublishing {
     repositories {
         sonatype {

gradle/wrapper/gradle-wrapper.properties

@@ -1,5 +1,5 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.6-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.9-bin.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists