diff --git a/libraries/stdlib/src/kotlin/random/Random.kt b/libraries/stdlib/src/kotlin/random/Random.kt index 2ae986f5f1f..fde28fec069 100644 --- a/libraries/stdlib/src/kotlin/random/Random.kt +++ b/libraries/stdlib/src/kotlin/random/Random.kt @@ -37,26 +37,26 @@ public abstract class Random { public open fun nextInt(): Int = nextBits(32) /** - * Gets the next random non-negative `Int` from the random number generator not greater than the specified [bound]. + * Gets the next random non-negative `Int` from the random number generator not greater than the specified [until]. * - * Generates an `Int` random value uniformly distributed between `0` (inclusive) and the specified [bound] (exclusive). + * Generates an `Int` random value uniformly distributed between `0` (inclusive) and the specified [until] (exclusive). * - * @param bound must be positive. + * @param until must be positive. * - * @throws IllegalArgumentException if [bound] is negative or zero. + * @throws IllegalArgumentException if [until] is negative or zero. */ - public open fun nextInt(bound: Int): Int = nextInt(0, bound) + public open fun nextInt(until: Int): Int = nextInt(0, until) /** * Gets the next random `Int` from the random number generator in the specified range. * - * Generates an `Int` random value uniformly distributed between the specified [origin] (inclusive) and the specified [bound] (exclusive). + * Generates an `Int` random value uniformly distributed between the specified [from] (inclusive) and the specified [until] (exclusive). * - * @throws IllegalArgumentException if [origin] is greater than or equal to [bound]. + * @throws IllegalArgumentException if [from] is greater than or equal to [until]. */ - public open fun nextInt(origin: Int, bound: Int): Int { - checkRangeBounds(origin, bound) - val n = bound - origin + public open fun nextInt(from: Int, until: Int): Int { + checkRangeBounds(from, until) + val n = until - from if (n > 0 || n == Int.MIN_VALUE) { val rnd = if (n and -n == n) { val bitCount = fastLog2(n) @@ -69,11 +69,11 @@ public abstract class Random { } while (bits - v + (n - 1) < 0) v } - return origin + rnd + return from + rnd } else { while (true) { val rnd = nextInt() - if (rnd in origin until bound) return rnd + if (rnd in from until until) return rnd } } } @@ -101,26 +101,26 @@ public abstract class Random { public open fun nextLong(): Long = nextInt().toLong().shl(32) + nextInt() /** - * Gets the next random non-negative `Long` from the random number generator not greater than the specified [bound]. + * Gets the next random non-negative `Long` from the random number generator not greater than the specified [until]. * - * Generates a `Long` random value uniformly distributed between `0` (inclusive) and the specified [bound] (exclusive). + * Generates a `Long` random value uniformly distributed between `0` (inclusive) and the specified [until] (exclusive). * - * @param bound must be positive. + * @param until must be positive. * - * @throws IllegalArgumentException if [bound] is negative or zero. + * @throws IllegalArgumentException if [until] is negative or zero. */ - public open fun nextLong(bound: Long): Long = nextLong(0, bound) + public open fun nextLong(until: Long): Long = nextLong(0, until) /** * Gets the next random `Long` from the random number generator in the specified range. * - * Generates a `Long` random value uniformly distributed between the specified [origin] (inclusive) and the specified [bound] (exclusive). + * Generates a `Long` random value uniformly distributed between the specified [from] (inclusive) and the specified [until] (exclusive). * - * @throws IllegalArgumentException if [origin] is greater than or equal to [bound]. + * @throws IllegalArgumentException if [from] is greater than or equal to [until]. */ - public open fun nextLong(origin: Long, bound: Long): Long { - checkRangeBounds(origin, bound) - val n = bound - origin + public open fun nextLong(from: Long, until: Long): Long { + checkRangeBounds(from, until) + val n = until - from if (n > 0) { val rnd: Long if (n and -n == n) { @@ -148,11 +148,11 @@ public abstract class Random { } while (bits - v + (n - 1) < 0) rnd = v } - return origin + rnd + return from + rnd } else { while (true) { val rnd = nextLong() - if (rnd in origin until bound) return rnd + if (rnd in from until until) return rnd } } } @@ -183,33 +183,33 @@ public abstract class Random { public open fun nextDouble(): Double = doubleFromParts(nextBits(26), nextBits(27)) /** - * Gets the next random non-negative `Double` from the random number generator not greater than the specified [bound]. + * Gets the next random non-negative `Double` from the random number generator not greater than the specified [until]. * - * Generates a `Double` random value uniformly distributed between 0 (inclusive) and [bound] (exclusive). + * Generates a `Double` random value uniformly distributed between 0 (inclusive) and [until] (exclusive). * - * @throws IllegalArgumentException if [bound] is negative or zero. + * @throws IllegalArgumentException if [until] is negative or zero. */ - public open fun nextDouble(bound: Double): Double = nextDouble(0.0, bound) + public open fun nextDouble(until: Double): Double = nextDouble(0.0, until) /** * Gets the next random `Double` from the random number generator in the specified range. * - * Generates a `Double` random value uniformly distributed between the specified [origin] (inclusive) and the specified [bound] (exclusive). + * Generates a `Double` random value uniformly distributed between the specified [from] (inclusive) and the specified [until] (exclusive). * - * [origin] and [bound] must be finite otherwise the behavior is unspecified. + * [from] and [until] must be finite otherwise the behavior is unspecified. * - * @throws IllegalArgumentException if [origin] is greater than or equal to [bound]. + * @throws IllegalArgumentException if [from] is greater than or equal to [until]. */ - public open fun nextDouble(origin: Double, bound: Double): Double { - checkRangeBounds(origin, bound) - val size = bound - origin - val r = if (size.isInfinite() && origin.isFinite() && bound.isFinite()) { - val r1 = nextDouble() * (bound / 2 - origin / 2) - origin + r1 + r1 + public open fun nextDouble(from: Double, until: Double): Double { + checkRangeBounds(from, until) + val size = until - from + val r = if (size.isInfinite() && from.isFinite() && until.isFinite()) { + val r1 = nextDouble() * (until / 2 - from / 2) + from + r1 + r1 } else { - origin + nextDouble() * size + from + nextDouble() * size } - return if (r >= bound) bound.nextDown() else r + return if (r >= until) until.nextDown() else r } /** @@ -274,20 +274,20 @@ public abstract class Random { override fun nextBits(bitCount: Int): Int = defaultRandom.nextBits(bitCount) override fun nextInt(): Int = defaultRandom.nextInt() - override fun nextInt(bound: Int): Int = defaultRandom.nextInt(bound) - override fun nextInt(origin: Int, bound: Int): Int = defaultRandom.nextInt(origin, bound) + override fun nextInt(until: Int): Int = defaultRandom.nextInt(until) + override fun nextInt(from: Int, until: Int): Int = defaultRandom.nextInt(from, until) override fun nextInt(range: IntRange): Int = defaultRandom.nextInt(range) override fun nextLong(): Long = defaultRandom.nextLong() - override fun nextLong(bound: Long): Long = defaultRandom.nextLong(bound) - override fun nextLong(origin: Long, bound: Long): Long = defaultRandom.nextLong(origin, bound) + override fun nextLong(until: Long): Long = defaultRandom.nextLong(until) + override fun nextLong(from: Long, until: Long): Long = defaultRandom.nextLong(from, until) override fun nextLong(range: LongRange): Long = defaultRandom.nextLong(range) override fun nextBoolean(): Boolean = defaultRandom.nextBoolean() override fun nextDouble(): Double = defaultRandom.nextDouble() - override fun nextDouble(bound: Double): Double = defaultRandom.nextDouble(bound) - override fun nextDouble(origin: Double, bound: Double): Double = defaultRandom.nextDouble(origin, bound) + override fun nextDouble(until: Double): Double = defaultRandom.nextDouble(until) + override fun nextDouble(from: Double, until: Double): Double = defaultRandom.nextDouble(from, until) override fun nextFloat(): Float = defaultRandom.nextFloat() @@ -331,30 +331,30 @@ public fun Random(seed: Long): Random = XorWowRandom(seed.toInt(), seed.shr(32). public fun Random.nextUInt(): UInt = nextInt().toUInt() /** - * Gets the next random [UInt] from the random number generator not greater than the specified [bound]. + * Gets the next random [UInt] from the random number generator not greater than the specified [until]. * - * Generates a [UInt] random value uniformly distributed between `0` (inclusive) and the specified [bound] (exclusive). + * Generates a [UInt] random value uniformly distributed between `0` (inclusive) and the specified [until] (exclusive). * - * @throws IllegalArgumentException if [bound] is zero. + * @throws IllegalArgumentException if [until] is zero. */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes -public fun Random.nextUInt(bound: UInt): UInt = nextUInt(0u, bound) +public fun Random.nextUInt(until: UInt): UInt = nextUInt(0u, until) /** * Gets the next random [UInt] from the random number generator in the specified range. * - * Generates a [UInt] random value uniformly distributed between the specified [origin] (inclusive) and the specified [bound] (exclusive). + * Generates a [UInt] random value uniformly distributed between the specified [from] (inclusive) and the specified [until] (exclusive). * - * @throws IllegalArgumentException if [origin] is greater than or equal to [bound]. + * @throws IllegalArgumentException if [from] is greater than or equal to [until]. */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes -public fun Random.nextUInt(origin: UInt, bound: UInt): UInt { - checkUIntRangeBounds(origin, bound) +public fun Random.nextUInt(from: UInt, until: UInt): UInt { + checkUIntRangeBounds(from, until) - val originTransformedToInt = origin.toInt() xor Int.MIN_VALUE - val boundTransformedToInt = bound.toInt() xor Int.MIN_VALUE + val originTransformedToInt = from.toInt() xor Int.MIN_VALUE + val boundTransformedToInt = until.toInt() xor Int.MIN_VALUE val randomValueTransformedBack = nextInt(originTransformedToInt, boundTransformedToInt) xor Int.MIN_VALUE @@ -388,30 +388,30 @@ public fun Random.nextUInt(range: UIntRange): UInt = when { public fun Random.nextULong(): ULong = nextLong().toULong() /** - * Gets the next random [ULong] from the random number generator not greater than the specified [bound]. + * Gets the next random [ULong] from the random number generator not greater than the specified [until]. * - * Generates a [ULong] random value uniformly distributed between `0` (inclusive) and the specified [bound] (exclusive). + * Generates a [ULong] random value uniformly distributed between `0` (inclusive) and the specified [until] (exclusive). * - * @throws IllegalArgumentException if [bound] is zero. + * @throws IllegalArgumentException if [until] is zero. */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes -public fun Random.nextULong(bound: ULong): ULong = nextULong(0uL, bound) +public fun Random.nextULong(until: ULong): ULong = nextULong(0uL, until) /** * Gets the next random [ULong] from the random number generator in the specified range. * - * Generates a [ULong] random value uniformly distributed between the specified [origin] (inclusive) and the specified [bound] (exclusive). + * Generates a [ULong] random value uniformly distributed between the specified [from] (inclusive) and the specified [until] (exclusive). * - * @throws IllegalArgumentException if [origin] is greater than or equal to [bound]. + * @throws IllegalArgumentException if [from] is greater than or equal to [until]. */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes -public fun Random.nextULong(origin: ULong, bound: ULong): ULong { - checkULongRangeBounds(origin, bound) +public fun Random.nextULong(from: ULong, until: ULong): ULong { + checkULongRangeBounds(from, until) - val originTransformedToLong = origin.toLong() xor Long.MIN_VALUE - val boundTransformedToLong = bound.toLong() xor Long.MIN_VALUE + val originTransformedToLong = from.toLong() xor Long.MIN_VALUE + val boundTransformedToLong = until.toLong() xor Long.MIN_VALUE val randomValueTransformedBack = nextLong(originTransformedToLong, boundTransformedToLong) xor Long.MIN_VALUE return randomValueTransformedBack.toULong() diff --git a/libraries/stdlib/test/random/RandomTest.kt b/libraries/stdlib/test/random/RandomTest.kt index 41d98e3e7e9..338f3076885 100644 --- a/libraries/stdlib/test/random/RandomTest.kt +++ b/libraries/stdlib/test/random/RandomTest.kt @@ -64,7 +64,7 @@ abstract class RandomSmokeTest { } @Test - fun nextIntBound() { + fun nextIntUntil() { assertFailsWith { subject.nextInt(0) } assertFailsWith { subject.nextInt(-1) } assertFailsWith { subject.nextInt(Int.MIN_VALUE) } @@ -83,7 +83,7 @@ abstract class RandomSmokeTest { } @Test - fun nextUIntBound() { + fun nextUIntUntil() { assertFailsWith { subject.nextUInt(UInt.MIN_VALUE) } repeat(1000) { @@ -100,7 +100,7 @@ abstract class RandomSmokeTest { } @Test - fun nextIntOriginBound() { + fun nextIntFromUntil() { assertFailsWith { subject.nextInt(0, 0) } assertFailsWith { subject.nextInt(-1, -2) } assertFailsWith { subject.nextInt(Int.MIN_VALUE, Int.MIN_VALUE) } @@ -122,7 +122,7 @@ abstract class RandomSmokeTest { } @Test - fun nextUIntOriginBound() { + fun nextUIntFromUntil() { assertFailsWith { subject.nextUInt(0u, 0u) } assertFailsWith { subject.nextUInt((-1).toUInt(), (-2).toUInt()) } assertFailsWith { subject.nextUInt(UInt.MIN_VALUE, UInt.MIN_VALUE) } @@ -219,7 +219,7 @@ abstract class RandomSmokeTest { } @Test - fun nextLongBound() { + fun nextLongUntil() { assertFailsWith { subject.nextLong(0) } assertFailsWith { subject.nextLong(-1) } assertFailsWith { subject.nextLong(Long.MIN_VALUE) } @@ -238,7 +238,7 @@ abstract class RandomSmokeTest { } @Test - fun nextULongBound() { + fun nextULongUntil() { assertFailsWith { subject.nextULong(ULong.MIN_VALUE) } repeat(1000) { @@ -256,7 +256,7 @@ abstract class RandomSmokeTest { } @Test - fun nextLongOriginBound() { + fun nextLongFromUntil() { assertFailsWith { subject.nextLong(0, 0) } assertFailsWith { subject.nextLong(-1, -2) } assertFailsWith { subject.nextLong(Long.MIN_VALUE, Long.MIN_VALUE) } @@ -277,7 +277,7 @@ abstract class RandomSmokeTest { } @Test - fun nextULongOriginBound() { + fun nextULongFromUntil() { assertFailsWith { subject.nextULong(0uL, 0uL) } assertFailsWith { subject.nextULong((-1).toULong(), (-2).toULong()) } @@ -364,7 +364,7 @@ abstract class RandomSmokeTest { } @Test - fun nextDoubleBound() { + fun nextDoubleUntil() { assertFailsWith { subject.nextDouble(-1.0) } assertFailsWith { subject.nextDouble(-0.0) } assertFailsWith { subject.nextDouble(0.0) } @@ -387,7 +387,7 @@ abstract class RandomSmokeTest { } @Test - fun nextDoubleOriginBound() { + fun nextDoubleFromUntil() { assertFailsWith { subject.nextDouble(0.0, -1.0) } assertFailsWith { subject.nextDouble(0.0, Double.NaN) } assertFailsWith { subject.nextDouble(Double.NaN, 0.0) }