kotlin-stdlib / kotlin.ranges

Package kotlin.ranges

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

Types

Common
JVM
JS
Native
1.0

CharProgression

A progression of values of type Char.

open class CharProgression : Iterable<Char>
Common
JVM
JS
Native
1.0

CharRange

A range of values of type Char.

class CharRange : 
    CharProgression,
    ClosedRange<Char>,
    OpenEndRange<Char>
Common
JVM
JS
Native
1.1

ClosedFloatingPointRange

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

interface ClosedFloatingPointRange<T : Comparable<T>> : 
    ClosedRange<T>
Common
JVM
JS
Native
1.0

ClosedRange

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.

interface ClosedRange<T : Comparable<T>>
Common
JVM
JS
Native
1.0

IntProgression

A progression of values of type Int.

open class IntProgression : Iterable<Int>
Common
JVM
JS
Native
1.0

IntRange

A range of values of type Int.

class IntRange : 
    IntProgression,
    ClosedRange<Int>,
    OpenEndRange<Int>
Common
JVM
JS
Native
1.0

LongProgression

A progression of values of type Long.

open class LongProgression : Iterable<Long>
Common
JVM
JS
Native
1.0

LongRange

A range of values of type Long.

class LongRange : 
    LongProgression,
    ClosedRange<Long>,
    OpenEndRange<Long>
Common
JVM
JS
Native
1.9

OpenEndRange

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.

interface OpenEndRange<T : Comparable<T>>
Common
JVM
JS
Native
1.5

UIntProgression

A progression of values of type UInt.

open class UIntProgression : Iterable<UInt>
Common
JVM
JS
Native
1.5

UIntRange

A range of values of type UInt.

class UIntRange : 
    UIntProgression,
    ClosedRange<UInt>,
    OpenEndRange<UInt>
Common
JVM
JS
Native
1.5

ULongProgression

A progression of values of type ULong.

open class ULongProgression : Iterable<ULong>
Common
JVM
JS
Native
1.5

ULongRange

A range of values of type ULong.

class ULongRange : 
    ULongProgression,
    ClosedRange<ULong>,
    OpenEndRange<ULong>

Functions

Common
JVM
JS
Native
1.0

coerceAtLeast

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

fun <T : Comparable<T>> T.coerceAtLeast(minimumValue: T): T
fun Byte.coerceAtLeast(minimumValue: Byte): Byte
fun Short.coerceAtLeast(minimumValue: Short): Short
fun Int.coerceAtLeast(minimumValue: Int): Int
fun Long.coerceAtLeast(minimumValue: Long): Long
fun Float.coerceAtLeast(minimumValue: Float): Float
fun Double.coerceAtLeast(minimumValue: Double): Double
fun UInt.coerceAtLeast(minimumValue: UInt): UInt
fun ULong.coerceAtLeast(minimumValue: ULong): ULong
fun UByte.coerceAtLeast(minimumValue: UByte): UByte
fun UShort.coerceAtLeast(minimumValue: UShort): UShort
Common
JVM
JS
Native
1.0

coerceAtMost

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

fun <T : Comparable<T>> T.coerceAtMost(maximumValue: T): T
fun Byte.coerceAtMost(maximumValue: Byte): Byte
fun Short.coerceAtMost(maximumValue: Short): Short
fun Int.coerceAtMost(maximumValue: Int): Int
fun Long.coerceAtMost(maximumValue: Long): Long
fun Float.coerceAtMost(maximumValue: Float): Float
fun Double.coerceAtMost(maximumValue: Double): Double
fun UInt.coerceAtMost(maximumValue: UInt): UInt
fun ULong.coerceAtMost(maximumValue: ULong): ULong
fun UByte.coerceAtMost(maximumValue: UByte): UByte
fun UShort.coerceAtMost(maximumValue: UShort): UShort
Common
JVM
JS
Native
1.0

coerceIn

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

fun <T : Comparable<T>> T.coerceIn(
    minimumValue: T?,
    maximumValue: T?
): T
fun Byte.coerceIn(
    minimumValue: Byte,
    maximumValue: Byte
): Byte
fun Short.coerceIn(
    minimumValue: Short,
    maximumValue: Short
): Short
fun Int.coerceIn(minimumValue: Int, maximumValue: Int): Int
fun Long.coerceIn(
    minimumValue: Long,
    maximumValue: Long
): Long
fun Float.coerceIn(
    minimumValue: Float,
    maximumValue: Float
): Float
fun Double.coerceIn(
    minimumValue: Double,
    maximumValue: Double
): Double
fun UInt.coerceIn(
    minimumValue: UInt,
    maximumValue: UInt
): UInt
fun ULong.coerceIn(
    minimumValue: ULong,
    maximumValue: ULong
): ULong
fun UByte.coerceIn(
    minimumValue: UByte,
    maximumValue: UByte
): UByte
fun UShort.coerceIn(
    minimumValue: UShort,
    maximumValue: UShort
): UShort

Ensures that this value lies in the specified range.

