Various improvements in collection samples #KT-20357

Merge some related samples,
add sample for building a sequence from Enumeration similar to building a list from Enumeration.

libraries/stdlib/samples/test/samples/collections/collections.kt

@@ -73,12 +73,14 @@ class Collections {
 
         @Sample
         fun emptyReadOnlyList() {
-            val list = emptyList<Int>()
+            val list = listOf<String>()
             assertTrue(list.isEmpty())
 
-            val other = listOf<String>()
+            // another way to create an empty list,
-            assertTrue(list == other, "Empty lists are equal")
+            // type parameter is inferred from the expected type
+            val other: List<Int> = emptyList()
 
+            assertTrue(list == other, "Empty lists are equal")
             assertPrints(list, "[]")
             assertFails { list[0] }
         }
@@ -86,7 +88,7 @@ class Collections {
         @Sample
         fun readOnlyList() {
             val list = listOf('a', 'b', 'c')
-            assertPrints(list.count(), "3")
+            assertPrints(list.size, "3")
             assertTrue(list.contains('a'))
             assertPrints(list.indexOf('b'), "1")
             assertPrints(list[2], "c")
@@ -96,7 +98,7 @@ class Collections {
         fun singletonReadOnlyList() {
             val list = listOf('a')
             assertPrints(list, "[a]")
-            assertPrints(list.count(), "1")
+            assertPrints(list.size, "1")
         }
 
         @Sample
@@ -122,7 +124,7 @@ class Collections {
             val list = mutableListOf(1, 2, 3)
             assertPrints(list, "[1, 2, 3]")
 
-            list.addAll(listOf(4, 5))
+            list += listOf(4, 5)
             assertPrints(list, "[1, 2, 3, 4, 5]")
         }
 
@@ -131,46 +133,35 @@ class Collections {
             val list = arrayListOf(1, 2, 3)
             assertPrints(list, "[1, 2, 3]")
 
-            list.addAll(listOf(4, 5))
+            list += listOf(4, 5)
             assertPrints(list, "[1, 2, 3, 4, 5]")
         }
 
-        @Sample
-        fun singletonListOfNotNull() {
-            val empty = listOfNotNull<Any>(null)
-            assertPrints(empty, "[]")
-
-            val singleton = listOfNotNull(42)
-            assertPrints(singleton, "[42]")
-        }
-
         @Sample
         fun listOfNotNull() {
             val empty = listOfNotNull<Any>(null)
             assertPrints(empty, "[]")
 
+            val singleton = listOfNotNull(42)
+            assertPrints(singleton, "[42]")
+
             val list = listOfNotNull(1, null, 2, null, 3)
             assertPrints(list, "[1, 2, 3]")
         }
 
         @Sample
         fun readOnlyListFromInitializer() {
-            val empty = List(0) {}
-            assertPrints(empty, "[]")
-
             val squares = List(5) { (it + 1) * (it + 1) }
             assertPrints(squares, "[1, 4, 9, 16, 25]")
         }
 
         @Sample
         fun mutableListFromInitializer() {
-            val chars = listOf('a', 'b', 'c', 'd')
+            val list = MutableList(3) { index -> 'A' + index }
+            assertPrints(list, "[A, B, C]")
 
-            val list = MutableList(3) { chars[it] }
+            list.clear()
-            assertPrints(list, "[a, b, c]")
+            assertPrints(list, "[]")
-
-            list.add(chars[3])
-            assertTrue(list == chars)
         }
 
         @Sample
@@ -191,13 +182,16 @@ class Collections {
         }
 
         @Sample
-        fun enumerationToList() {
+        fun listFromEnumeration() {
             val numbers = java.util.Hashtable<String, Int>()
             numbers.put("one", 1)
             numbers.put("two", 2)
             numbers.put("three", 3)
 
-            val enumeration = numbers.elements()
+            // when you have an Enumeration from some old code
+            val enumeration: java.util.Enumeration<Int> = numbers.elements()
+
+            // you can convert it to list and transform further with list operations
             val list = enumeration.toList().sorted()
             assertPrints(list, "[1, 2, 3]")
         }
@@ -246,13 +240,20 @@ class Collections {
 
         @Sample
         fun binarySearchWithComparisonFunction() {
-            data class Box(val value: Int)
+            data class Box(val value: String)
 
-            val numbers = listOf(12, 10, 7, 3, 1)
+            val values = listOf("A", "ant", "binding", "Box", "cell")
-            val boxes = numbers.map { Box(it) }
+            val boxes = values.map { Box(it) }
 
-            // `boxes` is sorted according to the comparison function
+            val valueToFind = "box"
-            assertPrints(boxes.binarySearch { 10 - it.value }, "1")
+            // `boxes` list is sorted according to the following comparison function
+            val index = boxes.binarySearch { String.CASE_INSENSITIVE_ORDER.compare(it.value, valueToFind) }
+
+            if (index >= 0) {
+                assertPrints("Value at $index is ${boxes[index]}", "Value at 3 is Box(value=Box)")
+            } else {
+                println("Box with value=$valueToFind was not found")
+            }
         }
     }
 

libraries/stdlib/samples/test/samples/collections/sequences.kt

@@ -92,6 +92,24 @@ class Sequences {
             // sequence2.drop(1).joinToString() // <- iterating sequence second time will fail
         }
 
+        @Sample
+        fun sequenceFromEnumeration() {
+            val numbers = java.util.Hashtable<String, Int>()
+            numbers.put("one", 1)
+            numbers.put("two", 2)
+            numbers.put("three", 3)
+
+            // when you have an Enumeration from some old code
+            val enumeration: java.util.Enumeration<String> = numbers.keys()
+
+            // you can wrap it in a sequence and transform further with sequence operations
+            val sequence = enumeration.asSequence().sorted()
+            assertPrints(sequence.toList(), "[one, three, two]")
+
+            // the resulting sequence is one-shot
+            assertFails { sequence.toList() }
+        }
+
         @Sample
         fun buildFibonacciSequence() {
             fun fibonacci() = buildSequence {

libraries/stdlib/src/kotlin/collections/Collections.kt

@@ -132,7 +132,7 @@ public fun <T> arrayListOf(vararg elements: T): ArrayList<T>
 
 /**
  * Returns a new read-only list either of single given element, if it is not null, or empty list if the element is null. The returned list is serializable (JVM).
- * @sample samples.collections.Collections.Lists.singletonListOfNotNull
+ * @sample samples.collections.Collections.Lists.listOfNotNull
  */
 public fun <T : Any> listOfNotNull(element: T?): List<T> = if (element != null) listOf(element) else emptyList()
 

libraries/stdlib/src/kotlin/collections/Sequences.kt

@@ -24,6 +24,7 @@ public fun <T> Iterator<T>.asSequence(): Sequence<T> = Sequence { this }.constra
 
 /**
  * Creates a sequence that returns all values from this enumeration. The sequence is constrained to be iterated only once.
+ * @sample samples.collections.Sequences.Building.sequenceFromEnumeration
  */
 @kotlin.jvm.JvmVersion
 @kotlin.internal.InlineOnly