kotlin-stdlib / kotlin.ranges / coerceIn

coerceIn

Common
JVM
JS
Native
1.0
fun <T : Comparable<T>> T.coerceIn(
    minimumValue: T?,
    maximumValue: T?
): T

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

import java.time.DayOfWeek
import kotlin.test.assertFailsWith

fun main(args: Array<String>) {
//sampleStart
val workingDays = DayOfWeek.MONDAY..DayOfWeek.FRIDAY
println(DayOfWeek.WEDNESDAY.coerceIn(workingDays)) // WEDNESDAY
println(DayOfWeek.SATURDAY.coerceIn(workingDays)) // FRIDAY

println(DayOfWeek.FRIDAY.coerceIn(DayOfWeek.SATURDAY, DayOfWeek.SUNDAY)) // SATURDAY
//sampleEnd
}

Return this value if it's in the range, or minimumValue if this value is less than minimumValue, or maximumValue if this value is greater than maximumValue.

Common
JVM
JS
Native
1.0
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

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

import java.time.DayOfWeek
import kotlin.test.assertFailsWith

fun main(args: Array<String>) {
//sampleStart
println(10.coerceIn(1, 100)) // 10
println(10.coerceIn(1..100)) // 10
println(0.coerceIn(1, 100)) // 1
println(500.coerceIn(1, 100)) // 100
// 10.coerceIn(100, 0) // will fail with IllegalArgumentException
//sampleEnd
}

Return this value if it's in the range, or minimumValue if this value is less than minimumValue, or maximumValue if this value is greater than maximumValue.

Common
JVM
JS
Native
1.1
fun <T : Comparable<T>> T.coerceIn(
    range: ClosedFloatingPointRange<T>
): T

Ensures that this value lies in the specified range.

import java.time.DayOfWeek
import kotlin.test.assertFailsWith

fun main(args: Array<String>) {
//sampleStart
println(10.1.coerceIn(1.0..10.0)) // 10.0
println(9.9.coerceIn(1.0..10.0)) // 9.9

// 9.9.coerceIn(1.0..Double.NaN) // will fail with IllegalArgumentException
//sampleEnd
}

Return this value if it's in the range, or range.start if this value is less than range.start, or range.endInclusive if this value is greater than range.endInclusive.

Common
JVM
JS
Native
1.0
fun <T : Comparable<T>> T.coerceIn(range: ClosedRange<T>): T

Ensures that this value lies in the specified range.

import java.time.DayOfWeek
import kotlin.test.assertFailsWith

fun main(args: Array<String>) {
//sampleStart
val workingDays = DayOfWeek.MONDAY..DayOfWeek.FRIDAY
println(DayOfWeek.WEDNESDAY.coerceIn(workingDays)) // WEDNESDAY
println(DayOfWeek.SATURDAY.coerceIn(workingDays)) // FRIDAY

println(DayOfWeek.FRIDAY.coerceIn(DayOfWeek.SATURDAY, DayOfWeek.SUNDAY)) // SATURDAY
//sampleEnd
}

Return this value if it's in the range, or range.start if this value is less than range.start, or range.endInclusive if this value is greater than range.endInclusive.

Common
JVM
JS
Native
1.0
fun Int.coerceIn(range: ClosedRange<Int>): Int
fun Long.coerceIn(range: ClosedRange<Long>): Long

Ensures that this value lies in the specified range.

import java.time.DayOfWeek
import kotlin.test.assertFailsWith

fun main(args: Array<String>) {
//sampleStart
println(10.coerceIn(1, 100)) // 10
println(10.coerceIn(1..100)) // 10
println(0.coerceIn(1, 100)) // 1
println(500.coerceIn(1, 100)) // 100
// 10.coerceIn(100, 0) // will fail with IllegalArgumentException
//sampleEnd
}

Return this value if it's in the range, or range.start if this value is less than range.start, or range.endInclusive if this value is greater than range.endInclusive.

Common
JVM
JS
Native
1.3
@ExperimentalUnsignedTypes fun UInt.coerceIn(
    minimumValue: UInt,
    maximumValue: UInt
): UInt
@ExperimentalUnsignedTypes fun ULong.coerceIn(
    minimumValue: ULong,
    maximumValue: ULong
): ULong
@ExperimentalUnsignedTypes fun UByte.coerceIn(
    minimumValue: UByte,
    maximumValue: UByte
): UByte
@ExperimentalUnsignedTypes fun UShort.coerceIn(
    minimumValue: UShort,
    maximumValue: UShort
): UShort

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

import java.time.DayOfWeek
import kotlin.test.assertFailsWith

fun main(args: Array<String>) {
//sampleStart
println(10u.coerceIn(1u, 100u)) // 10
println(10u.coerceIn(1u..100u)) // 10
println(0u.coerceIn(1u, 100u)) // 1
println(500u.coerceIn(1u, 100u)) // 100
// 10u.coerceIn(100u, 0u) // will fail with IllegalArgumentException
//sampleEnd
}

Return this value if it's in the range, or minimumValue if this value is less than minimumValue, or maximumValue if this value is greater than maximumValue.

Common
JVM
JS
Native
1.3
@ExperimentalUnsignedTypes fun UInt.coerceIn(
    range: ClosedRange<UInt>
): UInt
@ExperimentalUnsignedTypes fun ULong.coerceIn(
    range: ClosedRange<ULong>
): ULong

Ensures that this value lies in the specified range.

import java.time.DayOfWeek
import kotlin.test.assertFailsWith

fun main(args: Array<String>) {
//sampleStart
println(10u.coerceIn(1u, 100u)) // 10
println(10u.coerceIn(1u..100u)) // 10
println(0u.coerceIn(1u, 100u)) // 1
println(500u.coerceIn(1u, 100u)) // 100
// 10u.coerceIn(100u, 0u) // will fail with IllegalArgumentException
//sampleEnd
}

Return this value if it's in the range, or range.start if this value is less than range.start, or range.endInclusive if this value is greater than range.endInclusive.