kotlin-stdlib/kotlin.ranges

Package-level declarations

Ranges, Progressions and related top-level and extension functions.

Types

Link copied to clipboard
open class CharProgression : Iterable<Char>

A progression of values of type Char.

Since Kotlin 1.0
Link copied to clipboard
class CharRange(start: Char, endInclusive: Char) : CharProgression, ClosedRange<Char> , OpenEndRange<Char>

A range of values of type Char.

Since Kotlin 1.0
Link copied to clipboard
interface ClosedFloatingPointRange<T : Comparable<T>> : ClosedRange<T>

Represents a range of floating point numbers. Extends ClosedRange interface providing custom operation lessThanOrEquals for comparing values of range domain type.

Since Kotlin 1.1
Link copied to clipboard
interface ClosedRange<T : Comparable<T>>

Represents a range of values (for example, numbers or characters) where both the lower and upper bounds are included in the range. See the Kotlin language documentation for more information.

Since Kotlin 1.0
Link copied to clipboard
open class IntProgression : Iterable<Int>

A progression of values of type Int.

Since Kotlin 1.0
Link copied to clipboard
class IntRange(start: Int, endInclusive: Int) : IntProgression, ClosedRange<Int> , OpenEndRange<Int>

A range of values of type Int.

Since Kotlin 1.0
Link copied to clipboard
open class LongProgression : Iterable<Long>

A progression of values of type Long.

Since Kotlin 1.0
Link copied to clipboard
class LongRange(start: Long, endInclusive: Long) : LongProgression, ClosedRange<Long> , OpenEndRange<Long>

A range of values of type Long.

Since Kotlin 1.0
Link copied to clipboard
interface OpenEndRange<T : Comparable<T>>

Represents a range of values (for example, numbers or characters) where the upper bound is not included in the range. See the Kotlin language documentation for more information.

Since Kotlin 1.9
Link copied to clipboard
open class UIntProgression : Iterable<UInt>

A progression of values of type UInt.

Since Kotlin 1.5
Link copied to clipboard
class UIntRange(start: UInt, endInclusive: UInt) : UIntProgression, ClosedRange<UInt> , OpenEndRange<UInt>

A range of values of type UInt.

Since Kotlin 1.5
Link copied to clipboard
open class ULongProgression : Iterable<ULong>

A progression of values of type ULong.

Since Kotlin 1.5
Link copied to clipboard
class ULongRange(start: ULong, endInclusive: ULong) : ULongProgression, ClosedRange<ULong> , OpenEndRange<ULong>

A range of values of type ULong.

Since Kotlin 1.5

Functions

Link copied to clipboard
fun <T : Comparable<T>> T.coerceAtLeast(minimumValue: T): T
fun Byte.coerceAtLeast(minimumValue: Byte): Byte
fun Double.coerceAtLeast(minimumValue: Double): Double
fun Float.coerceAtLeast(minimumValue: Float): Float
fun Int.coerceAtLeast(minimumValue: Int): Int
fun Long.coerceAtLeast(minimumValue: Long): Long
fun Short.coerceAtLeast(minimumValue: Short): Short

Ensures that this value is not less than the specified minimumValue.

Since Kotlin 1.0
fun UByte.coerceAtLeast(minimumValue: UByte): UByte
fun UInt.coerceAtLeast(minimumValue: UInt): UInt
fun ULong.coerceAtLeast(minimumValue: ULong): ULong
fun UShort.coerceAtLeast(minimumValue: UShort): UShort

Ensures that this value is not less than the specified minimumValue.

Since Kotlin 1.5
Link copied to clipboard
fun <T : Comparable<T>> T.coerceAtMost(maximumValue: T): T
fun Byte.coerceAtMost(maximumValue: Byte): Byte
fun Double.coerceAtMost(maximumValue: Double): Double
fun Float.coerceAtMost(maximumValue: Float): Float
fun Int.coerceAtMost(maximumValue: Int): Int
fun Long.coerceAtMost(maximumValue: Long): Long
fun Short.coerceAtMost(maximumValue: Short): Short

Ensures that this value is not greater than the specified maximumValue.

