Improve onEach templates.

Add new functions to reference API.
Add tests for onEach
  #KT-8220

libraries/stdlib/test/collections/IterableTests.kt

@@ -192,6 +192,17 @@ abstract class IterableTests<T : Iterable<String>>(val data: T, val empty: T) {
         assertEquals(6, count)
     }
 
+    @Test
+    fun onEach() {
+        var count = 0
+        val newData = data.onEach { count += it.length }
+        assertEquals(6, count)
+        assertTrue(data === newData)
+
+        // static types test
+        val list: ArrayList<Int> = arrayListOf(1, 2, 3).onEach {  }
+    }
+
     @Test
     fun contains() {
         assertTrue(data.contains("foo"))

libraries/stdlib/test/collections/MapTest.kt

@@ -98,6 +98,19 @@ class MapTest {
         assertEquals("beverage,beer,location,Mells,name,James", list.joinToString(","))
     }
 
+
+    @Test
+    fun onEach() {
+        val map = mutableMapOf("beverage" to "beer", "location" to "Mells")
+        val result = StringBuilder()
+        val newMap = map.onEach { result.append(it.key).append("=").append(it.value).append(";") }
+        assertEquals("beverage=beer;location=Mells;", result.toString())
+        assertTrue(map === newMap)
+
+        // static types test
+        val m: HashMap<String, String> = hashMapOf("a" to "b").onEach {  }
+    }
+
     @Test fun stream() {
         val map = mapOf("beverage" to "beer", "location" to "Mells", "name" to "James")
         val named = map.asSequence().filter { it.key == "name" }.single()

libraries/stdlib/test/collections/SequenceTest.kt

@@ -87,6 +87,22 @@ public class SequenceTest {
         assertEquals(listOf("f", "ba"), indexed)
     }
 
+    @Test
+    fun onEach() {
+        var count = 0
+        val data = sequenceOf("foo", "bar")
+        val newData = data.onEach { count += it.length }
+        assertFalse(data === newData)
+        assertEquals(0, count, "onEach should be executed lazily")
+
+        data.forEach {  }
+        assertEquals(0, count, "onEach should be executed only when resulting sequence is iterated")
+
+        val sum = newData.sumBy { it.length }
+        assertEquals(sum, count)
+    }
+
+
     @Test fun filterAndTakeWhileExtractTheElementsWithinRange() {
         assertEquals(listOf(144, 233, 377, 610, 987), fibonacci().filter { it > 100 }.takeWhile { it < 1000 }.toList())
     }

libraries/stdlib/test/text/StringTest.kt

@@ -753,6 +753,18 @@ class StringTest {
         assertEquals(data.toString(), sb.toString())
     }
 
+    @Test
+    fun onEach() = withOneCharSequenceArg("abcd") { data ->
+        val result = StringBuilder()
+        val newData = data.onEach { result.append(it + 1) }
+        assertEquals("bcde", result.toString())
+        assertTrue(data === newData)
+
+        // static types test
+        val s: String = "x".onEach {  }
+        val sb: StringBuilder = result.onEach {  }
+    }
+
 
     @Test fun filter() {
         assertEquals("acdca", ("abcdcba").filter { !it.equals('b') })