Add elementAtOrNull extensions (#217)

Add extensions on List and Iterable to read an element without risk of
exceptions.

CHANGELOG.md

@@ -1,4 +1,6 @@
-## 1.16.1-dev
+## 1.17.0-dev
+
+* Add `Iterable.elementAtOrNull` and `List.elementAtOrNull` extension methods.
 
 * Add a top-level `lastBy()` function that converts an `Iterable` to a `Map` by
   grouping its elements using a function, keeping the last element for each

lib/src/iterable_extensions.dart

@@ -354,6 +354,17 @@ extension IterableExtension<T> on Iterable<T> {
     return null;
   }
 
+  /// The [index]th element, or `null` if there is no such element.
+  ///
+  /// Returns the element at position [index] of this iterable,
+  /// just like [elementAt], if this iterable has such an element.
+  /// If this iterable does not have enough elements to have one with the given
+  /// [index], the `null` value is returned, unlike [elementAt] which throws
+  /// instead.
+  ///
+  /// The [index] must not be negative.
+  T? elementAtOrNull(int index) => skip(index).firstOrNull;
+
   /// Associates the elements in [this] by the value returned by [key].
   ///
   /// Returns a map from keys computed by [key] to the last value for which [key]

lib/src/list_extensions.dart

@@ -259,6 +259,17 @@ extension ListExtensions<E> on List<E> {
     return true;
   }
 
+  /// The [index]th element, or `null` if there is no such element.
+  ///
+  /// Returns the element at position [index] of this list,
+  /// just like [elementAt], if this list has such an element.
+  /// If this list does not have enough elements to have one with the given
+  /// [index], the `null` value is returned, unlike [elementAt] which throws
+  /// instead.
+  ///
+  /// The [index] must not be negative.
+  E? elementAtOrNull(int index) => (index < length) ? this[index] : null;
+
   /// Contiguous [slice]s of [this] with the given [length].
   ///
   /// Each slice is a view of this list [length] elements long, except for the

pubspec.yaml

@@ -1,5 +1,5 @@
 name: collection
-version: 1.16.1-dev
+version: 1.17.0-dev
 
 description: Collections and utilities functions and classes related to collections.
 repository: https://github.com/dart-lang/collection

test/extensions_test.dart

@@ -1160,6 +1160,21 @@ void main() {
         }
       });
     });
+    group('.elementAtOrNull', () {
+      test('empty', () async {
+        expect(iterable([]).elementAtOrNull(0), isNull);
+      });
+      test('negative index', () async {
+        expect(() => iterable([1]).elementAtOrNull(-1),
+            throwsA(isA<RangeError>()));
+      });
+      test('index within range', () async {
+        expect(iterable([1]).elementAtOrNull(0), 1);
+      });
+      test('index too high', () async {
+        expect(iterable([1]).elementAtOrNull(1), isNull);
+      });
+    });
     group('.slices', () {
       test('empty', () {
         expect(iterable(<int>[]).slices(1), []);
@@ -1748,6 +1763,20 @@ void main() {
               ['1', 'b']);
         });
       });
+      group('.elementAtOrNull', () {
+        test('empty', () async {
+          expect([].elementAtOrNull(0), isNull);
+        });
+        test('negative index', () async {
+          expect(() => [1].elementAtOrNull(-1), throwsA(isA<RangeError>()));
+        });
+        test('index within range', () async {
+          expect([1].elementAtOrNull(0), 1);
+        });
+        test('index too high', () async {
+          expect([1].elementAtOrNull(1), isNull);
+        });
+      });
       group('.slices', () {
         test('empty', () {
           expect(<int>[].slices(1), []);