fun <T : Comparable<T>> T.coerceIn(
    range: ClosedFloatingPointRange<T>
): T
fun <T : Comparable<T>> T.coerceIn(range: ClosedRange<T>): T
fun Int.coerceIn(range: ClosedRange<Int>): Int
fun Long.coerceIn(range: ClosedRange<Long>): Long
fun UInt.coerceIn(range: ClosedRange<UInt>): UInt
fun ULong.coerceIn(range: ClosedRange<ULong>): ULong
Common
JVM
JS
Native
1.0

contains

Returns true if this range contains the specified element.

operator fun IntRange.contains(element: Int?): Boolean
operator fun LongRange.contains(element: Long?): Boolean
operator fun CharRange.contains(element: Char?): Boolean
operator fun UIntRange.contains(element: UInt?): Boolean
operator fun ULongRange.contains(element: ULong?): Boolean

Checks if the specified value belongs to this range.

operator fun ClosedRange<Int>.contains(value: Byte): Boolean
operator fun ClosedRange<Long>.contains(value: Byte): Boolean
operator fun ClosedRange<Short>.contains(
    value: Byte
): Boolean
operator fun ClosedRange<Double>.contains(
    value: Byte
): Boolean
operator fun ClosedRange<Float>.contains(
    value: Byte
): Boolean
operator fun OpenEndRange<Int>.contains(value: Byte): Boolean
operator fun OpenEndRange<Long>.contains(
    value: Byte
): Boolean
operator fun OpenEndRange<Short>.contains(
    value: Byte
): Boolean
operator fun IntRange.contains(value: Byte): Boolean
operator fun LongRange.contains(value: Byte): Boolean
operator fun ClosedRange<Int>.contains(
    value: Double
): Boolean
operator fun ClosedRange<Long>.contains(
    value: Double
): Boolean
operator fun ClosedRange<Byte>.contains(
    value: Double
): Boolean
operator fun ClosedRange<Short>.contains(
    value: Double
): Boolean
operator fun ClosedRange<Float>.contains(
    value: Double
): Boolean
operator fun ClosedRange<Int>.contains(value: Float): Boolean
operator fun ClosedRange<Long>.contains(
    value: Float
): Boolean
operator fun ClosedRange<Byte>.contains(
    value: Float
): Boolean
operator fun ClosedRange<Short>.contains(
    value: Float
): Boolean
operator fun ClosedRange<Double>.contains(
    value: Float
): Boolean
operator fun OpenEndRange<Double>.contains(
    value: Float
): Boolean
operator fun ClosedRange<Long>.contains(value: Int): Boolean
operator fun ClosedRange<Byte>.contains(value: Int): Boolean
operator fun ClosedRange<Short>.contains(value: Int): Boolean
operator fun ClosedRange<Double>.contains(
    value: Int
): Boolean
operator fun ClosedRange<Float>.contains(value: Int): Boolean
operator fun OpenEndRange<Long>.contains(value: Int): Boolean
operator fun OpenEndRange<Byte>.contains(value: Int): Boolean
operator fun OpenEndRange<Short>.contains(
    value: Int
): Boolean
operator fun LongRange.contains(value: Int): Boolean
operator fun ClosedRange<Int>.contains(value: Long): Boolean
operator fun ClosedRange<Byte>.contains(value: Long): Boolean
operator fun ClosedRange<Short>.contains(
    value: Long
): Boolean
operator fun ClosedRange<Double>.contains(
    value: Long
): Boolean
operator fun ClosedRange<Float>.contains(
    value: Long
): Boolean
operator fun OpenEndRange<Int>.contains(value: Long): Boolean
operator fun OpenEndRange<Byte>.contains(
    value: Long
): Boolean
operator fun OpenEndRange<Short>.contains(
    value: Long
): Boolean
operator fun IntRange.contains(value: Long): Boolean
operator fun ClosedRange<Int>.contains(value: Short): Boolean
operator fun ClosedRange<Long>.contains(
    value: Short
): Boolean
operator fun ClosedRange<Byte>.contains(
    value: Short
): Boolean
operator fun ClosedRange<Double>.contains(
    value: Short
): Boolean
operator fun ClosedRange<Float>.contains(
    value: Short
): Boolean
operator fun OpenEndRange<Int>.contains(
    value: Short
): Boolean
operator fun OpenEndRange<Long>.contains(
    value: Short
): Boolean
operator fun OpenEndRange<Byte>.contains(
    value: Short
): Boolean
operator fun IntRange.contains(value: Short): Boolean
operator fun LongRange.contains(value: Short): Boolean
operator fun UIntRange.contains(value: UByte): Boolean
operator fun ULongRange.contains(value: UByte): Boolean
operator fun ULongRange.contains(value: UInt): Boolean
operator fun UIntRange.contains(value: ULong): Boolean
operator fun UIntRange.contains(value: UShort): Boolean
operator fun ULongRange.contains(value: UShort): Boolean

Returns true if this iterable range contains the specified element.

operator fun <T : Any, R> R.contains(
    element: T?
): Boolean where R : ClosedRange<T>, R : Iterable<T>
Common
JVM
JS
Native
1.0

