Average Extension Methods (#49)

* Added the average methods.

* Return null if list is empty.

Author: arielmagbanua

.gitignore

@@ -16,3 +16,5 @@ doc/api/
 
 # macOS stuff.
 .DS_Store
+
+.vscode/launch.json

lib/iterable_basics.dart

@@ -154,6 +154,22 @@ extension IterableBasics<E> on Iterable<E> {
       ? 0
       : this.fold(0, (prev, element) => prev + addend(element));
 
+  /// Returns the average of all the values in this iterable, as defined by
+  /// [value].
+  ///
+  /// Returns null if [this] is empty.
+  ///
+  /// Example:
+  /// ```dart
+  /// ['a', 'aa', 'aaa'].average((s) => s.length); // 2
+  /// [].average(); // null
+  /// ```
+  num? average(num Function(E) value) {
+    if (this.isEmpty) return null;
+
+    return this.sum(value) / this.length;
+  }
+
   /// Returns a random element of [this], or [null] if [this] is empty.
   ///
   /// If [seed] is provided, will be used as the random seed for determining
@@ -237,6 +253,25 @@ extension NumIterableBasics<E extends num> on Iterable<E> {
         ? this.reduce((a, b) => (a + b) as E)
         : this.fold(0, (prev, element) => prev + addend(element));
   }
+
+  /// Returns the average of all the values in this iterable.
+  ///
+  /// If [value] is provided, it will be used to compute the value to be
+  /// averaged.
+  ///
+  /// Returns null if [this] is empty.
+  ///
+  /// Example:
+  /// ```dart
+  /// [2, 2, 4, 8].average(); // 4.
+  /// [2, 2, 4, 8].average((i) => i + 1); // 5.
+  /// [].average() // null.
+  /// ```
+  num? average([num Function(E)? value]) {
+    if (this.isEmpty) return null;
+
+    return this.sum(value) / this.length;
+  }
 }
 
 T Function(T, T) _generateCustomMaxFunction<T>(Comparator<T> compare) {

test/iterable_basics_test.dart

@@ -407,6 +407,49 @@ void main() {
     });
   });
 
+  group('average', () {
+    test('returns average on list of numbers', () {
+      final nums = <int>[2, 2, 4, 8];
+      final ints = <int>[2, 2, 2];
+      final numbers = [1.5, 1.5, 3, 3];
+
+      expect(nums.average(), 4);
+      expect(ints.average(), 2);
+      expect(ints.average((n) => n * 2), 4);
+      expect(nums.average((n) => n + 1), 5);
+      expect(numbers.average(), 2.25);
+    });
+
+    test('returns null on empty lists', () {
+      expect(<int>[].average(), null);
+      expect(<double>[].average(), null);
+      expect(<num>[].average((n) => n * 2), null);
+      expect(<String>[].average((s) => s.length), null);
+      expect(<int>[].average((n) => n * 2), null);
+    });
+
+    test('returns average of custom value function', () {
+      final strings = ['a', 'aa', 'aaa'];
+
+      expect(strings.average((s) => s.length), 2);
+    });
+
+    test('works on sets', () {
+      final strings = {'a', 'aa', 'aaa'};
+
+      expect(strings.average((s) => s.length), 2);
+    });
+
+    test('works on dynamic list with custom value function', () {
+      final items = [1, 'aaa', 2.0];
+
+      expect(items.average((a) => _getItemSize(a)), equals(2));
+
+      items.add(0.5);
+      expect(items.average((a) => _getItemSize(a)), equals(1.625));
+    });
+  });
+
   group('sum', () {
     test('returns sum on list of numbers', () {
       final nums = [1.5, 2, 3];