Since Kotlin 1.0
fun UByte.coerceAtMost(maximumValue: UByte): UByte
fun UInt.coerceAtMost(maximumValue: UInt): UInt
fun ULong.coerceAtMost(maximumValue: ULong): ULong
fun UShort.coerceAtMost(maximumValue: UShort): UShort

Ensures that this value is not greater than the specified maximumValue.

Since Kotlin 1.5
Link copied to clipboard
fun <T : Comparable<T>> T.coerceIn(range: ClosedFloatingPointRange<T>): T

Ensures that this value lies in the specified range.

Since Kotlin 1.1
fun <T : Comparable<T>> T.coerceIn(range: ClosedRange<T>): T
fun Int.coerceIn(range: ClosedRange<Int>): Int
fun Long.coerceIn(range: ClosedRange<Long>): Long

Ensures that this value lies in the specified range.

Since Kotlin 1.0
fun UInt.coerceIn(range: ClosedRange<UInt>): UInt
fun ULong.coerceIn(range: ClosedRange<ULong>): ULong

Ensures that this value lies in the specified range.

Since Kotlin 1.5
fun <T : Comparable<T>> T.coerceIn(minimumValue: T?, maximumValue: T?): T
fun Byte.coerceIn(minimumValue: Byte, maximumValue: Byte): Byte
fun Double.coerceIn(minimumValue: Double, maximumValue: Double): Double
fun Float.coerceIn(minimumValue: Float, maximumValue: Float): Float
fun Int.coerceIn(minimumValue: Int, maximumValue: Int): Int
fun Long.coerceIn(minimumValue: Long, maximumValue: Long): Long
fun Short.coerceIn(minimumValue: Short, maximumValue: Short): Short

Ensures that this value lies in the specified range minimumValue..maximumValue.

Since Kotlin 1.0
fun UByte.coerceIn(minimumValue: UByte, maximumValue: UByte): UByte
fun UInt.coerceIn(minimumValue: UInt, maximumValue: UInt): UInt
fun ULong.coerceIn(minimumValue: ULong, maximumValue: ULong): ULong
fun UShort.coerceIn(minimumValue: UShort, maximumValue: UShort): UShort

Ensures that this value lies in the specified range minimumValue..maximumValue.

Since Kotlin 1.5
Link copied to clipboard
inline operator fun <T : Any, R : ClosedRange<T>, Iterable<T>> R.contains(element: T?): Boolean

Returns true if this iterable range contains the specified element.

Since Kotlin 1.3
inline operator fun <T : Any, R : OpenEndRange<T>, Iterable<T>> R.contains(element: T?): Boolean

Returns true if this iterable range contains the specified element.

Since Kotlin 1.9
inline operator fun CharRange.contains(element: Char?): Boolean
inline operator fun IntRange.contains(element: Int?): Boolean
inline operator fun LongRange.contains(element: Long?): Boolean

Returns true if this range contains the specified element.

