List/Iterable - The Safety Net

Your collections deserve protection. Use null-aware extensions to access list ends and indices without ever crashing your app with a RangeError or StateError.

1. 🔝 Ends of the List

   firstOrNull · T?

   Gets the first element of the list, or returns null if the list is empty. Prevents StateError.

   final numbers = [1, 2, 3];
   final result = numbers.firstOrNull;  // 1
   
   final alphabets = [];
   final last = alphabets.firstOrNull; // null
   

   lastOrNull · T?

   Gets the last element of the list, or returns null if the list is empty. Prevents StateError.

   final names = ['Alice', 'Bob'];
   final last = names.lastOrNull; // 'Bob'
   
   final ids = [];
   final last = ids.lastOrNull; // null
   
2. 🔍 Index & Element Access

   elementAtOrNull(int index) · T?

   Show Parameters

   index · int · required

   The zero-based index of the element to retrieve.

   Safely retrieves an element at a given index, returning null if the index is out of bounds. Prevents RangeError.

   final data = ['a', 'b', 'c'];
   final safe = data.elementAtOrNull(10); // null
   

   indexOfOrNull(T element) · int?

   Show Parameters

   element · T · required

   The element to locate in the list.

   Gets the index of the element, or returns null if the element doesn’t exist in the list.

   final ids = [10, 20, 30];
   final notFound = ids.indexOfOrNull(50); // null
   

   firstWhereOrNull(bool Function(T) test) · T?

   Show Parameters

   test · bool Function(T) · required

   A function that returns true for the element you are looking for.

   Gets the first element that satisfies the test, or returns null if none is found. Prevents StateError without needing an orElse callback.

   final users = [{'id': 1}, {'id': 2}];
   final missing = users.firstWhereOrNull((u) => u['id'] == 99); // null