Provide average() method for iterables, sequences and arrays.

#KT-3843 Fixed

libraries/stdlib/src/generated/_Numeric.kt

@@ -10,6 +10,462 @@ import java.util.*
 
 import java.util.Collections // TODO: it's temporary while we have java.util.Collections in js
 
+/**
+ * Returns an average value of elements in the collection
+ */
+platformName("averageOfInt")
+public fun Iterable<Int>.average(): Double {
+    val iterator = iterator()
+    var sum: Double = 0.0
+    var count: Int = 0
+    while (iterator.hasNext()) {
+        sum += iterator.next()
+        count += 1
+    }
+    return if (count == 0) 0.0 else sum / count
+}
+
+/**
+ * Returns an average value of elements in the collection
+ */
+platformName("averageOfInt")
+public fun Sequence<Int>.average(): Double {
+    val iterator = iterator()
+    var sum: Double = 0.0
+    var count: Int = 0
+    while (iterator.hasNext()) {
+        sum += iterator.next()
+        count += 1
+    }
+    return if (count == 0) 0.0 else sum / count
+}
+
+
+deprecated("Migrate to using Sequence<T> and respective functions")
+/**
+ * Returns an average value of elements in the collection
+ */
+platformName("averageOfInt")
+public fun Stream<Int>.average(): Double {
+    val iterator = iterator()
+    var sum: Double = 0.0
+    var count: Int = 0
+    while (iterator.hasNext()) {
+        sum += iterator.next()
+        count += 1
+    }
+    return if (count == 0) 0.0 else sum / count
+}
+
+/**
+ * Returns an average value of elements in the collection
+ */
+platformName("averageOfInt")
+public fun Array<out Int>.average(): Double {
+    val iterator = iterator()
+    var sum: Double = 0.0
+    var count: Int = 0
+    while (iterator.hasNext()) {
+        sum += iterator.next()
+        count += 1
+    }
+    return if (count == 0) 0.0 else sum / count
+}
+
+/**
+ * Returns an average value of elements in the collection
+ */
+public fun IntArray.average(): Double {
+    val iterator = iterator()
+    var sum: Double = 0.0
+    var count: Int = 0
+    while (iterator.hasNext()) {
+        sum += iterator.next()
+        count += 1
+    }
+    return if (count == 0) 0.0 else sum / count
+}
+
+/**
+ * Returns an average value of elements in the collection
+ */
+platformName("averageOfLong")
+public fun Iterable<Long>.average(): Double {
+    val iterator = iterator()
+    var sum: Double = 0.0
+    var count: Int = 0
+    while (iterator.hasNext()) {
+        sum += iterator.next()
+        count += 1
+    }
+    return if (count == 0) 0.0 else sum / count
+}
+
+/**
+ * Returns an average value of elements in the collection
+ */
+platformName("averageOfLong")
+public fun Sequence<Long>.average(): Double {
+    val iterator = iterator()
+    var sum: Double = 0.0
+    var count: Int = 0
+    while (iterator.hasNext()) {
+        sum += iterator.next()
+        count += 1
+    }
+    return if (count == 0) 0.0 else sum / count
+}
+
+
+deprecated("Migrate to using Sequence<T> and respective functions")
+/**
+ * Returns an average value of elements in the collection
+ */
+platformName("averageOfLong")
+public fun Stream<Long>.average(): Double {
+    val iterator = iterator()
+    var sum: Double = 0.0
+    var count: Int = 0
+    while (iterator.hasNext()) {
+        sum += iterator.next()
+        count += 1
+    }
+    return if (count == 0) 0.0 else sum / count
+}
+
+/**
+ * Returns an average value of elements in the collection
+ */
+platformName("averageOfLong")
+public fun Array<out Long>.average(): Double {
+    val iterator = iterator()
+    var sum: Double = 0.0
+    var count: Int = 0
+    while (iterator.hasNext()) {
+        sum += iterator.next()
+        count += 1
+    }
+    return if (count == 0) 0.0 else sum / count
+}
+
+/**
+ * Returns an average value of elements in the collection
+ */
+public fun LongArray.average(): Double {
+    val iterator = iterator()
+    var sum: Double = 0.0
+    var count: Int = 0
+    while (iterator.hasNext()) {
+        sum += iterator.next()
+        count += 1
+    }
+    return if (count == 0) 0.0 else sum / count
+}
+
+/**
+ * Returns an average value of elements in the collection
+ */
+platformName("averageOfByte")
+public fun Iterable<Byte>.average(): Double {
+    val iterator = iterator()
+    var sum: Double = 0.0
+    var count: Int = 0
+    while (iterator.hasNext()) {
+        sum += iterator.next()
+        count += 1
+    }
+    return if (count == 0) 0.0 else sum / count
+}
+
+/**
+ * Returns an average value of elements in the collection
+ */
+platformName("averageOfByte")
+public fun Sequence<Byte>.average(): Double {
+    val iterator = iterator()
+    var sum: Double = 0.0
+    var count: Int = 0
+    while (iterator.hasNext()) {
+        sum += iterator.next()
+        count += 1
+    }
+    return if (count == 0) 0.0 else sum / count
+}
+
+
+deprecated("Migrate to using Sequence<T> and respective functions")
+/**
+ * Returns an average value of elements in the collection
+ */
+platformName("averageOfByte")
+public fun Stream<Byte>.average(): Double {
+    val iterator = iterator()
+    var sum: Double = 0.0
+    var count: Int = 0
+    while (iterator.hasNext()) {
+        sum += iterator.next()
+        count += 1
+    }
+    return if (count == 0) 0.0 else sum / count
+}
+
+/**
+ * Returns an average value of elements in the collection
+ */
+platformName("averageOfByte")
+public fun Array<out Byte>.average(): Double {
+    val iterator = iterator()
+    var sum: Double = 0.0
+    var count: Int = 0
+    while (iterator.hasNext()) {
+        sum += iterator.next()
+        count += 1
+    }
+    return if (count == 0) 0.0 else sum / count
+}
+
+/**
+ * Returns an average value of elements in the collection
+ */
+public fun ByteArray.average(): Double {
+    val iterator = iterator()
+    var sum: Double = 0.0
+    var count: Int = 0
+    while (iterator.hasNext()) {
+        sum += iterator.next()
+        count += 1
+    }
+    return if (count == 0) 0.0 else sum / count
+}
+
+/**
+ * Returns an average value of elements in the collection
+ */
+platformName("averageOfShort")
+public fun Iterable<Short>.average(): Double {
+    val iterator = iterator()
+    var sum: Double = 0.0
+    var count: Int = 0
+    while (iterator.hasNext()) {
+        sum += iterator.next()
+        count += 1
+    }
+    return if (count == 0) 0.0 else sum / count
+}
+
+/**
+ * Returns an average value of elements in the collection
+ */
+platformName("averageOfShort")
+public fun Sequence<Short>.average(): Double {
+    val iterator = iterator()
+    var sum: Double = 0.0
+    var count: Int = 0
+    while (iterator.hasNext()) {
+        sum += iterator.next()
+        count += 1
+    }
+    return if (count == 0) 0.0 else sum / count
+}
+
+
+deprecated("Migrate to using Sequence<T> and respective functions")
+/**
+ * Returns an average value of elements in the collection
+ */
+platformName("averageOfShort")
+public fun Stream<Short>.average(): Double {
+    val iterator = iterator()
+    var sum: Double = 0.0
+    var count: Int = 0
+    while (iterator.hasNext()) {
+        sum += iterator.next()
+        count += 1
+    }
+    return if (count == 0) 0.0 else sum / count
+}
+
+/**
+ * Returns an average value of elements in the collection
+ */
+platformName("averageOfShort")
+public fun Array<out Short>.average(): Double {
+    val iterator = iterator()
+    var sum: Double = 0.0
+    var count: Int = 0
+    while (iterator.hasNext()) {
+        sum += iterator.next()
+        count += 1
+    }
+    return if (count == 0) 0.0 else sum / count
+}
+
+/**
+ * Returns an average value of elements in the collection
+ */
+public fun ShortArray.average(): Double {
+    val iterator = iterator()
+    var sum: Double = 0.0
+    var count: Int = 0
+    while (iterator.hasNext()) {
+        sum += iterator.next()
+        count += 1
+    }
+    return if (count == 0) 0.0 else sum / count
+}
+
+/**
+ * Returns an average value of elements in the collection
+ */
+platformName("averageOfDouble")
+public fun Iterable<Double>.average(): Double {
+    val iterator = iterator()
+    var sum: Double = 0.0
+    var count: Int = 0
+    while (iterator.hasNext()) {
+        sum += iterator.next()
+        count += 1
+    }
+    return if (count == 0) 0.0 else sum / count
+}
+
+/**
+ * Returns an average value of elements in the collection
+ */
+platformName("averageOfDouble")
+public fun Sequence<Double>.average(): Double {
+    val iterator = iterator()
+    var sum: Double = 0.0
+    var count: Int = 0
+    while (iterator.hasNext()) {
+        sum += iterator.next()
+        count += 1
+    }
+    return if (count == 0) 0.0 else sum / count
+}
+
+
+deprecated("Migrate to using Sequence<T> and respective functions")
+/**
+ * Returns an average value of elements in the collection
+ */
+platformName("averageOfDouble")
+public fun Stream<Double>.average(): Double {
+    val iterator = iterator()
+    var sum: Double = 0.0
+    var count: Int = 0
+    while (iterator.hasNext()) {
+        sum += iterator.next()
+        count += 1
+    }
+    return if (count == 0) 0.0 else sum / count
+}
+
+/**
+ * Returns an average value of elements in the collection
+ */
+platformName("averageOfDouble")
+public fun Array<out Double>.average(): Double {
+    val iterator = iterator()
+    var sum: Double = 0.0
+    var count: Int = 0
+    while (iterator.hasNext()) {
+        sum += iterator.next()
+        count += 1
+    }
+    return if (count == 0) 0.0 else sum / count
+}
+
+/**
+ * Returns an average value of elements in the collection
+ */
+public fun DoubleArray.average(): Double {
+    val iterator = iterator()
+    var sum: Double = 0.0
+    var count: Int = 0
+    while (iterator.hasNext()) {
+        sum += iterator.next()
+        count += 1
+    }
+    return if (count == 0) 0.0 else sum / count
+}
+
+/**
+ * Returns an average value of elements in the collection
+ */
+platformName("averageOfFloat")
+public fun Iterable<Float>.average(): Double {
+    val iterator = iterator()
+    var sum: Double = 0.0
+    var count: Int = 0
+    while (iterator.hasNext()) {
+        sum += iterator.next()
+        count += 1
+    }
+    return if (count == 0) 0.0 else sum / count
+}
+
+/**
+ * Returns an average value of elements in the collection
+ */
+platformName("averageOfFloat")
+public fun Sequence<Float>.average(): Double {
+    val iterator = iterator()
+    var sum: Double = 0.0
+    var count: Int = 0
+    while (iterator.hasNext()) {
+        sum += iterator.next()
+        count += 1
+    }
+    return if (count == 0) 0.0 else sum / count
+}
+
+
+deprecated("Migrate to using Sequence<T> and respective functions")
+/**
+ * Returns an average value of elements in the collection
+ */
+platformName("averageOfFloat")
+public fun Stream<Float>.average(): Double {
+    val iterator = iterator()
+    var sum: Double = 0.0
+    var count: Int = 0
+    while (iterator.hasNext()) {
+        sum += iterator.next()
+        count += 1
+    }
+    return if (count == 0) 0.0 else sum / count
+}
+
+/**
+ * Returns an average value of elements in the collection
+ */
+platformName("averageOfFloat")
+public fun Array<out Float>.average(): Double {
+    val iterator = iterator()
+    var sum: Double = 0.0
+    var count: Int = 0
+    while (iterator.hasNext()) {
+        sum += iterator.next()
+        count += 1
+    }
+    return if (count == 0) 0.0 else sum / count
+}
+
+/**
+ * Returns an average value of elements in the collection
+ */
+public fun FloatArray.average(): Double {
+    val iterator = iterator()
+    var sum: Double = 0.0
+    var count: Int = 0
+    while (iterator.hasNext()) {
+        sum += iterator.next()
+        count += 1
+    }
+    return if (count == 0) 0.0 else sum / count
+}
+
 /**
  * Returns the sum of all elements in the collection.
  */

