Enables representation and manipulation of bounded intervals, supporting closed, open, or half-open types. Features operations on intervals and unions with generic type support, ensuring type-safe distance calculations.
Represent closed, open, or half-open, bounded intervals in Kotlin and perform common operations on them. Values covered by the interval can be of a different type than distances between those values.
For example, IntInterval has Int values and UInt distances:
val interval: IntInterval = interval( 0, 10, isEndIncluded = false )
val areIncluded = 0 in interval && 5 in interval // true
val areExcluded = ! interval && ! interval
size: UInt = interval.size
shifted = interval shr 10u
This protects against overflows (e.g. if size > Int.MAX_VALUE) but also offers better semantics.
For example, this library supports Instant values which are a Duration apart.
val now = Clock.System.now()
val interval: InstantInterval = interval( now, now + 100.seconds )
val areIncluded = now + 50.seconds in interval // true
val size: Duration = interval.size // 100 seconds
val shifted = interval shr 24.hours // 100 seconds 24 hours from now
Intervals support common math operations which allow concisely expressing common use cases.
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.
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: and respectively.
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>:
The following operations are specific to Interval<T, TSize>:
This library includes a generic base class Interval<T, TSize> which can be used to create intervals for any type.
To achieve this, it directs type operations to IntervalTypeOperations which the constructor takes as a parameter.
The following interval types are included in io.github.whathecode.kotlinx.interval:kotlinx-interval on Maven:
// Two intervals of different types: a timeline visualized at some screen coordinates.
val start2025 = LocalDateTime( 2025, 1, 1, 0, 0 ).toInstant( TimeZone.UTC )
val end2025 = LocalDateTime( 2026, 1, 1, 0, 0 ).toInstant( TimeZone.UTC )
val year2025: InstantInterval = interval( start2025, end2025 )
val timelineUi: IntInterval = interval( 0, 800 ) // UI element 800 pixels wide
// Find the selected time at a given UI coordinate using linear interpolation.
val mouseX = 400
val uiPercentage: Double = timelineUi.getPercentageFor( mouseX )
val selectedTime: Instant = year2025.getValueAt( uiPercentage ) // July 2nd at noon.
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 shiftBackAndForth = splitInTwo shr 100u shl 100u // == splitInTwo
val areExcluded = 50 !in splitInTwo && 85 !in splitInTwo // true
val unite = splitInTwo + interval( 10, 90 ) // Interval: [0, 100]
val backToStart = start == unite // true
[4, 7][4.0, 7.0]| 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 to the set. |
shift() (shl/shr) | Move the interval by a specified offset. |
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]]. |
| 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. |
getValueAt() | Get the value at a given percentage inside (0.0–1.0) or outside (< 0.0, > 1.0) the interval. |
getPercentageFor() | Gets the percentage how far within (0.0-1.0) or outside (< 0.0, > 1.0) of the interval a value lies. |
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. |
| Type | Values (T) | Distances (TSize) |
|---|
ByteInterval | Byte | UByte |
ShortInterval | Short | UShort |
IntInterval | Int | UInt |
LongInterval | Long | ULong |
FloatInterval | Float | Double |
DoubleInterval | Double | Double |
UByteInterval | UByte | UByte |
UShortInterval | UShort | UShort |
UIntInterval | UInt | UInt |
ULongInterval | ULong | ULong |
CharInterval | Char | UShort |
InstantInterval | Instant | Duration |
Surfaced from shared tags and platforms — no rankings paid for.