diff --git a/libraries/stdlib/samples/test/samples/collections/collections.kt b/libraries/stdlib/samples/test/samples/collections/collections.kt new file mode 100644 index 00000000000..5ae32fe755a --- /dev/null +++ b/libraries/stdlib/samples/test/samples/collections/collections.kt @@ -0,0 +1,62 @@ +/* + * Copyright 2010-2016 JetBrains s.r.o. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package samples.collections + +import samples.* +import kotlin.test.* +import java.util.* + + +@RunWith(Enclosed::class) +class Collections { + + class Lists { + @Sample + fun lastIndexOfList() { + assertPrints(emptyList().lastIndex, "-1") + assertPrints(listOf("a", "x", "y").lastIndex, "2") + } + } + + class Transformations { + + @Sample + fun groupBy() { + val words = listOf("a", "abc", "ab", "def", "abcd") + val byLength = words.groupBy { it.length } + + assertPrints(byLength.keys, "[1, 3, 2, 4]") + assertPrints(byLength.values, "[[a], [abc, def], [ab], [abcd]]") + + val mutableByLength: MutableMap> = words.groupByTo(mutableMapOf()) { it.length } + // same content as in byLength map, but the map is mutable + assertTrue(mutableByLength == byLength) + } + + @Sample + fun groupByKeysAndValues() { + val nameToTeam = listOf("Alice" to "Marketing", "Bob" to "Sales", "Carol" to "Marketing") + val namesByTeam = nameToTeam.groupBy({ it.second }, { it.first }) + assertPrints(namesByTeam, "{Marketing=[Alice, Carol], Sales=[Bob]}") + + val mutableNamesByTeam = nameToTeam.groupByTo(HashMap(), { it.second }, { it.first }) + // same content as in namesByTeam map, but the map is mutable + assertTrue(mutableNamesByTeam == namesByTeam) + } + } + +} \ No newline at end of file diff --git a/libraries/stdlib/samples/test/samples/collections/maps.kt b/libraries/stdlib/samples/test/samples/collections/maps.kt new file mode 100644 index 00000000000..c2317a37a80 --- /dev/null +++ b/libraries/stdlib/samples/test/samples/collections/maps.kt @@ -0,0 +1,156 @@ +package samples.collections + +import samples.* +import kotlin.test.* +import java.util.* +import kotlin.comparisons.* + +@RunWith(Enclosed::class) +class Maps { + + class Instantiation { + + @Sample + fun mapFromPairs() { + val map = mapOf(1 to "x", 2 to "y", -1 to "zz") + assertPrints(map, "{1=x, 2=y, -1=zz}") + } + + @Sample + fun mutableMapFromPairs() { + val map = mutableMapOf(1 to "x", 2 to "y", -1 to "zz") + assertPrints(map, "{1=x, 2=y, -1=zz}") + + map[1] = "a" + assertPrints(map, "{1=a, 2=y, -1=zz}") + } + + @Sample + fun hashMapFromPairs() { + val map: HashMap = hashMapOf(1 to "x", 2 to "y", -1 to "zz") + assertPrints(map, "{-1=zz, 1=x, 2=y}") + } + + @Sample + fun linkedMapFromPairs() { + val map: LinkedHashMap = linkedMapOf(1 to "x", 2 to "y", -1 to "zz") + assertPrints(map, "{1=x, 2=y, -1=zz}") + } + + @Sample + fun sortedMapFromPairs() { + val map = sortedMapOf(Pair("c", 3), Pair("b", 2), Pair("d", 1)) + assertPrints(map.keys, "[b, c, d]") + assertPrints(map.values, "[2, 3, 1]") + } + + @Sample + fun emptyReadOnlyMap() { + val map = emptyMap() + assertTrue(map.isEmpty()) + + val anotherMap = mapOf() + assertTrue(map == anotherMap, "Empty maps are equal") + } + + @Sample + fun emptyMutableMap() { + val map = mutableMapOf() + assertTrue(map.isEmpty()) + + map[1] = "x" + map[2] = 1.05 + // Now map contains something: + assertPrints(map, "{1=x, 2=1.05}") + } + + } + + + class Usage { + + @Sample + fun getOrElse() { + val map = mutableMapOf() + assertPrints(map.getOrElse("x") { 1 }, "1") + + map["x"] = 3 + assertPrints(map.getOrElse("x") { 1 }, "3") + + map["x"] = null + assertPrints(map.getOrElse("x") { 1 }, "1") + } + + @Sample + fun getOrPut() { + val map = mutableMapOf() + assertPrints(map.getOrPut("x") { 2 }, "2") + assertPrints(map.getOrPut("x") { 3 }, "2") // still + + assertPrints(map.getOrPut("y") { null }, "null") + assertPrints(map.getOrPut("y") { 42 }, "42") // but! + } + + @Sample + fun forOverEntries() { + val map = mapOf("beverage" to 2.7, "meal" to 12.4, "dessert" to 5.8) + + for ((key, value) in map) { + println("$key - $value") // prints: beverage - 2.7 + // prints: meal - 12.4 + // prints: dessert - 5.8 + } + + } + } + + class Transformations { + + @Sample + fun mapKeys() { + val map1 = mapOf("beer" to 2.7, "bisquit" to 5.8) + val map2 = map1.mapKeys { it.key.length } + assertPrints(map2, "{4=2.7, 7=5.8}") + + val map3 = map1.mapKeys { it.key.take(1) } + assertPrints(map3, "{b=5.8}") + } + + @Sample + fun mapValues() { + val map1 = mapOf("beverage" to 2.7, "meal" to 12.4) + val map2 = map1.mapValues { it.value.toString() + "$" } + + assertPrints(map2, "{beverage=2.7$, meal=12.4$}") + } + + + @Sample + fun mapToSortedMap() { + val map = mapOf(Pair("c", 3), Pair("b", 2), Pair("d", 1)) + val sorted = map.toSortedMap() + assertPrints(sorted.keys, "[b, c, d]") + assertPrints(sorted.values, "[2, 3, 1]") + } + + @Sample + fun mapToSortedMapWithComparator() { + val map = mapOf(Pair("abc", 1), Pair("c", 3), Pair("bd", 4), Pair("bc", 2)) + val sorted = map.toSortedMap(compareBy { it.length }.thenBy { it }) + assertPrints(sorted.keys, "[c, bc, bd, abc]") + } + + @Sample + fun mapToProperties() { + val map = mapOf("x" to "value A", "y" to "value B") + val props = map.toProperties() + + assertPrints(props.getProperty("x"), "value A") + assertPrints(props.getProperty("y", "fail"), "value B") + assertPrints(props.getProperty("z", "fail"), "fail") + } + + } + +} + diff --git a/libraries/stdlib/samples/test/samples/misc/preconditions.kt b/libraries/stdlib/samples/test/samples/misc/preconditions.kt new file mode 100644 index 00000000000..f38cc4eaeba --- /dev/null +++ b/libraries/stdlib/samples/test/samples/misc/preconditions.kt @@ -0,0 +1,55 @@ +package samples.misc + +import samples.* +import kotlin.test.* + +class Preconditions { + + @Sample + fun failWithError() { + val name: String? = null + + val exception = assertFailsWith { + val nonNullName = name ?: error("Name is missing") + } + + assertPrints(exception.message, "Name is missing") + } + + @Sample + fun failRequireWithLazyMessage() { + + fun getIndices(count: Int) { + require(count >= 0) { "Count must be non-negative, was $count" } + // ... + } + + val exception = assertFailsWith { + getIndices(-1) + } + assertPrints(exception.message, "Count must be non-negative, was -1") + } + + @Sample + fun failCheckWithLazyMessage() { + + var someState: String? = null + fun getStateValue(): String { + val state = checkNotNull(someState) { "State must be set beforehand" } + check(state.isNotEmpty()) { "State must be non-empty" } + // ... + return state + } + + assertFailsWith { + getStateValue() + } + + assertFailsWith { + someState = "" + getStateValue() + }.let { exception -> + assertPrints(exception.message, "State must be non-empty") + } + } +} diff --git a/libraries/stdlib/samples/test/samples/misc/tuples.kt b/libraries/stdlib/samples/test/samples/misc/tuples.kt new file mode 100644 index 00000000000..7cd03c4d38b --- /dev/null +++ b/libraries/stdlib/samples/test/samples/misc/tuples.kt @@ -0,0 +1,23 @@ +package samples.misc + +import samples.* +import kotlin.test.* + +class Tuples { + + @Sample + fun pairDestructuring() { + val (a, b) = Pair(1, "x") + assertPrints(a, "1") + assertPrints(b, "x") + } + + @Sample + fun tripleDestructuring() { + val (a, b, c) = Triple(2, "x", listOf(null)) + assertPrints(a, "2") + assertPrints(b, "x") + assertPrints(c, "[null]") + } + +} \ No newline at end of file diff --git a/libraries/stdlib/samples/test/samples/text/regex.kt b/libraries/stdlib/samples/test/samples/text/regex.kt new file mode 100644 index 00000000000..6dca16b17d8 --- /dev/null +++ b/libraries/stdlib/samples/test/samples/text/regex.kt @@ -0,0 +1,23 @@ +package samples.text + +import samples.* +import kotlin.test.* +import java.util.* + +class Regexps { + + @Sample + fun matchDestructuringToGroupValues() { + val inputString = "John 9731879" + val match = Regex("(\\w+) (\\d+)").find(inputString)!! + val (name, phone) = match.destructured + + assertPrints(name, "John") + assertPrints(phone, "9731879") + + assertPrints(match.groupValues, "[John 9731879, John, 9731879]") + + val numberedGroupValues = match.destructured.toList() + assertPrints(numberedGroupValues, "[John, 9731879]") + } +} \ No newline at end of file diff --git a/libraries/stdlib/samples/test/samples/text/strings.kt b/libraries/stdlib/samples/test/samples/text/strings.kt new file mode 100644 index 00000000000..4314bfa3b93 --- /dev/null +++ b/libraries/stdlib/samples/test/samples/text/strings.kt @@ -0,0 +1,27 @@ +package samples.text + +import samples.* +import kotlin.test.* +import java.util.* + +class Strings { + + @Sample + fun capitalize() { + assertPrints("abcd".capitalize(), "Abcd") + assertPrints("Abcd".capitalize(), "Abcd") + } + + @Sample + fun decaptialize() { + assertPrints("abcd".decapitalize(), "abcd") + assertPrints("Abcd".decapitalize(), "abcd") + } + + @Sample + fun repeat() { + assertPrints("Word".repeat(4), "WordWordWordWord") + assertPrints("Word".repeat(0), "") + } + +} \ No newline at end of file diff --git a/libraries/stdlib/src/generated/_Arrays.kt b/libraries/stdlib/src/generated/_Arrays.kt index 8f67d8721bc..2f67282e918 100644 --- a/libraries/stdlib/src/generated/_Arrays.kt +++ b/libraries/stdlib/src/generated/_Arrays.kt @@ -7235,7 +7235,7 @@ public inline fun > CharArray.flatMapTo(destinati * * The returned map preserves the entry iteration order of the keys produced from the original array. * - * @sample test.collections.CollectionTest.groupBy + * @sample samples.collections.Collections.Transformations.groupBy */ public inline fun Array.groupBy(keySelector: (T) -> K): Map> { return groupByTo(LinkedHashMap>(), keySelector) @@ -7247,7 +7247,7 @@ public inline fun Array.groupBy(keySelector: (T) -> K): Map ByteArray.groupBy(keySelector: (Byte) -> K): Map> { return groupByTo(LinkedHashMap>(), keySelector) @@ -7259,7 +7259,7 @@ public inline fun ByteArray.groupBy(keySelector: (Byte) -> K): Map ShortArray.groupBy(keySelector: (Short) -> K): Map> { return groupByTo(LinkedHashMap>(), keySelector) @@ -7271,7 +7271,7 @@ public inline fun ShortArray.groupBy(keySelector: (Short) -> K): Map IntArray.groupBy(keySelector: (Int) -> K): Map> { return groupByTo(LinkedHashMap>(), keySelector) @@ -7283,7 +7283,7 @@ public inline fun IntArray.groupBy(keySelector: (Int) -> K): Map LongArray.groupBy(keySelector: (Long) -> K): Map> { return groupByTo(LinkedHashMap>(), keySelector) @@ -7295,7 +7295,7 @@ public inline fun LongArray.groupBy(keySelector: (Long) -> K): Map FloatArray.groupBy(keySelector: (Float) -> K): Map> { return groupByTo(LinkedHashMap>(), keySelector) @@ -7307,7 +7307,7 @@ public inline fun FloatArray.groupBy(keySelector: (Float) -> K): Map DoubleArray.groupBy(keySelector: (Double) -> K): Map> { return groupByTo(LinkedHashMap>(), keySelector) @@ -7319,7 +7319,7 @@ public inline fun DoubleArray.groupBy(keySelector: (Double) -> K): Map BooleanArray.groupBy(keySelector: (Boolean) -> K): Map> { return groupByTo(LinkedHashMap>(), keySelector) @@ -7331,7 +7331,7 @@ public inline fun BooleanArray.groupBy(keySelector: (Boolean) -> K): Map CharArray.groupBy(keySelector: (Char) -> K): Map> { return groupByTo(LinkedHashMap>(), keySelector) @@ -7344,7 +7344,7 @@ public inline fun CharArray.groupBy(keySelector: (Char) -> K): Map Array.groupBy(keySelector: (T) -> K, valueTransform: (T) -> V): Map> { return groupByTo(LinkedHashMap>(), keySelector, valueTransform) @@ -7357,7 +7357,7 @@ public inline fun Array.groupBy(keySelector: (T) -> K, valueTra * * The returned map preserves the entry iteration order of the keys produced from the original array. * - * @sample test.collections.CollectionTest.groupByKeysAndValues + * @sample samples.collections.Collections.Transformations.groupByKeysAndValues */ public inline fun ByteArray.groupBy(keySelector: (Byte) -> K, valueTransform: (Byte) -> V): Map> { return groupByTo(LinkedHashMap>(), keySelector, valueTransform) @@ -7370,7 +7370,7 @@ public inline fun ByteArray.groupBy(keySelector: (Byte) -> K, valueTransf * * The returned map preserves the entry iteration order of the keys produced from the original array. * - * @sample test.collections.CollectionTest.groupByKeysAndValues + * @sample samples.collections.Collections.Transformations.groupByKeysAndValues */ public inline fun ShortArray.groupBy(keySelector: (Short) -> K, valueTransform: (Short) -> V): Map> { return groupByTo(LinkedHashMap>(), keySelector, valueTransform) @@ -7383,7 +7383,7 @@ public inline fun ShortArray.groupBy(keySelector: (Short) -> K, valueTran * * The returned map preserves the entry iteration order of the keys produced from the original array. * - * @sample test.collections.CollectionTest.groupByKeysAndValues + * @sample samples.collections.Collections.Transformations.groupByKeysAndValues */ public inline fun IntArray.groupBy(keySelector: (Int) -> K, valueTransform: (Int) -> V): Map> { return groupByTo(LinkedHashMap>(), keySelector, valueTransform) @@ -7396,7 +7396,7 @@ public inline fun IntArray.groupBy(keySelector: (Int) -> K, valueTransfor * * The returned map preserves the entry iteration order of the keys produced from the original array. * - * @sample test.collections.CollectionTest.groupByKeysAndValues + * @sample samples.collections.Collections.Transformations.groupByKeysAndValues */ public inline fun LongArray.groupBy(keySelector: (Long) -> K, valueTransform: (Long) -> V): Map> { return groupByTo(LinkedHashMap>(), keySelector, valueTransform) @@ -7409,7 +7409,7 @@ public inline fun LongArray.groupBy(keySelector: (Long) -> K, valueTransf * * The returned map preserves the entry iteration order of the keys produced from the original array. * - * @sample test.collections.CollectionTest.groupByKeysAndValues + * @sample samples.collections.Collections.Transformations.groupByKeysAndValues */ public inline fun FloatArray.groupBy(keySelector: (Float) -> K, valueTransform: (Float) -> V): Map> { return groupByTo(LinkedHashMap>(), keySelector, valueTransform) @@ -7422,7 +7422,7 @@ public inline fun FloatArray.groupBy(keySelector: (Float) -> K, valueTran * * The returned map preserves the entry iteration order of the keys produced from the original array. * - * @sample test.collections.CollectionTest.groupByKeysAndValues + * @sample samples.collections.Collections.Transformations.groupByKeysAndValues */ public inline fun DoubleArray.groupBy(keySelector: (Double) -> K, valueTransform: (Double) -> V): Map> { return groupByTo(LinkedHashMap>(), keySelector, valueTransform) @@ -7435,7 +7435,7 @@ public inline fun DoubleArray.groupBy(keySelector: (Double) -> K, valueTr * * The returned map preserves the entry iteration order of the keys produced from the original array. * - * @sample test.collections.CollectionTest.groupByKeysAndValues + * @sample samples.collections.Collections.Transformations.groupByKeysAndValues */ public inline fun BooleanArray.groupBy(keySelector: (Boolean) -> K, valueTransform: (Boolean) -> V): Map> { return groupByTo(LinkedHashMap>(), keySelector, valueTransform) @@ -7448,7 +7448,7 @@ public inline fun BooleanArray.groupBy(keySelector: (Boolean) -> K, value * * The returned map preserves the entry iteration order of the keys produced from the original array. * - * @sample test.collections.CollectionTest.groupByKeysAndValues + * @sample samples.collections.Collections.Transformations.groupByKeysAndValues */ public inline fun CharArray.groupBy(keySelector: (Char) -> K, valueTransform: (Char) -> V): Map> { return groupByTo(LinkedHashMap>(), keySelector, valueTransform) @@ -7460,7 +7460,7 @@ public inline fun CharArray.groupBy(keySelector: (Char) -> K, valueTransf * * @return The [destination] map. * - * @sample test.collections.CollectionTest.groupBy + * @sample samples.collections.Collections.Transformations.groupBy */ public inline fun >> Array.groupByTo(destination: M, keySelector: (T) -> K): M { for (element in this) { @@ -7477,7 +7477,7 @@ public inline fun >> Array.grou * * @return The [destination] map. * - * @sample test.collections.CollectionTest.groupBy + * @sample samples.collections.Collections.Transformations.groupBy */ public inline fun >> ByteArray.groupByTo(destination: M, keySelector: (Byte) -> K): M { for (element in this) { @@ -7494,7 +7494,7 @@ public inline fun >> ByteArray.groupBy * * @return The [destination] map. * - * @sample test.collections.CollectionTest.groupBy + * @sample samples.collections.Collections.Transformations.groupBy */ public inline fun >> ShortArray.groupByTo(destination: M, keySelector: (Short) -> K): M { for (element in this) { @@ -7511,7 +7511,7 @@ public inline fun >> ShortArray.group * * @return The [destination] map. * - * @sample test.collections.CollectionTest.groupBy + * @sample samples.collections.Collections.Transformations.groupBy */ public inline fun >> IntArray.groupByTo(destination: M, keySelector: (Int) -> K): M { for (element in this) { @@ -7528,7 +7528,7 @@ public inline fun >> IntArray.groupByTo * * @return The [destination] map. * - * @sample test.collections.CollectionTest.groupBy + * @sample samples.collections.Collections.Transformations.groupBy */ public inline fun >> LongArray.groupByTo(destination: M, keySelector: (Long) -> K): M { for (element in this) { @@ -7545,7 +7545,7 @@ public inline fun >> LongArray.groupBy * * @return The [destination] map. * - * @sample test.collections.CollectionTest.groupBy + * @sample samples.collections.Collections.Transformations.groupBy */ public inline fun >> FloatArray.groupByTo(destination: M, keySelector: (Float) -> K): M { for (element in this) { @@ -7562,7 +7562,7 @@ public inline fun >> FloatArray.group * * @return The [destination] map. * - * @sample test.collections.CollectionTest.groupBy + * @sample samples.collections.Collections.Transformations.groupBy */ public inline fun >> DoubleArray.groupByTo(destination: M, keySelector: (Double) -> K): M { for (element in this) { @@ -7579,7 +7579,7 @@ public inline fun >> DoubleArray.gro * * @return The [destination] map. * - * @sample test.collections.CollectionTest.groupBy + * @sample samples.collections.Collections.Transformations.groupBy */ public inline fun >> BooleanArray.groupByTo(destination: M, keySelector: (Boolean) -> K): M { for (element in this) { @@ -7596,7 +7596,7 @@ public inline fun >> BooleanArray.g * * @return The [destination] map. * - * @sample test.collections.CollectionTest.groupBy + * @sample samples.collections.Collections.Transformations.groupBy */ public inline fun >> CharArray.groupByTo(destination: M, keySelector: (Char) -> K): M { for (element in this) { @@ -7614,7 +7614,7 @@ public inline fun >> CharArray.groupBy * * @return The [destination] map. * - * @sample test.collections.CollectionTest.groupByKeysAndValues + * @sample samples.collections.Collections.Transformations.groupByKeysAndValues */ public inline fun >> Array.groupByTo(destination: M, keySelector: (T) -> K, valueTransform: (T) -> V): M { for (element in this) { @@ -7632,7 +7632,7 @@ public inline fun >> Array.g * * @return The [destination] map. * - * @sample test.collections.CollectionTest.groupByKeysAndValues + * @sample samples.collections.Collections.Transformations.groupByKeysAndValues */ public inline fun >> ByteArray.groupByTo(destination: M, keySelector: (Byte) -> K, valueTransform: (Byte) -> V): M { for (element in this) { @@ -7650,7 +7650,7 @@ public inline fun >> ByteArray.groupBy * * @return The [destination] map. * - * @sample test.collections.CollectionTest.groupByKeysAndValues + * @sample samples.collections.Collections.Transformations.groupByKeysAndValues */ public inline fun >> ShortArray.groupByTo(destination: M, keySelector: (Short) -> K, valueTransform: (Short) -> V): M { for (element in this) { @@ -7668,7 +7668,7 @@ public inline fun >> ShortArray.groupB * * @return The [destination] map. * - * @sample test.collections.CollectionTest.groupByKeysAndValues + * @sample samples.collections.Collections.Transformations.groupByKeysAndValues */ public inline fun >> IntArray.groupByTo(destination: M, keySelector: (Int) -> K, valueTransform: (Int) -> V): M { for (element in this) { @@ -7686,7 +7686,7 @@ public inline fun >> IntArray.groupByT * * @return The [destination] map. * - * @sample test.collections.CollectionTest.groupByKeysAndValues + * @sample samples.collections.Collections.Transformations.groupByKeysAndValues */ public inline fun >> LongArray.groupByTo(destination: M, keySelector: (Long) -> K, valueTransform: (Long) -> V): M { for (element in this) { @@ -7704,7 +7704,7 @@ public inline fun >> LongArray.groupBy * * @return The [destination] map. * - * @sample test.collections.CollectionTest.groupByKeysAndValues + * @sample samples.collections.Collections.Transformations.groupByKeysAndValues */ public inline fun >> FloatArray.groupByTo(destination: M, keySelector: (Float) -> K, valueTransform: (Float) -> V): M { for (element in this) { @@ -7722,7 +7722,7 @@ public inline fun >> FloatArray.groupB * * @return The [destination] map. * - * @sample test.collections.CollectionTest.groupByKeysAndValues + * @sample samples.collections.Collections.Transformations.groupByKeysAndValues */ public inline fun >> DoubleArray.groupByTo(destination: M, keySelector: (Double) -> K, valueTransform: (Double) -> V): M { for (element in this) { @@ -7740,7 +7740,7 @@ public inline fun >> DoubleArray.group * * @return The [destination] map. * - * @sample test.collections.CollectionTest.groupByKeysAndValues + * @sample samples.collections.Collections.Transformations.groupByKeysAndValues */ public inline fun >> BooleanArray.groupByTo(destination: M, keySelector: (Boolean) -> K, valueTransform: (Boolean) -> V): M { for (element in this) { @@ -7758,7 +7758,7 @@ public inline fun >> BooleanArray.grou * * @return The [destination] map. * - * @sample test.collections.CollectionTest.groupByKeysAndValues + * @sample samples.collections.Collections.Transformations.groupByKeysAndValues */ public inline fun >> CharArray.groupByTo(destination: M, keySelector: (Char) -> K, valueTransform: (Char) -> V): M { for (element in this) { diff --git a/libraries/stdlib/src/generated/_Collections.kt b/libraries/stdlib/src/generated/_Collections.kt index a9ade75da3e..1fd388965ba 100644 --- a/libraries/stdlib/src/generated/_Collections.kt +++ b/libraries/stdlib/src/generated/_Collections.kt @@ -1139,7 +1139,7 @@ public inline fun > Iterable.flatMapTo(dest * * The returned map preserves the entry iteration order of the keys produced from the original collection. * - * @sample test.collections.CollectionTest.groupBy + * @sample samples.collections.Collections.Transformations.groupBy */ public inline fun Iterable.groupBy(keySelector: (T) -> K): Map> { return groupByTo(LinkedHashMap>(), keySelector) @@ -1152,7 +1152,7 @@ public inline fun Iterable.groupBy(keySelector: (T) -> K): Map Iterable.groupBy(keySelector: (T) -> K, valueTransform: (T) -> V): Map> { return groupByTo(LinkedHashMap>(), keySelector, valueTransform) @@ -1164,7 +1164,7 @@ public inline fun Iterable.groupBy(keySelector: (T) -> K, valueTran * * @return The [destination] map. * - * @sample test.collections.CollectionTest.groupBy + * @sample samples.collections.Collections.Transformations.groupBy */ public inline fun >> Iterable.groupByTo(destination: M, keySelector: (T) -> K): M { for (element in this) { @@ -1182,7 +1182,7 @@ public inline fun >> Iterable.group * * @return The [destination] map. * - * @sample test.collections.CollectionTest.groupByKeysAndValues + * @sample samples.collections.Collections.Transformations.groupByKeysAndValues */ public inline fun >> Iterable.groupByTo(destination: M, keySelector: (T) -> K, valueTransform: (T) -> V): M { for (element in this) { diff --git a/libraries/stdlib/src/generated/_Sequences.kt b/libraries/stdlib/src/generated/_Sequences.kt index 2f6d211c9ad..93bd66e0f32 100644 --- a/libraries/stdlib/src/generated/_Sequences.kt +++ b/libraries/stdlib/src/generated/_Sequences.kt @@ -608,7 +608,7 @@ public inline fun > Sequence.flatMapTo(dest * * The returned map preserves the entry iteration order of the keys produced from the original sequence. * - * @sample test.collections.CollectionTest.groupBy + * @sample samples.collections.Collections.Transformations.groupBy */ public inline fun Sequence.groupBy(keySelector: (T) -> K): Map> { return groupByTo(LinkedHashMap>(), keySelector) @@ -621,7 +621,7 @@ public inline fun Sequence.groupBy(keySelector: (T) -> K): Map Sequence.groupBy(keySelector: (T) -> K, valueTransform: (T) -> V): Map> { return groupByTo(LinkedHashMap>(), keySelector, valueTransform) @@ -633,7 +633,7 @@ public inline fun Sequence.groupBy(keySelector: (T) -> K, valueTran * * @return The [destination] map. * - * @sample test.collections.CollectionTest.groupBy + * @sample samples.collections.Collections.Transformations.groupBy */ public inline fun >> Sequence.groupByTo(destination: M, keySelector: (T) -> K): M { for (element in this) { @@ -651,7 +651,7 @@ public inline fun >> Sequence.group * * @return The [destination] map. * - * @sample test.collections.CollectionTest.groupByKeysAndValues + * @sample samples.collections.Collections.Transformations.groupByKeysAndValues */ public inline fun >> Sequence.groupByTo(destination: M, keySelector: (T) -> K, valueTransform: (T) -> V): M { for (element in this) { diff --git a/libraries/stdlib/src/generated/_Strings.kt b/libraries/stdlib/src/generated/_Strings.kt index 82eae0a206d..df9de48de4f 100644 --- a/libraries/stdlib/src/generated/_Strings.kt +++ b/libraries/stdlib/src/generated/_Strings.kt @@ -658,7 +658,7 @@ public inline fun > CharSequence.flatMapTo(destin * * The returned map preserves the entry iteration order of the keys produced from the original char sequence. * - * @sample test.collections.CollectionTest.groupBy + * @sample samples.collections.Collections.Transformations.groupBy */ public inline fun CharSequence.groupBy(keySelector: (Char) -> K): Map> { return groupByTo(LinkedHashMap>(), keySelector) @@ -671,7 +671,7 @@ public inline fun CharSequence.groupBy(keySelector: (Char) -> K): Map CharSequence.groupBy(keySelector: (Char) -> K, valueTransform: (Char) -> V): Map> { return groupByTo(LinkedHashMap>(), keySelector, valueTransform) @@ -683,7 +683,7 @@ public inline fun CharSequence.groupBy(keySelector: (Char) -> K, valueTra * * @return The [destination] map. * - * @sample test.collections.CollectionTest.groupBy + * @sample samples.collections.Collections.Transformations.groupBy */ public inline fun >> CharSequence.groupByTo(destination: M, keySelector: (Char) -> K): M { for (element in this) { @@ -701,7 +701,7 @@ public inline fun >> CharSequence.grou * * @return The [destination] map. * - * @sample test.collections.CollectionTest.groupByKeysAndValues + * @sample samples.collections.Collections.Transformations.groupByKeysAndValues */ public inline fun >> CharSequence.groupByTo(destination: M, keySelector: (Char) -> K, valueTransform: (Char) -> V): M { for (element in this) { diff --git a/libraries/stdlib/src/kotlin/collections/Collections.kt b/libraries/stdlib/src/kotlin/collections/Collections.kt index 67748803817..6c20db08d5a 100644 --- a/libraries/stdlib/src/kotlin/collections/Collections.kt +++ b/libraries/stdlib/src/kotlin/collections/Collections.kt @@ -113,7 +113,7 @@ public val Collection<*>.indices: IntRange /** * Returns the index of the last item in the list or -1 if the list is empty. * - * @sample test.collections.ListSpecificTest.lastIndex + * @sample samples.collections.Collections.Lists.lastIndexOfList */ public val List.lastIndex: Int get() = this.size - 1 diff --git a/libraries/stdlib/src/kotlin/collections/Maps.kt b/libraries/stdlib/src/kotlin/collections/Maps.kt index a44f9444ece..dd7e3fb92e6 100644 --- a/libraries/stdlib/src/kotlin/collections/Maps.kt +++ b/libraries/stdlib/src/kotlin/collections/Maps.kt @@ -23,7 +23,10 @@ private object EmptyMap : Map, Serializable { private fun readResolve(): Any = EmptyMap } -/** Returns an empty read-only map of specified type. The returned map is serializable (JVM). */ +/** + * Returns an empty read-only map of specified type. The returned map is serializable (JVM). + * @sample samples.collections.Maps.Instantiation.emptyReadOnlyMap + */ public fun emptyMap(): Map = @Suppress("UNCHECKED_CAST") (EmptyMap as Map) /** @@ -33,16 +36,22 @@ public fun emptyMap(): Map = @Suppress("UNCHECKED_CAST") (EmptyMap * * Entries of the map are iterated in the order they were specified. * The returned map is serializable (JVM). + * + * @sample samples.collections.Maps.Instantiation.mapFromPairs */ public fun mapOf(vararg pairs: Pair): Map = if (pairs.size > 0) linkedMapOf(*pairs) else emptyMap() -/** Returns an empty read-only map. The returned map is serializable (JVM). */ +/** + * Returns an empty read-only map. The returned map is serializable (JVM). + * @sample samples.collections.Maps.Instantiation.emptyReadOnlyMap + */ @kotlin.internal.InlineOnly public inline fun mapOf(): Map = emptyMap() /** * Returns an immutable map, mapping only the specified key to the * specified value. The returned map is serializable. + * @sample samples.collections.Maps.Instantiation.mapFromPairs */ @JvmVersion public fun mapOf(pair: Pair): Map = java.util.Collections.singletonMap(pair.first, pair.second) @@ -52,6 +61,8 @@ public fun mapOf(pair: Pair): Map = java.util.Collections.sin * where the first component is the key and the second is the value. If multiple pairs have * the same key, the resulting map will contain the value from the last of those pairs. * Entries of the map are iterated in the order they were specified. + * @sample samples.collections.Maps.Instantiation.mutableMapFromPairs + * @sample samples.collections.Maps.Instantiation.emptyMutableMap */ public fun mutableMapOf(vararg pairs: Pair): MutableMap = LinkedHashMap(mapCapacity(pairs.size)).apply { putAll(pairs) } @@ -60,7 +71,7 @@ public fun mutableMapOf(vararg pairs: Pair): MutableMap * Returns a new [HashMap] with the specified contents, given as a list of pairs * where the first component is the key and the second is the value. * - * @sample test.collections.MapTest.createUsingPairs + * @sample samples.collections.Maps.Instantiation.hashMapFromPairs */ public fun hashMapOf(vararg pairs: Pair): HashMap = HashMap(mapCapacity(pairs.size)).apply { putAll(pairs) } @@ -72,7 +83,7 @@ public fun hashMapOf(vararg pairs: Pair): HashMap * the same key, the resulting map will contain the value from the last of those pairs. * Entries of the map are iterated in the order they were specified. * - * @sample test.collections.MapTest.createLinkedMap + * @sample samples.collections.Maps.Instantiation.linkedMapFromPairs */ public fun linkedMapOf(vararg pairs: Pair): LinkedHashMap = LinkedHashMap(mapCapacity(pairs.size)).apply { putAll(pairs) } @@ -182,7 +193,7 @@ public inline fun Map.Entry.toPair(): Pair = Pair(key, value) /** * Returns the value for the given key, or the result of the [defaultValue] function if there was no entry for the given key. * - * @sample test.collections.MapTest.getOrElse + * @sample samples.collections.Maps.Usage.getOrElse */ @kotlin.internal.InlineOnly public inline fun Map.getOrElse(key: K, defaultValue: () -> V): V = get(key) ?: defaultValue() @@ -203,7 +214,7 @@ internal inline fun Map.getOrElseNullable(key: K, defaultValue: () * Returns the value for the given key. If the key is not found in the map, calls the [defaultValue] function, * puts its result into the map under the given key and returns it. * - * @sample test.collections.MapTest.getOrPut + * @sample samples.collections.Maps.Usage.getOrPut */ public inline fun MutableMap.getOrPut(key: K, defaultValue: () -> V): V { val value = get(key) @@ -219,7 +230,7 @@ public inline fun MutableMap.getOrPut(key: K, defaultValue: () -> V /** * Returns an [Iterator] over the entries in the [Map]. * - * @sample test.collections.MapTest.iterateWithProperties + * @sample samples.collections.Maps.Usage.forOverEntries */ @kotlin.internal.InlineOnly public inline operator fun Map.iterator(): Iterator> = entries.iterator() @@ -285,7 +296,7 @@ public fun MutableMap.putAll(pairs: Sequence>): Uni * * The returned map preserves the entry iteration order of the original map. * - * @sample test.collections.MapTest.mapValues + * @sample samples.collections.Maps.Transforms.mapValues */ @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") public inline fun Map.mapValues(transform: (Map.Entry) -> R): Map { @@ -301,7 +312,7 @@ public inline fun Map.mapValues(transform: (Map.Entry) * * The returned map preserves the entry iteration order of the original map. * - * @sample test.collections.MapTest.mapKeys + * @sample samples.collections.Maps.Transforms.mapKeys */ @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") public inline fun Map.mapKeys(transform: (Map.Entry) -> R): Map { diff --git a/libraries/stdlib/src/kotlin/collections/MapsJVM.kt b/libraries/stdlib/src/kotlin/collections/MapsJVM.kt index 1db7565323a..cd4a82605f0 100644 --- a/libraries/stdlib/src/kotlin/collections/MapsJVM.kt +++ b/libraries/stdlib/src/kotlin/collections/MapsJVM.kt @@ -40,7 +40,7 @@ public inline fun ConcurrentMap.getOrPut(key: K, defaultValue: () - /** * Converts this [Map] to a [SortedMap] so iteration order will be in key order. * - * @sample test.collections.MapJVMTest.toSortedMap + * @sample samples.collections.Maps.Transformations.mapToSortedMap */ public fun , V> Map.toSortedMap(): SortedMap = TreeMap(this) @@ -48,7 +48,7 @@ public fun , V> Map.toSortedMap(): SortedMap = * Converts this [Map] to a [SortedMap] using the given [comparator] so that iteration order will be in the order * defined by the comparator. * - * @sample test.collections.MapJVMTest.toSortedMapWithComparator + * @sample samples.collections.Maps.Transformations.mapToSortedMapWithComparator */ public fun Map.toSortedMap(comparator: Comparator): SortedMap = TreeMap(comparator).apply { putAll(this@toSortedMap) } @@ -57,7 +57,7 @@ public fun Map.toSortedMap(comparator: Comparator): Sorte * Returns a new [SortedMap] with the specified contents, given as a list of pairs * where the first value is the key and the second is the value. * - * @sample test.collections.MapJVMTest.createSortedMap + * @sample samples.collections.Maps.Instantiation.sortedMapFromPairs */ public fun , V> sortedMapOf(vararg pairs: Pair): SortedMap = TreeMap().apply { putAll(pairs) } @@ -66,7 +66,7 @@ public fun , V> sortedMapOf(vararg pairs: Pair): SortedM /** * Converts this [Map] to a [Properties] object. * - * @sample test.collections.MapJVMTest.toProperties + * @sample samples.collections.Maps.Transformations.mapToProperties */ @kotlin.internal.InlineOnly public inline fun Map.toProperties(): Properties diff --git a/libraries/stdlib/src/kotlin/text/StringsJVM.kt b/libraries/stdlib/src/kotlin/text/StringsJVM.kt index b0c73036c4b..075e61f4f38 100644 --- a/libraries/stdlib/src/kotlin/text/StringsJVM.kt +++ b/libraries/stdlib/src/kotlin/text/StringsJVM.kt @@ -385,7 +385,7 @@ public inline fun String.toPattern(flags: Int = 0): java.util.regex.Pattern { * Returns a copy of this string having its first letter uppercased, or the original string, * if it's empty or already starts with an upper case letter. * - * @sample test.text.StringTest.capitalize + * @sample samples.text.Strings.captialize */ public fun String.capitalize(): String { return if (isNotEmpty() && this[0].isLowerCase()) substring(0, 1).toUpperCase() + substring(1) else this @@ -395,7 +395,7 @@ public fun String.capitalize(): String { * Returns a copy of this string having its first letter lowercased, or the original string, * if it's empty or already starts with a lower case letter. * - * @sample test.text.StringTest.decapitalize + * @sample samples.text.Strings.decaptialize */ public fun String.decapitalize(): String { return if (isNotEmpty() && this[0].isUpperCase()) substring(0, 1).toLowerCase() + substring(1) else this @@ -404,7 +404,7 @@ public fun String.decapitalize(): String { /** * Returns a string containing this char sequence repeated [n] times. * @throws [IllegalArgumentException] when n < 0. - * @sample test.text.StringJVMTest.repeat + * @sample samples.text.Strings.repeat */ public fun CharSequence.repeat(n: Int): String { require (n >= 0) { "Count 'n' must be non-negative, but was $n." } diff --git a/libraries/stdlib/src/kotlin/text/regex/MatchResult.kt b/libraries/stdlib/src/kotlin/text/regex/MatchResult.kt index 9c0876f9ea2..94444521742 100644 --- a/libraries/stdlib/src/kotlin/text/regex/MatchResult.kt +++ b/libraries/stdlib/src/kotlin/text/regex/MatchResult.kt @@ -73,6 +73,8 @@ public interface MatchResult { * * If the group in the regular expression is optional and there were no match captured by that group, * corresponding item in [groupValues] is an empty string. + * + * @sample: samples.text.Regexps.matchDestructuringToGroupValues */ public val groupValues: List @@ -81,10 +83,7 @@ public interface MatchResult { * * component1 corresponds to the value of the first group, component2 — of the second, and so on. * - * @sample: - * ``` - * val (name, phone) = Regex("(\\w+) (\\d+)").match(inputString)!!.destructured - * ``` + * @sample: samples.text.Regexps.matchDestructuring */ public val destructured: Destructured get() = Destructured(this) @@ -100,6 +99,8 @@ public interface MatchResult { * * If the group in the regular expression is optional and there were no match captured by that group, * corresponding component value is an empty string. + * + * @sample: samples.text.Regexps.matchDestructuringToGroupValues */ public class Destructured internal constructor(public val match: MatchResult) { @kotlin.internal.InlineOnly @@ -125,6 +126,8 @@ public interface MatchResult { /** * Returns destructured group values as a list of strings. * First value in the returned list corresponds to the value of the first group, and so on. + * + * @sample: samples.text.Regexps.matchDestructuringToGroupValues */ public fun toList(): List = match.groupValues.subList(1, match.groupValues.size) } diff --git a/libraries/stdlib/src/kotlin/util/Preconditions.kt b/libraries/stdlib/src/kotlin/util/Preconditions.kt index 26914150ade..7ae8d724907 100644 --- a/libraries/stdlib/src/kotlin/util/Preconditions.kt +++ b/libraries/stdlib/src/kotlin/util/Preconditions.kt @@ -4,6 +4,8 @@ package kotlin /** * Throws an [IllegalArgumentException] if the [value] is false. + * + * @sample samples.misc.Preconditions.failRequireWithLazyMessage */ @kotlin.internal.InlineOnly public inline fun require(value: Boolean): Unit = require(value) { "Failed requirement." } @@ -11,7 +13,7 @@ public inline fun require(value: Boolean): Unit = require(value) { "Failed requi /** * Throws an [IllegalArgumentException] with the result of calling [lazyMessage] if the [value] is false. * - * @sample test.collections.PreconditionsTest.failingRequireWithLazyMessage + * @sample samples.misc.Preconditions.failRequireWithLazyMessage */ @kotlin.internal.InlineOnly public inline fun require(value: Boolean, lazyMessage: () -> Any): Unit { @@ -31,7 +33,7 @@ public inline fun requireNotNull(value: T?): T = requireNotNull(value) { * Throws an [IllegalArgumentException] with the result of calling [lazyMessage] if the [value] is null. Otherwise * returns the not null value. * - * @sample test.collections.PreconditionsTest.requireNotNullWithLazyMessage + * @sample samples.misc.Preconditions.failRequireWithLazyMessage */ @kotlin.internal.InlineOnly public inline fun requireNotNull(value: T?, lazyMessage: () -> Any): T { @@ -45,6 +47,8 @@ public inline fun requireNotNull(value: T?, lazyMessage: () -> Any): T { /** * Throws an [IllegalStateException] if the [value] is false. + * + * @sample samples.misc.Preconditions.failCheckWithLazyMessage */ @kotlin.internal.InlineOnly public inline fun check(value: Boolean): Unit = check(value) { "Check failed." } @@ -52,7 +56,7 @@ public inline fun check(value: Boolean): Unit = check(value) { "Check failed." } /** * Throws an [IllegalStateException] with the result of calling [lazyMessage] if the [value] is false. * - * @sample test.collections.PreconditionsTest.failingCheckWithLazyMessage + * @sample samples.misc.Preconditions.failCheckWithLazyMessage */ @kotlin.internal.InlineOnly public inline fun check(value: Boolean, lazyMessage: () -> Any): Unit { @@ -65,6 +69,8 @@ public inline fun check(value: Boolean, lazyMessage: () -> Any): Unit { /** * Throws an [IllegalStateException] if the [value] is null. Otherwise * returns the not null value. + * + * @sample samples.misc.Preconditions.failCheckWithLazyMessage */ @kotlin.internal.InlineOnly public inline fun checkNotNull(value: T?): T = checkNotNull(value) { "Required value was null." } @@ -72,6 +78,8 @@ public inline fun checkNotNull(value: T?): T = checkNotNull(value) { "Re /** * Throws an [IllegalStateException] with the result of calling [lazyMessage] if the [value] is null. Otherwise * returns the not null value. + * + * @sample samples.misc.Preconditions.failCheckWithLazyMessage */ @kotlin.internal.InlineOnly public inline fun checkNotNull(value: T?, lazyMessage: () -> Any): T { @@ -87,7 +95,7 @@ public inline fun checkNotNull(value: T?, lazyMessage: () -> Any): T { /** * Throws an [IllegalStateException] with the given [message]. * - * @sample test.collections.PreconditionsTest.error + * @sample samples.misc.Preconditions.failWithError */ @kotlin.internal.InlineOnly public inline fun error(message: Any): Nothing = throw IllegalStateException(message.toString()) diff --git a/libraries/stdlib/src/kotlin/util/Tuples.kt b/libraries/stdlib/src/kotlin/util/Tuples.kt index 6e78a87c9cc..b85d770b333 100644 --- a/libraries/stdlib/src/kotlin/util/Tuples.kt +++ b/libraries/stdlib/src/kotlin/util/Tuples.kt @@ -9,7 +9,7 @@ package kotlin * Pair exhibits value semantics, i.e. two pairs are equal if both components are equal. * * An example of decomposing it into values: - * @sample test.tuples.PairTest.pairMultiAssignment + * @sample samples.misc.Tuples.pairDestructuring * * @param A type of the first value. * @param B type of the second value. @@ -32,7 +32,7 @@ public data class Pair( * Creates a tuple of type [Pair] from this and [that]. * * This can be useful for creating [Map] literals with less noise, for example: - * @sample test.collections.MapTest.createUsingTo + * @sample samples.collections.Maps.Instantiation.mapFromPairs */ public infix fun A.to(that: B): Pair = Pair(this, that) @@ -47,7 +47,7 @@ public fun Pair.toList(): List = listOf(first, second) * There is no meaning attached to values in this class, it can be used for any purpose. * Triple exhibits value semantics, i.e. two triples are equal if all three components are equal. * An example of decomposing it into values: - * @sample test.tuples.TripleTest.tripleMultiAssignment + * @sample samples.misc.Tuples.tripleDestructuring * * @param A type of the first value. * @param B type of the second value. diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Mapping.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Mapping.kt index e57df6da730..3c1ecaf3c94 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Mapping.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Mapping.kt @@ -297,7 +297,7 @@ fun mapping(): List { The returned map preserves the entry iteration order of the keys produced from the original ${f.collection}. - @sample test.collections.CollectionTest.groupBy + @sample samples.collections.Collections.Transformations.groupBy """ } typeParam("K") @@ -318,7 +318,7 @@ fun mapping(): List { @return The [destination] map. - @sample test.collections.CollectionTest.groupBy + @sample samples.collections.Collections.Transformations.groupBy """ } returns("M") @@ -346,7 +346,7 @@ fun mapping(): List { The returned map preserves the entry iteration order of the keys produced from the original ${f.collection}. - @sample test.collections.CollectionTest.groupByKeysAndValues + @sample samples.collections.Collections.Transformations.groupByKeysAndValues """ } typeParam("K") @@ -372,7 +372,7 @@ fun mapping(): List { @return The [destination] map. - @sample test.collections.CollectionTest.groupByKeysAndValues + @sample samples.collections.Collections.Transformations.groupByKeysAndValues """ } returns("M")