Iterable Extensions #

A comprehensive collection of useful extension methods for Dart's Iterable<T> class. These extensions provide null-safe alternatives to common operations, collection utilities, and functional programming helpers that make working with iterables more convenient and expressive.

Features #

🛡️ Null-safe operations - Safe alternatives to methods that throw exceptions
🔍 Enhanced filtering - Advanced filtering and search capabilities
📊 Collection utilities - Grouping, chunking, and distinct operations
🧮 Mathematical operations - Sum, average, min/max with null safety
🔄 Transformation helpers - Convenient ways to transform and combine iterables
📈 Performance focused - Lazy evaluation where possible

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  iterable_extensions: ^1.0.0

Then run:

dart pub get

Usage #

Import the package and the extension methods will be automatically available on all Iterable<T> instances:

import 'package:iterable_extensions/iterable_extensions.dart';

void main() {
  final numbers = [1, 2, 3, 4, 5];
  
  // Null-safe operations
  final firstEven = numbers.firstWhereOrNull((n) => n.isEven); // 2
  final elementAt10 = numbers.elementAtOrNull(10); // null
  
  // Collection utilities
  final grouped = numbers.groupBy((n) => n.isEven ? 'even' : 'odd');
  // {'odd': [1, 3, 5], 'even': [2, 4]}
  
  // Mathematical operations
  final sum = numbers.sum(); // 15
  final average = numbers.average; // 3.0
}

Extension Methods #

Null-Safe Operations #

Replace exception-throwing methods with null-returning alternatives:

final numbers = [1, 2, 3, 4, 5];
final empty = <int>[];

// Safe element access
final first = numbers.firstOrNull; // 1
final emptyFirst = empty.firstOrNull; // null

// Safe conditional access
final firstEven = numbers.firstWhereOrNull((n) => n.isEven); // 2
final firstNegative = numbers.firstWhereOrNull((n) => n < 0); // null

// Safe index access
final third = numbers.elementAtOrNull(2); // 3
final outOfBounds = numbers.elementAtOrNull(10); // null

Collection Utilities #

Group, chunk, and manipulate collections easily:

final words = ['apple', 'banana', 'apricot', 'blueberry'];

// Group by criteria
final byFirstLetter = words.groupBy((word) => word[0]);
// {'a': ['apple', 'apricot'], 'b': ['banana', 'blueberry']}

// Remove duplicates
final numbers = [1, 2, 2, 3, 3, 4];
final unique = numbers.distinct.toList(); // [1, 2, 3, 4]

// Split into chunks
final chunks = numbers.chunked(2).toList(); // [[1, 2], [2, 3], [3, 4]]

Mathematical Operations #

Perform calculations with null safety:

final numbers = [1, 2, 3, 4, 5];
final empty = <int>[];

// Sum and average
final total = numbers.sum(); // 15
final avg = numbers.average; // 3.0
final emptySum = empty.sumOrNull; // null

// Min and max
final min = numbers.minOrNull; // 1
final max = numbers.maxOrNull; // 5

// Min/max by selector
final words = ['apple', 'banana', 'cherry'];
final shortest = words.minByOrNull((w) => w.length); // 'apple'
final longest = words.maxByOrNull((w) => w.length); // 'banana'

Functional Operations #

Enhanced functional programming support:

final numbers = [2, 4, 6, 8];

// Enhanced predicates
final allEven = numbers.all((n) => n.isEven); // true
final noneOdd = numbers.none((n) => n.isOdd); // true

// Combine iterables
final first = [1, 2, 3];
final second = [4, 5, 6];
final combined = (first + second).toList(); // [1, 2, 3, 4, 5, 6]

// Indexed operations
numbers.forEachIndexed((index, value) {
  print('$index: $value');
});

final indexed = numbers.indexed.toList();
// [MapEntry(0, 2), MapEntry(1, 4), MapEntry(2, 6), MapEntry(3, 8)]

Complete Method Reference #

Performance Notes #

• Most methods use lazy evaluation and don't materialize collections unnecessarily
• reversed materializes the iterable into a list first
• chunked() yields chunks as they're created
• Mathematical operations (sum, average) work only with numeric types

Contributing #

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License #

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog #

See CHANGELOG.md for a detailed history of changes.