Since Kotlin 1.3
@JvmName(name = "byteRangeContains")
operator fun ClosedRange<Byte>.contains(value: Double): Boolean
@JvmName(name = "byteRangeContains")
operator fun ClosedRange<Byte>.contains(value: Float): Boolean
@JvmName(name = "byteRangeContains")
operator fun ClosedRange<Byte>.contains(value: Int): Boolean
@JvmName(name = "byteRangeContains")
operator fun ClosedRange<Byte>.contains(value: Long): Boolean
@JvmName(name = "byteRangeContains")
operator fun ClosedRange<Byte>.contains(value: Short): Boolean
@JvmName(name = "doubleRangeContains")
operator fun ClosedRange<Double>.contains(value: Byte): Boolean
@JvmName(name = "doubleRangeContains")
operator fun ClosedRange<Double>.contains(value: Float): Boolean
@JvmName(name = "doubleRangeContains")
operator fun ClosedRange<Double>.contains(value: Int): Boolean
@JvmName(name = "doubleRangeContains")
operator fun ClosedRange<Double>.contains(value: Long): Boolean
@JvmName(name = "doubleRangeContains")
operator fun ClosedRange<Double>.contains(value: Short): Boolean
@JvmName(name = "floatRangeContains")
operator fun ClosedRange<Float>.contains(value: Byte): Boolean
@JvmName(name = "floatRangeContains")
operator fun ClosedRange<Float>.contains(value: Double): Boolean
@JvmName(name = "floatRangeContains")
operator fun ClosedRange<Float>.contains(value: Int): Boolean
@JvmName(name = "floatRangeContains")
operator fun ClosedRange<Float>.contains(value: Long): Boolean
@JvmName(name = "floatRangeContains")
operator fun ClosedRange<Float>.contains(value: Short): Boolean
@JvmName(name = "intRangeContains")
operator fun ClosedRange<Int>.contains(value: Byte): Boolean
@JvmName(name = "intRangeContains")
operator fun ClosedRange<Int>.contains(value: Double): Boolean
@JvmName(name = "intRangeContains")
operator fun ClosedRange<Int>.contains(value: Float): Boolean
@JvmName(name = "intRangeContains")
operator fun ClosedRange<Int>.contains(value: Long): Boolean
@JvmName(name = "intRangeContains")
operator fun ClosedRange<Int>.contains(value: Short): Boolean
@JvmName(name = "longRangeContains")
operator fun ClosedRange<Long>.contains(value: Byte): Boolean
@JvmName(name = "longRangeContains")
operator fun ClosedRange<Long>.contains(value: Double): Boolean
@JvmName(name = "longRangeContains")
operator fun ClosedRange<Long>.contains(value: Float): Boolean
@JvmName(name = "longRangeContains")
operator fun ClosedRange<Long>.contains(value: Int): Boolean
@JvmName(name = "longRangeContains")
operator fun ClosedRange<Long>.contains(value: Short): Boolean
@JvmName(name = "shortRangeContains")
operator fun ClosedRange<Short>.contains(value: Byte): Boolean
@JvmName(name = "shortRangeContains")
operator fun ClosedRange<Short>.contains(value: Double): Boolean
@JvmName(name = "shortRangeContains")
operator fun ClosedRange<Short>.contains(value: Float): Boolean
@JvmName(name = "shortRangeContains")
operator fun ClosedRange<Short>.contains(value: Int): Boolean
@JvmName(name = "shortRangeContains")
operator fun ClosedRange<Short>.contains(value: Long): Boolean
inline operator fun IntRange.contains(value: Byte): Boolean
inline operator fun IntRange.contains(value: Long): Boolean
inline operator fun IntRange.contains(value: Short): Boolean
inline operator fun LongRange.contains(value: Byte): Boolean
inline operator fun LongRange.contains(value: Int): Boolean
inline operator fun LongRange.contains(value: Short): Boolean

Checks if the specified value belongs to this range.

Since Kotlin 1.0
@JvmName(name = "byteRangeContains")
operator fun OpenEndRange<Byte>.contains(value: Int): Boolean
@JvmName(name = "byteRangeContains")
operator fun OpenEndRange<Byte>.contains(value: Long): Boolean
@JvmName(name = "byteRangeContains")
operator fun OpenEndRange<Byte>.contains(value: Short): Boolean
@JvmName(name = "doubleRangeContains")
operator fun OpenEndRange<Double>.contains(value: Float): Boolean
@JvmName(name = "intRangeContains")
operator fun OpenEndRange<Int>.contains(value: Byte): Boolean
@JvmName(name = "intRangeContains")
operator fun OpenEndRange<Int>.contains(value: Long): Boolean
@JvmName(name = "intRangeContains")
operator fun OpenEndRange<Int>.contains(value: Short): Boolean
@JvmName(name = "longRangeContains")
operator fun OpenEndRange<Long>.contains(value: Byte): Boolean
@JvmName(name = "longRangeContains")
operator fun OpenEndRange<Long>.contains(value: Int): Boolean
@JvmName(name = "longRangeContains")
operator fun OpenEndRange<Long>.contains(value: Short): Boolean
@JvmName(name = "shortRangeContains")
operator fun OpenEndRange<Short>.contains(value: Byte): Boolean
@JvmName(name = "shortRangeContains")
operator fun OpenEndRange<Short>.contains(value: Int): Boolean
@JvmName(name = "shortRangeContains")
operator fun OpenEndRange<Short>.contains(value: Long): Boolean