libraries/stdlib/test/collections/ArraysTest.kt

@@ -160,6 +160,17 @@ class ArraysTest {
         expect(3.0.toFloat()) { arrayOf<Float>(1.0.toFloat(), 2.0.toFloat()).sum() }
     }
 
+    test fun average() {
+        expect(0.0) { array<Int>().average() }
+        expect(3.8) { array(1, 2, 5, 8, 3).average() }
+        expect(2.1) { array(1.6, 2.6, 3.6, 0.6).average() }
+        expect(100.0) { array<Byte>(100, 100, 100, 100, 100, 100).average() }
+        expect(0) { array<Short>(1, -1, 2, -2, 3, -3).average().toShort() }
+        // TODO: Property based tests
+        // for each arr with size 1 arr.average() == arr[0]
+        // for each arr with size > 0  arr.average() = arr.sum().toDouble() / arr.size()
+    }
+
     test fun indexOf() {
         expect(-1) { arrayOf("cat", "dog", "bird").indexOf("mouse") }
         expect(0) { arrayOf("cat", "dog", "bird").indexOf("cat") }

libraries/stdlib/test/collections/CollectionTest.kt

@@ -438,6 +438,16 @@ class CollectionTest {
         expect(3.0.toFloat()) { sequenceOf<Float>(1.0.toFloat(), 2.0.toFloat()).sum() }
     }
 
+    test fun average() {
+        expect(0.0) { arrayListOf<Int>().average() }
+        expect(3.8) { listOf(1, 2, 5, 8, 3).average() }
+        expect(2.1) { sequenceOf(1.6, 2.6, 3.6, 0.6).average() }
+        expect(100.0) { arrayListOf<Byte>(100, 100, 100, 100, 100, 100).average() }
+        val n = 100
+        val range = 0..n
+        expect(n.toDouble()/2) { range.average() }
+    }
+
     test fun takeReturnsFirstNElements() {
         expect(listOf(1, 2, 3, 4, 5)) { (1..10) take 5 }
         expect(listOf(1, 2, 3, 4, 5)) { (1..10).toList().take(5) }

libraries/tools/kotlin-stdlib-gen/src/templates/Numeric.kt

@@ -21,5 +21,23 @@ fun numeric(): List<GenericFunction> {
         }
     }
 
+    templates add f("average()") {
+        exclude(Strings)
+        doc { "Returns an average value of elements in the collection"}
+        returns("Double")
+        body {
+            """
+            val iterator = iterator()
+            var sum: Double = 0.0
+            var count: Int = 0
+            while (iterator.hasNext()) {
+                sum += iterator.next()
+                count += 1
+            }
+            return if (count == 0) 0.0 else sum / count
+            """
+        }
+    }
+
     return templates
 }