Documentation update for Iterable class

Contains:
- Examples

Closes dart-lang/sdk#47845
dart-lang/sdk#47845

GitOrigin-RevId: ba3b885224b2511be2b06148d16bd6d3622473d9
Change-Id: Iadc197183b6464d66527701ba71978c8d9ac683a
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/222023
Reviewed-by: Lasse Nielsen <lrn@google.com>
Commit-Queue: Lasse Nielsen <lrn@google.com>

Author: jpsiitonen

sdk/lib/core/iterable.dart

@@ -162,6 +162,13 @@ abstract class Iterable<E> {
   /// The returned iterable will provide the same elements as this iterable,
   /// and, after that, the elements of [other], in the same order as in the
   /// original iterables.
+  ///
+  /// Example:
+  /// ```dart
+  /// var planets = <String>['Earth', 'Jupiter'];
+  /// var updated = planets.followedBy(['Mars', 'Venus']);
+  /// print(updated); // (Earth, Jupiter, Mars, Venus)
+  /// ```
   Iterable<E> followedBy(Iterable<E> other) {
     var self = this; // TODO(lrn): Remove when we can promote `this`.
     if (self is EfficientLengthIterable<E>) {
@@ -189,13 +196,24 @@ abstract class Iterable<E> {
   /// For example, [elementAt] may call `toElement` only once.
   ///
   /// Equivalent to:
-  /// ```dart
+  /// ```
   /// Iterable<T> map<T>(T toElement(E e)) sync* {
   ///   for (var value in this) {
   ///     yield toElement(value);
   ///   }
   /// }
   /// ```
+  /// Example:
+  /// ```dart import:convert
+  /// var products = jsonDecode('''
+  /// [
+  ///   {"name": "Screwdriver", "price": 42.00},
+  ///   {"name": "Wingnut", "price": 0.50}
+  /// ]
+  /// ''');
+  /// var values = products.map((product) => product['price'] as double);
+  /// var totalPrice = values.fold(0.0, (a, b) => a + b); // 42.5.
+  /// ```
   Iterable<T> map<T>(T toElement(E e)) => MappedIterable<E, T>(this, toElement);
 
   /// Returns a new lazy [Iterable] with all elements that satisfy the
@@ -210,6 +228,14 @@ abstract class Iterable<E> {
   /// Iterating will not cache results, and thus iterating multiple times over
   /// the returned [Iterable] may invoke the supplied
   /// function [test] multiple times on the same element.
+  ///
+  /// Example:
+  /// ```dart
+  /// final numbers = <int>[1, 2, 3, 5, 6, 7];
+  /// var result = numbers.where((x) => x < 5); // (1, 2, 3)
+  /// result = numbers.where((x) => x > 5); // (6, 7)
+  /// result = numbers.where((x) => x.isEven); // (2, 6)
+  /// ```
   Iterable<E> where(bool test(E element)) => WhereIterable<E>(this, test);
 
   /// Returns a new lazy [Iterable] with all elements that have type [T].
@@ -233,17 +259,18 @@ abstract class Iterable<E> {
   ///
   /// Example:
   /// ```dart
-  /// var pairs = [[1, 2], [3, 4]];
-  /// var flattened = pairs.expand((pair) => pair).toList();
-  /// print(flattened); // => [1, 2, 3, 4];
-  ///
-  /// var input = [1, 2, 3];
-  /// var duplicated = input.expand((i) => [i, i]).toList();
-  /// print(duplicated); // => [1, 1, 2, 2, 3, 3]
+  /// Iterable<int> count(int n) sync* {
+  ///   for (var i = 1; i <= n; i++) {
+  ///     yield i;
+  ///    }
+  ///  }
+  ///
+  /// var numbers = [1, 3, 0, 2];
+  /// print(numbers.expand(count)); // (1, 1, 2, 3, 1, 2)
   /// ```
   ///
   /// Equivalent to:
-  /// ```dart
+  /// ```
   /// Iterable<T> expand<T>(Iterable<T> toElements(E e)) sync* {
   ///   for (var value in this) {
   ///     yield* toElements(value);
@@ -267,6 +294,15 @@ abstract class Iterable<E> {
   /// (see [Set.identity]) that its `contains` uses.
   /// Likewise the `Iterable` returned by a [Map.keys] call
   /// should use the same equality that the `Map` uses for keys.
+  ///
+  /// Example:
+  /// ```dart
+  /// final gasPlanets = <int, String>{1: 'Jupiter', 2: 'Saturn'};
+  /// final containsOne = gasPlanets.keys.contains(1); // true
+  /// final containsFive = gasPlanets.keys.contains(5); // false
+  /// final containsJupiter = gasPlanets.values.contains('Jupiter'); // true
+  /// final containsMercury = gasPlanets.values.contains('Mercury'); // false
+  /// ```
   bool contains(Object? element) {
     for (E e in this) {
       if (e == element) return true;
@@ -275,6 +311,16 @@ abstract class Iterable<E> {
   }
 
   /// Invokes [action] on each element of this iterable in iteration order.
+  ///
+  /// Example:
+  /// ```dart
+  /// final numbers = <int>[1, 2, 6, 7];
+  /// numbers.forEach(print);
+  /// // 1
+  /// // 2
+  /// // 6
+  /// // 7
+  /// ```
   void forEach(void action(E element)) {
     for (E element in this) action(element);
   }
@@ -288,7 +334,7 @@ abstract class Iterable<E> {
   /// Otherwise this method starts with the first element from the iterator,
   /// and then combines it with the remaining elements in iteration order,
   /// as if by:
-  /// ```dart
+  /// ```
   /// E value = iterable.first;
   /// iterable.skip(1).forEach((element) {
   ///   value = combine(value, element);
@@ -297,7 +343,9 @@ abstract class Iterable<E> {
   /// ```
   /// Example of calculating the sum of an iterable:
   /// ```dart
-  /// iterable.reduce((value, element) => value + element);
+  /// final numbers = <double>[10, 2, 5, 0.5];
+  /// final result = numbers.reduce((value, element) => value + element);
+  /// print(result); // 17.5
   /// ```
   E reduce(E combine(E value, E element)) {
     Iterator<E> iterator = this.iterator;
@@ -317,7 +365,7 @@ abstract class Iterable<E> {
   /// Uses [initialValue] as the initial value,
   /// then iterates through the elements and updates the value with
   /// each element using the [combine] function, as if by:
-  /// ```dart
+  /// ```
   /// var value = initialValue;
   /// for (E element in this) {
   ///   value = combine(value, element);
@@ -326,7 +374,11 @@ abstract class Iterable<E> {
   /// ```
   /// Example of calculating the sum of an iterable:
   /// ```dart
-  /// iterable.fold(0, (prev, element) => prev + element);
+  /// final numbers = <double>[10, 2, 5, 0.5];
+  /// const initialValue = 100.0;
+  /// final result = numbers.fold<double>(
+  ///     initialValue, (previousValue, element) => previousValue + element);
+  /// print(result); // 117.5
   /// ```
   T fold<T>(T initialValue, T combine(T previousValue, E element)) {
     var value = initialValue;
@@ -338,6 +390,14 @@ abstract class Iterable<E> {
   ///
   /// Checks every element in iteration order, and returns `false` if
   /// any of them make [test] return `false`, otherwise returns `true`.
+  ///
+  /// Example:
+  /// ```dart
+  /// final planetsByMass = <double, String>{0.06: 'Mercury', 0.81: 'Venus',
+  ///   0.11: 'Mars'};
+  /// // Checks whether all keys are smaller than 1.
+  /// final every = planetsByMass.keys.every((key) => key < 1.0); // true
+  /// ```
   bool every(bool test(E element)) {
     for (E element in this) {
       if (!test(element)) return false;
@@ -351,6 +411,13 @@ abstract class Iterable<E> {
   /// converts each one to a [String] by calling [Object.toString],
   /// and then concatenates the strings, with the
   /// [separator] string interleaved between the elements.
+  ///
+  /// Example:
+  /// ```dart
+  /// final planetsByMass = <double, String>{0.06: 'Mercury', 0.81: 'Venus',
+  ///   0.11: 'Mars'};
+  /// final joinedNames = planetsByMass.values.join('-'); // Mercury-Venus-Mars
+  /// ```
   String join([String separator = ""]) {
     Iterator<E> iterator = this.iterator;
     if (!iterator.moveNext()) return "";
@@ -373,6 +440,13 @@ abstract class Iterable<E> {
   ///
   /// Checks every element in iteration order, and returns `true` if
   /// any of them make [test] return `true`, otherwise returns false.
+  ///
+  /// Example:
+  /// ```dart
+  /// final numbers = <int>[1, 2, 3, 5, 6, 7];
+  /// var result = numbers.any((element) => element >= 5); // true;
+  /// result = numbers.any((element) => element >= 10); // false;
+  /// ```
   bool any(bool test(E element)) {
     for (E element in this) {
       if (test(element)) return true;
@@ -384,6 +458,14 @@ abstract class Iterable<E> {
   ///
   /// The elements are in iteration order.
   /// The list is fixed-length if [growable] is false.
+  ///
+  /// Example:
+  /// ```dart
+  /// final planets = <int, String>{1: 'Mercury', 2: 'Venus', 3: 'Mars'};
+  /// final keysList = planets.keys.toList(growable: false); // [1, 2, 3]
+  /// final valuesList =
+  ///     planets.values.toList(growable: false); // [Mercury, Venus, Mars]
+  /// ```
   List<E> toList({bool growable = true}) {
     return List<E>.of(this, growable: growable);
   }
@@ -395,6 +477,12 @@ abstract class Iterable<E> {
   /// or it contains one or more elements that are equal.
   /// The order of the elements in the set is not guaranteed to be the same
   /// as for the iterable.
+  ///
+  /// Example:
+  /// ```dart
+  /// final planets = <int, String>{1: 'Mercury', 2: 'Venus', 3: 'Mars'};
+  /// final valueSet = planets.values.toSet(); // {Mercury, Venus, Mars}
+  /// ```
   Set<E> toSet() => Set<E>.of(this);
 
   /// Returns the number of elements in [this].
@@ -415,11 +503,25 @@ abstract class Iterable<E> {
   /// Whether this collection has no elements.
   ///
   /// May be computed by checking if `iterator.moveNext()` returns `false`.
+  ///
+  /// Example:
+  /// ```dart
+  /// final emptyList = <int>[];
+  /// print(emptyList.isEmpty); // true;
+  /// print(emptyList.iterator.moveNext()); // false
+  /// ```
   bool get isEmpty => !iterator.moveNext();
 
   /// Whether this collection has at least one element.
   ///
   /// May be computed by checking if `iterator.moveNext()` returns `true`.
+  ///
+  /// Example:
+  /// ```dart
+  /// final numbers = <int>{1, 2, 3};
+  /// print(numbers.isNotEmpty); // true;
+  /// print(numbers.iterator.moveNext()); // true
+  /// ```
   bool get isNotEmpty => !isEmpty;
 
   /// Returns a lazy iterable of the [count] first elements of this iterable.
@@ -431,6 +533,13 @@ abstract class Iterable<E> {
   /// elements have been seen.
   ///
   /// The `count` must not be negative.
+  ///
+  /// Example:
+  /// ```dart
+  /// final numbers = <int>[1, 2, 3, 5, 6, 7];
+  /// final result = numbers.take(4); // (1, 2, 3, 5)
+  /// final takeAll = numbers.take(100); // (1, 2, 3, 5, 6, 7)
+  /// ```
   Iterable<E> take(int count) {
     return TakeIterable<E>(this, count);
   }
@@ -443,6 +552,15 @@ abstract class Iterable<E> {
   /// The elements can be computed by stepping through [iterator] until an
   /// element is found where `test(element)` is false. At that point,
   /// the returned iterable stops (its `moveNext()` returns false).
+  ///
+  /// Example:
+  /// ```dart
+  /// final numbers = <int>[1, 2, 3, 5, 6, 7];
+  /// var result = numbers.takeWhile((x) => x < 5); // (1, 2, 3)
+  /// result = numbers.takeWhile((x) => x != 3); // (1, 2)
+  /// result = numbers.takeWhile((x) => x != 4); // (1, 2, 3, 5, 6, 7)
+  /// result = numbers.takeWhile((x) => x.isOdd); // (1)
+  /// ```
   Iterable<E> takeWhile(bool test(E value)) {
     return TakeWhileIterable<E>(this, test);
   }
@@ -460,6 +578,13 @@ abstract class Iterable<E> {
   /// through earlier elements, for example when iterating a [List].
   /// Such iterables are allowed to ignore the initial skipped elements.
   ///
+  /// Example:
+  /// ```dart
+  /// final numbers = <int>[1, 2, 3, 5, 6, 7];
+  /// final result = numbers.skip(4); // (6, 7)
+  /// final skipAll = numbers.skip(100); // () - no elements.
+  /// ```
+  ///
   /// The [count] must not be negative.
   Iterable<E> skip(int count) {
     return SkipIterable<E>(this, count);
@@ -475,6 +600,15 @@ abstract class Iterable<E> {
   /// true. If all elements satisfy `test` the resulting iterable is empty,
   /// otherwise it iterates the remaining elements in their original order,
   /// starting with the first element for which `test(element)` returns `false`.
+  ///
+  /// Example:
+  /// ```dart
+  /// final numbers = <int>[1, 2, 3, 5, 6, 7];
+  /// var result = numbers.skipWhile((x) => x < 5); // (5, 6, 7)
+  /// result = numbers.skipWhile((x) => x != 3); // (3, 5, 6, 7)
+  /// result = numbers.skipWhile((x) => x != 4); // ()
+  /// result = numbers.skipWhile((x) => x.isOdd); // (2, 3, 5, 6, 7)
+  /// ```
   Iterable<E> skipWhile(bool test(E value)) {
     return SkipWhileIterable<E>(this, test);
   }
@@ -527,6 +661,15 @@ abstract class Iterable<E> {
   ///
   /// Iterates through elements and returns the first to satisfy [test].
   ///
+  /// Example:
+  /// ```dart
+  /// final numbers = <int>[1, 2, 3, 5, 6, 7];
+  /// var result = numbers.firstWhere((element) => element < 5); // 1
+  /// result = numbers.firstWhere((element) => element > 5); // 6
+  /// result =
+  ///     numbers.firstWhere((element) => element > 10, orElse: () => -1); // -1
+  /// ```
+  ///
   /// If no element satisfies [test], the result of invoking the [orElse]
   /// function is returned.
   /// If [orElse] is omitted, it defaults to throwing a [StateError].
@@ -547,6 +690,15 @@ abstract class Iterable<E> {
   /// checks `test(element)` for each,
   /// and finally returns that last one that matched.
   ///
+  /// Example:
+  /// ```dart
+  /// final numbers = <int>[1, 2, 3, 5, 6, 7];
+  /// var result = numbers.lastWhere((element) => element < 5); // 3
+  /// result = numbers.lastWhere((element) => element > 5); // 7
+  /// result = numbers.lastWhere((element) => element > 10,
+  ///     orElse: () => -1); // -1
+  /// ```
+  ///
   /// If no element satisfies [test], the result of invoking the [orElse]
   /// function is returned.
   /// If [orElse] is omitted, it defaults to throwing a [StateError].
@@ -571,6 +723,22 @@ abstract class Iterable<E> {
   /// If more than one matching element is found, throws [StateError].
   /// If no matching element is found, returns the result of [orElse].
   /// If [orElse] is omitted, it defaults to throwing a [StateError].
+  ///
+  /// Example:
+  /// ```dart
+  /// final numbers = <int>[2, 2, 10];
+  /// var result = numbers.singleWhere((element) => element > 5); // 10
+  /// ```
+  /// When no matching element is found, the result of calling [orElse] is
+  /// returned instead.
+  /// ```dart continued
+  /// result = numbers.singleWhere((element) => element == 1,
+  ///     orElse: () => -1); // -1
+  /// ```
+  /// There must not be more than one matching element.
+  /// ```dart continued
+  /// result = numbers.singleWhere((element) => element == 2); // Throws Error.
+  /// ```
   E singleWhere(bool test(E element), {E orElse()?}) {
     late E result;
     bool foundMatching = false;
@@ -597,6 +765,12 @@ abstract class Iterable<E> {
   /// May iterate through the elements in iteration order, ignoring the
   /// first [index] elements and then returning the next.
   /// Some iterables may have a more efficient way to find the element.
+  ///
+  /// Example:
+  /// ```dart
+  /// final numbers = <int>[1, 2, 3, 5, 6, 7];
+  /// final elementAt = numbers.elementAt(4); // 6
+  /// ```
   E elementAt(int index) {
     RangeError.checkNotNegative(index, "index");
     int elementIndex = 0;