Checks if the specified value belongs to this range.

Since Kotlin 1.9
operator fun UIntRange.contains(value: UByte): Boolean
operator fun UIntRange.contains(value: ULong): Boolean
operator fun UIntRange.contains(value: UShort): Boolean
operator fun ULongRange.contains(value: UByte): Boolean
operator fun ULongRange.contains(value: UInt): Boolean
operator fun ULongRange.contains(value: UShort): Boolean

Checks if the specified value belongs to this range.

Since Kotlin 1.5
inline operator fun UIntRange.contains(element: UInt?): Boolean
inline operator fun ULongRange.contains(element: ULong?): Boolean

Returns true if this range contains the specified element.

Since Kotlin 1.5
Link copied to clipboard
infix fun Byte.downTo(to: Byte): IntProgression
infix fun Byte.downTo(to: Int): IntProgression
infix fun Byte.downTo(to: Long): LongProgression
infix fun Byte.downTo(to: Short): IntProgression
infix fun Char.downTo(to: Char): CharProgression
infix fun Int.downTo(to: Byte): IntProgression
infix fun Int.downTo(to: Int): IntProgression
infix fun Int.downTo(to: Long): LongProgression
infix fun Int.downTo(to: Short): IntProgression
infix fun Long.downTo(to: Byte): LongProgression
infix fun Long.downTo(to: Int): LongProgression
infix fun Long.downTo(to: Long): LongProgression
infix fun Long.downTo(to: Short): LongProgression
infix fun Short.downTo(to: Byte): IntProgression
infix fun Short.downTo(to: Int): IntProgression
infix fun Short.downTo(to: Long): LongProgression
infix fun Short.downTo(to: Short): IntProgression

Returns a progression from this value down to the specified to value with the step -1.

Since Kotlin 1.0
infix fun UByte.downTo(to: UByte): UIntProgression
infix fun UInt.downTo(to: UInt): UIntProgression
infix fun ULong.downTo(to: ULong): ULongProgression
infix fun UShort.downTo(to: UShort): UIntProgression

Returns a progression from this value down to the specified to value with the step -1.

Since Kotlin 1.5
Link copied to clipboard
fun CharProgression.first(): Char
fun IntProgression.first(): Int
fun LongProgression.first(): Long
fun UIntProgression.first(): UInt
fun ULongProgression.first(): ULong

Returns the first element.

Since Kotlin 1.7
Link copied to clipboard
fun CharProgression.firstOrNull(): Char?
fun IntProgression.firstOrNull(): Int?
fun LongProgression.firstOrNull(): Long?
fun UIntProgression.firstOrNull(): UInt?
fun ULongProgression.firstOrNull(): ULong?

Returns the first element, or null if the progression is empty.

Since Kotlin 1.7
Link copied to clipboard
fun CharProgression.last(): Char
fun IntProgression.last(): Int
fun LongProgression.last(): Long
fun UIntProgression.last(): UInt
fun ULongProgression.last(): ULong

Returns the last element.

Since Kotlin 1.7
Link copied to clipboard
fun CharProgression.lastOrNull(): Char?
fun IntProgression.lastOrNull(): Int?
fun LongProgression.lastOrNull(): Long?
fun UIntProgression.lastOrNull(): UInt?
fun ULongProgression.lastOrNull(): ULong?

Returns the last element, or null if the progression is empty.

Since Kotlin 1.7
Link copied to clipboard
inline fun CharRange.random(): Char
inline fun IntRange.random(): Int
inline fun LongRange.random(): Long

Returns a random element from this range.

Since Kotlin 1.3
inline fun UIntRange.random(): UInt
inline fun ULongRange.random(): ULong

Returns a random element from this range.

Since Kotlin 1.5
fun CharRange.random(random: Random): Char
fun IntRange.random(random: Random): Int
fun LongRange.random(random: Random): Long

Returns a random element from this range using the specified source of randomness.

Since Kotlin 1.3
fun UIntRange.random(random: Random): UInt
fun ULongRange.random(random: Random): ULong

Returns a random element from this range using the specified source of randomness.

