List/Iterable - Transformations & Sorting

Functional utilities for complex list mapping, efficient sorting by property (selector), chunking for pagination, and creating shuffled copies.

1. 🗺️ Mapping & Filtering

   mapIndexed<R>(R Function(int index, T item) mapper) · List<R>

   Show Parameters

   mapper · R Function(int index, T item) · required

   A function that accepts the index and the item, returning a new value.

   Maps the list, providing the element’s index along with the item to the mapper function. Perfect for generating indexed widgets.

   final names = ['Alice', 'Bob'];
   final widgets = names.mapIndexed((i, name) => Text('No. $i: $name'));
   

   mapNotNull<R>(R? Function(T item) mapper) · List<R>

   Show Parameters

   mapper · R? Function(T item) · required

   A function that transforms the item into a potentially nullable value.

   Maps the list and automatically filters out all resulting null values, guaranteeing a non-nullable output list.

   final grades = [85, 40];
   final passing = grades.mapNotNull((g) => g >= 50 ? g : null); // [85]
   

2. 🔄 Sorting & Order

   reversedList · List<T>

   Gets a new list containing the elements of the original list in reverse order.

   final original = [1, 2, 3];
   final reversed = original.reversedList; // [3, 2, 1]
   

   sortBy(Comparable Function(T) selector, {bool ascending}) · void

   Show Parameters

   selector · Comparable Function(T) · required

   A function that returns a Comparable property (e.g., int, String) by which to sort.

   ascending · bool · default: "true"

   If true, sorts from smallest to largest; otherwise, largest to smallest.

   Sorts the list in-place (mutates the original list) based on a selected property.

   // Sorts by score in ascending order (10, 20)
   users.sortBy((user) => user.score);
   

   Mutates the original list

   sortByAndReturnSorted(Comparable Function(T) selector, {bool ascending}) · List<T>

   Show Parameters

   selector · Comparable Function(T) · required

   A function that returns a Comparable property (e.g., int, String) by which to sort.

   ascending · bool · default: "true"

   If true, sorts from smallest to largest; otherwise, largest to smallest.

   Sorts the list based on a selected property and returns a new sorted list. The original list remains unchanged.

   final originalScores = [10, 50, 20];
   final topScores = originalScores.sortByAndReturnSorted((s) => s, ascending: false);
   

   Returns a new sorted list. The original list remains unchanged.

3. ✂️ Structural Changes

   chunked(int chunkSize) · List<List<T>>

   Show Parameters

   chunkSize · int · required

   The maximum size for each chunk. Must be greater than 0.

   Splits the list into smaller sub-lists (chunks) of a maximum specified size. Highly useful for pagination or multi-column layouts.

   final items = [1, 2, 3, 4, 5, 6, 7];
   final chunks = items.chunked(3); // "chunks is [[1, 2, 3], [4, 5, 6], [7]]"