downTo

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

infix fun Int.downTo(to: Byte): IntProgression
infix fun Long.downTo(to: Byte): LongProgression
infix fun Byte.downTo(to: Byte): IntProgression
infix fun Short.downTo(to: Byte): IntProgression
infix fun Char.downTo(to: Char): CharProgression
infix fun Int.downTo(to: Int): IntProgression
infix fun Long.downTo(to: Int): LongProgression
infix fun Byte.downTo(to: Int): IntProgression
infix fun Short.downTo(to: Int): IntProgression
infix fun Int.downTo(to: Long): LongProgression
infix fun Long.downTo(to: Long): LongProgression
infix fun Byte.downTo(to: Long): LongProgression
infix fun Short.downTo(to: Long): LongProgression
infix fun Int.downTo(to: Short): IntProgression
infix fun Long.downTo(to: Short): LongProgression
infix fun Byte.downTo(to: Short): IntProgression
infix fun Short.downTo(to: Short): IntProgression
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
Common
JVM
JS
Native
1.7

first

Returns the first element.

fun IntProgression.first(): Int
fun LongProgression.first(): Long
fun CharProgression.first(): Char
fun UIntProgression.first(): UInt
fun ULongProgression.first(): ULong
Common
JVM
JS
Native
1.7

firstOrNull

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

fun IntProgression.firstOrNull(): Int?
fun LongProgression.firstOrNull(): Long?
fun CharProgression.firstOrNull(): Char?
fun UIntProgression.firstOrNull(): UInt?
fun ULongProgression.firstOrNull(): ULong?
Common
JVM
JS
Native
1.7

last

Returns the last element.

fun IntProgression.last(): Int
fun LongProgression.last(): Long
fun CharProgression.last(): Char
fun UIntProgression.last(): UInt
fun ULongProgression.last(): ULong
Common
JVM
JS
Native
1.7

lastOrNull

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

fun IntProgression.lastOrNull(): Int?
fun LongProgression.lastOrNull(): Long?
fun CharProgression.lastOrNull(): Char?
fun UIntProgression.lastOrNull(): UInt?
fun ULongProgression.lastOrNull(): ULong?
Common
JVM
JS
Native
1.3

random

Returns a random element from this range.

fun IntRange.random(): Int
fun LongRange.random(): Long
fun CharRange.random(): Char
fun UIntRange.random(): UInt
fun ULongRange.random(): ULong

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

fun IntRange.random(random: Random): Int
fun LongRange.random(random: Random): Long
fun CharRange.random(random: Random): Char
fun UIntRange.random(random: Random): UInt
fun ULongRange.random(random: Random): ULong
Common
JVM
JS
Native
1.4

randomOrNull

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

fun IntRange.randomOrNull(): Int?
fun LongRange.randomOrNull(): Long?
fun CharRange.randomOrNull(): Char?
fun UIntRange.randomOrNull(): UInt?
fun ULongRange.randomOrNull(): ULong?

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

fun IntRange.randomOrNull(random: Random): Int?
fun LongRange.randomOrNull(random: Random): Long?
fun CharRange.randomOrNull(random: Random): Char?
fun UIntRange.randomOrNull(random: Random): UInt?
fun ULongRange.randomOrNull(random: Random): ULong?
Common
JVM
JS
Native
1.0

rangeTo

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

operator fun <T : Comparable<T>> T.rangeTo(
    that: T
): ClosedRange<T>

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

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

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

operator fun Float.rangeTo(
    that: Float
): ClosedFloatingPointRange<Float>
Common
JVM
JS
Native
1.9

rangeUntil

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

operator fun <T : Comparable<T>> T.rangeUntil(
    that: T
): OpenEndRange<T>

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

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

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

operator fun Float.rangeUntil(
    that: Float
): OpenEndRange<Float>
Common
JVM
JS
Native
1.0

reversed

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

Common
JVM
JS
Native
1.0

step

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

infix fun IntProgression.step(step: Int): IntProgression
infix fun LongProgression.step(step: Long): LongProgression
infix fun CharProgression.step(step: Int): CharProgression
infix fun UIntProgression.step(step: Int): UIntProgression
infix fun ULongProgression.step(step: Long): ULongProgression
Common
JVM
JS
Native
1.0

until

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

infix fun Int.until(to: Byte): IntRange
infix fun Long.until(to: Byte): LongRange
infix fun Byte.until(to: Byte): IntRange
infix fun Short.until(to: Byte): IntRange
infix fun Char.until(to: Char): CharRange
infix fun Int.until(to: Int): IntRange
infix fun Long.until(to: Int): LongRange
infix fun Byte.until(to: Int): IntRange
infix fun Short.until(to: Int): IntRange
infix fun Int.until(to: Long): LongRange
infix fun Long.until(to: Long): LongRange
infix fun Byte.until(to: Long): LongRange
infix fun Short.until(to: Long): LongRange
infix fun Int.until(to: Short): IntRange
infix fun Long.until(to: Short): LongRange
infix fun Byte.until(to: Short): IntRange
infix fun Short.until(to: Short): IntRange
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