Since Kotlin 1.5
Link copied to clipboard
inline fun CharRange.randomOrNull(): Char?
inline fun IntRange.randomOrNull(): Int?
inline fun LongRange.randomOrNull(): Long?

Returns a random element from this range, or null if this range is empty.

Since Kotlin 1.4
inline fun UIntRange.randomOrNull(): UInt?
inline fun ULongRange.randomOrNull(): ULong?

Returns a random element from this range, or null if this range is empty.

Since Kotlin 1.5
fun CharRange.randomOrNull(random: Random): Char?
fun IntRange.randomOrNull(random: Random): Int?
fun LongRange.randomOrNull(random: Random): Long?

Returns a random element from this range using the specified source of randomness, or null if this range is empty.

Since Kotlin 1.4
fun UIntRange.randomOrNull(random: Random): UInt?
fun ULongRange.randomOrNull(random: Random): ULong?

Returns a random element from this range using the specified source of randomness, or null if this range is empty.

Since Kotlin 1.5
Link copied to clipboard
operator fun <T : Comparable<T>> T.rangeTo(that: T): ClosedRange<T>

Creates a range from this Comparable value to the specified that value.

Since Kotlin 1.0
operator fun Double.rangeTo(that: Double): ClosedFloatingPointRange<Double>

Creates a range from this Double value to the specified that value.

Since Kotlin 1.1
operator fun Float.rangeTo(that: Float): ClosedFloatingPointRange<Float>

Creates a range from this Float value to the specified that value.

Since Kotlin 1.1
Link copied to clipboard
operator fun <T : Comparable<T>> T.rangeUntil(that: T): OpenEndRange<T>

Creates an open-ended range from this Comparable value to the specified that value.

Since Kotlin 1.9
operator fun Double.rangeUntil(that: Double): OpenEndRange<Double>

Creates an open-ended range from this Double value to the specified that value.

Since Kotlin 1.9
operator fun Float.rangeUntil(that: Float): OpenEndRange<Float>

Creates an open-ended range from this Float value to the specified that value.

Since Kotlin 1.9
Link copied to clipboard
fun CharProgression.reversed(): CharProgression
fun IntProgression.reversed(): IntProgression
fun LongProgression.reversed(): LongProgression

Returns a progression that goes over the same range in the opposite direction with the same step.

Since Kotlin 1.0
fun UIntProgression.reversed(): UIntProgression
fun ULongProgression.reversed(): ULongProgression

Returns a progression that goes over the same range in the opposite direction with the same step.

Since Kotlin 1.5
Link copied to clipboard
infix fun CharProgression.step(step: Int): CharProgression
infix fun IntProgression.step(step: Int): IntProgression
infix fun LongProgression.step(step: Long): LongProgression

Returns a progression that goes over the same range with the given step.

Since Kotlin 1.0
infix fun UIntProgression.step(step: Int): UIntProgression
infix fun ULongProgression.step(step: Long): ULongProgression

Returns a progression that goes over the same range with the given step.

Since Kotlin 1.5
Link copied to clipboard
infix fun Byte.until(to: Byte): IntRange
infix fun Byte.until(to: Int): IntRange
infix fun Byte.until(to: Long): LongRange
infix fun Byte.until(to: Short): IntRange
infix fun Char.until(to: Char): CharRange
infix fun Int.until(to: Byte): IntRange
infix fun Int.until(to: Int): IntRange
infix fun Int.until(to: Long): LongRange
infix fun Int.until(to: Short): IntRange
infix fun Long.until(to: Byte): LongRange
infix fun Long.until(to: Int): LongRange
infix fun Long.until(to: Long): LongRange
infix fun Long.until(to: Short): LongRange
infix fun Short.until(to: Byte): IntRange
infix fun Short.until(to: Int): IntRange
infix fun Short.until(to: Long): LongRange
infix fun Short.until(to: Short): IntRange

Returns a range from this value up to but excluding the specified to value.

Since Kotlin 1.0
infix fun UByte.until(to: UByte): UIntRange
infix fun UInt.until(to: UInt): UIntRange
infix fun ULong.until(to: ULong): ULongRange
infix fun UShort.until(to: UShort): UIntRange

Returns a range from this value up to but excluding the specified to value.

Since Kotlin 1.5