├── .github ├── dependabot.yaml └── workflows │ └── dart.yml ├── .gitignore ├── AUTHORS ├── CHANGELOG.md ├── LICENSE ├── README.md ├── analysis_options.yaml ├── contributing.md ├── example └── main.dart ├── lib ├── basics.dart ├── comparable_basics.dart ├── date_time_basics.dart ├── int_basics.dart ├── iterable_basics.dart ├── list_basics.dart ├── map_basics.dart ├── set_basics.dart ├── src │ ├── slice_indices.dart │ └── sort_key_compare.dart └── string_basics.dart ├── pubspec.yaml └── test ├── comparable_basics_test.dart ├── date_time_basics_test.dart ├── int_basics_test.dart ├── iterable_basics_test.dart ├── list_basics_test.dart ├── map_basics_test.dart ├── set_basics_test.dart └── string_basics_test.dart /.github/dependabot.yaml: -------------------------------------------------------------------------------- 1 | # Dependabot configuration file. 2 | version: 2 3 | enable-beta-ecosystems: true 4 | 5 | updates: 6 | - package-ecosystem: "github-actions" 7 | directory: "/" 8 | schedule: 9 | interval: "monthly" 10 | -------------------------------------------------------------------------------- /.github/workflows/dart.yml: -------------------------------------------------------------------------------- 1 | name: Dart CI 2 | 3 | on: 4 | schedule: 5 | # “At 00:00 (UTC) on Sunday.” 6 | - cron: '0 0 * * 0' 7 | push: 8 | branches: [ master ] 9 | pull_request: 10 | branches: [ master ] 11 | 12 | jobs: 13 | build: 14 | runs-on: ${{ matrix.os }} 15 | strategy: 16 | fail-fast: false 17 | matrix: 18 | os: [ubuntu-latest] 19 | sdk: [2.17.0, stable, dev] 20 | 21 | name: build on ${{ matrix.os }} for ${{ matrix.sdk }} 22 | 23 | steps: 24 | - uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c 25 | - uses: dart-lang/setup-dart@a57a6c04cf7d4840e88432aad6281d1e125f0d46 26 | 27 | - name: Install dependencies 28 | run: dart pub get 29 | 30 | - name: Verify formatting 31 | run: dart format --output=none --set-exit-if-changed . 32 | 33 | - name: Analyze project source 34 | run: dart analyze --fatal-infos 35 | 36 | - name: Run tests 37 | run: dart test 38 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Reference: 2 | 3 | # pub stuff. 4 | .dart_tool/ 5 | .packages 6 | build/ 7 | .pub/ 8 | pubspec.lock 9 | doc/api/ 10 | 11 | # IntelliJ stuff. 12 | *.iml 13 | *.ipr 14 | *.iws 15 | .idea 16 | 17 | # macOS stuff. 18 | .DS_Store 19 | 20 | .vscode/launch.json 21 | -------------------------------------------------------------------------------- /AUTHORS: -------------------------------------------------------------------------------- 1 | # Below is a list of people and organizations that have contributed 2 | # to the Dart Basics project. Names should be added to the list like so: 3 | # 4 | # Name/Organization 5 | 6 | Google Inc. 7 | MH Johnson 8 | Zachary Garcia 9 | eikob 10 | Tianguang 11 | James Lin 12 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | ## [0.10.0] 2 | 3 | * Added `truncate` method to `String`. 4 | * Added `capitalize` method to `String`. 5 | 6 | ## [0.9.0] 7 | 8 | * Added `average` method to `Iterable`. 9 | 10 | ## [0.8.1] 11 | 12 | * Added stricter type checks. 13 | 14 | ## [0.8.0] 15 | 16 | * Added `ComparableBasics`. 17 | * Added `getRange` to `Iterable`. 18 | * Added `isNullOrBlank` and `isNotNullOrBlank` to `String?` 19 | * Improved performance of `maxBy`, `minBy` and `sortBy` by adding a cache. 20 | 21 | ## [0.7.0] 22 | 23 | Added `copyWith`, `addCalendarDays`, and `calendarDaysTill` to `DateTimeBasics`. 24 | 25 | ## [0.6.0] 26 | 27 | Remove object basics (`isNull` and `isNotNull`). 28 | 29 | ## [0.5.1] 30 | 31 | Update docs. 32 | 33 | ## [0.5.0] 34 | 35 | Updated with null safety. 36 | 37 | ## [0.4.0] 38 | 39 | Added `MapBasics.get`. 40 | 41 | ## [0.3.0] 42 | 43 | Added `DateTimeBasics`. 44 | 45 | ## [0.2.0] - 2020-04-24 46 | 47 | Add example and changelog. 48 | 49 | ## [0.1.0] - 2020-04-24 50 | 51 | Initial release. 52 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (c) 2019, Google. 2 | All rights reserved. 3 | 4 | Redistribution and use in source and binary forms, with or without 5 | modification, are permitted provided that the following conditions are met: 6 | * Redistributions of source code must retain the above copyright 7 | notice, this list of conditions and the following disclaimer. 8 | * Redistributions in binary form must reproduce the above copyright 9 | notice, this list of conditions and the following disclaimer in the 10 | documentation and/or other materials provided with the distribution. 11 | * Neither the name of the nor the 12 | names of its contributors may be used to endorse or promote products 13 | derived from this software without specific prior written permission. 14 | 15 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 16 | ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 17 | WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 18 | DISCLAIMED. IN NO EVENT SHALL BE LIABLE FOR ANY 19 | DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 20 | (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 21 | LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 22 | ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23 | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 24 | SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | [![Dart CI](https://github.com/google/dart-basics/actions/workflows/dart.yml/badge.svg)](https://github.com/google/dart-basics/actions/workflows/dart.yml) 2 | [![pub package](https://img.shields.io/pub/v/basics.svg)](https://pub.dev/packages/basics) 3 | [![package publisher](https://img.shields.io/pub/publisher/basics.svg)](https://pub.dev/packages/basics/publisher) 4 | 5 | This repository contains a collection of useful extension methods on the 6 | built-in objects in Dart, such as String, Iterable, and Object. 7 | 8 | ## Usage 9 | Import the basics library. 10 | 11 | ```dart 12 | import 'package:basics/basics.dart'; 13 | ``` 14 | 15 | Then use the methods directly on objects in your dart code. 16 | 17 | ```dart 18 | import 'package:basics/basics.dart'; 19 | 20 | main() async { 21 | const numbers = [2, 4, 8]; 22 | 23 | if (numbers.all((n) => n.isEven)) { 24 | print('All numbers are even.'); 25 | } 26 | 27 | print('sum of numbers is: ${numbers.sum()}'); 28 | 29 | for (var _ in 5.range) { 30 | print('waiting 500 milliseconds...'); 31 | await Future.delayed(500.milliseconds); 32 | } 33 | } 34 | ``` 35 | 36 | ## Notes 37 | This is not an official Google project. 38 | 39 | -------------------------------------------------------------------------------- /analysis_options.yaml: -------------------------------------------------------------------------------- 1 | include: package:pedantic/analysis_options.1.8.0.yaml 2 | 3 | analyzer: 4 | language: 5 | strict-casts: true 6 | strict-inference: true 7 | strict-raw-types: true 8 | 9 | linter: 10 | rules: 11 | - avoid_types_on_closure_parameters 12 | - avoid_void_async 13 | - await_only_futures 14 | - camel_case_types 15 | - cancel_subscriptions 16 | - close_sinks 17 | - constant_identifier_names 18 | - control_flow_in_finally 19 | - directives_ordering 20 | - empty_statements 21 | - hash_and_equals 22 | - implementation_imports 23 | - non_constant_identifier_names 24 | - package_api_docs 25 | - package_names 26 | - package_prefixed_library_names 27 | - test_types_in_equals 28 | - throw_in_finally 29 | - unnecessary_brace_in_string_interps 30 | - unnecessary_getters_setters 31 | - unnecessary_new 32 | - unnecessary_statements 33 | -------------------------------------------------------------------------------- /contributing.md: -------------------------------------------------------------------------------- 1 | # How to Contribute 2 | 3 | We'd love to accept your patches and contributions to this project. There are 4 | just a few small guidelines you need to follow. 5 | 6 | ## Contributor License Agreement 7 | 8 | Contributions to this project must be accompanied by a Contributor License 9 | Agreement. You (or your employer) retain the copyright to your contribution; 10 | this simply gives us permission to use and redistribute your contributions as 11 | part of the project. Head over to to see 12 | your current agreements on file or to sign a new one. 13 | 14 | You generally only need to submit a CLA once, so if you've already submitted one 15 | (even if it was for a different project), you probably don't need to do it 16 | again. 17 | 18 | ## Code reviews 19 | 20 | All submissions, including submissions by project members, require review. We 21 | use GitHub pull requests for this purpose. Consult 22 | [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more 23 | information on using pull requests. 24 | 25 | ## Community Guidelines 26 | 27 | This project follows [Google's Open Source Community 28 | Guidelines](https://opensource.google/conduct/). 29 | -------------------------------------------------------------------------------- /example/main.dart: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2020, Google Inc. Please see the AUTHORS file for details. 2 | // All rights reserved. Use of this source code is governed by a BSD-style 3 | // license that can be found in the LICENSE file. 4 | 5 | import 'package:basics/basics.dart'; 6 | 7 | void main() async { 8 | const numbers = [2, 4, 8]; 9 | 10 | if (numbers.all((n) => n.isEven)) { 11 | print('All numbers are even.'); 12 | } 13 | 14 | print('sum of numbers is: ${numbers.sum()}'); 15 | 16 | for (var _ in 5.range) { 17 | print('waiting 500 milliseconds...'); 18 | await Future.delayed(500.milliseconds); 19 | } 20 | } 21 | -------------------------------------------------------------------------------- /lib/basics.dart: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2019, Google Inc. Please see the AUTHORS file for details. 2 | // All rights reserved. Use of this source code is governed by a BSD-style 3 | // license that can be found in the LICENSE file. 4 | 5 | export 'date_time_basics.dart'; 6 | export 'int_basics.dart'; 7 | export 'iterable_basics.dart'; 8 | export 'list_basics.dart'; 9 | export 'map_basics.dart'; 10 | export 'set_basics.dart'; 11 | export 'string_basics.dart'; 12 | -------------------------------------------------------------------------------- /lib/comparable_basics.dart: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2022, Google Inc. Please see the AUTHORS file for details. 2 | // All rights reserved. Use of this source code is governed by a BSD-style 3 | // license that can be found in the LICENSE file. 4 | 5 | import 'dart:math' as math show min, max; 6 | 7 | /// Utility extension methods for the [Comparable] class. 8 | extension ComparableBasics on Comparable { 9 | /// Returns true if [this] should be ordered strictly before [other]. 10 | bool operator <(T other) => compareTo(other) < 0; 11 | 12 | /// Returns true if [this] should be ordered strictly after [other]. 13 | bool operator >(T other) => compareTo(other) > 0; 14 | 15 | /// Returns true if [this] should be ordered before or with [other]. 16 | bool operator <=(T other) => compareTo(other) <= 0; 17 | 18 | /// Returns true if [this] should be ordered after or with [other]. 19 | bool operator >=(T other) => compareTo(other) >= 0; 20 | } 21 | 22 | /// Returns the greater of two [Comparable] objects. 23 | /// 24 | /// For [num] values, behaves identically to [math.max]. 25 | /// 26 | /// If the arguments compare equal, then it is unspecified which of the two 27 | /// arguments is returned. 28 | T max>(T a, T b) { 29 | if (a is num) { 30 | return math.max(a, b as num) as T; 31 | } 32 | return (a >= b) ? a : b; 33 | } 34 | 35 | /// Returns the lesser of two [Comparable] objects. 36 | /// 37 | /// For [num] values, behaves identically to [math.min]. 38 | /// 39 | /// If the arguments compare equal, then it is unspecified which of the two 40 | /// arguments is returned. 41 | T min>(T a, T b) { 42 | if (a is num) { 43 | return math.min(a, b as num) as T; 44 | } 45 | return (a <= b) ? a : b; 46 | } 47 | -------------------------------------------------------------------------------- /lib/date_time_basics.dart: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2020, Google Inc. Please see the AUTHORS file for details. 2 | // All rights reserved. Use of this source code is governed by a BSD-style 3 | // license that can be found in the LICENSE file. 4 | 5 | /// Utility extension methods for the core [DateTime] class. 6 | extension DateTimeBasics on DateTime { 7 | /// Returns true if [this] occurs strictly before [other], accounting for time 8 | /// zones. 9 | /// 10 | /// Alias for [DateTime.isBefore]. 11 | /// 12 | /// Note that attempting to use this operator with [DateTime.==] will likely 13 | /// give undesirable results. This operator compares moments (i.e. with time 14 | /// zone taken into account), while [DateTime.==] compares field values (i.e. 15 | /// two [DateTime]s representing the same moment in different time zones will 16 | /// be treated as not equal). To check moment equality with time zone taken 17 | /// into account, use [DateTime.isAtSameMomentAs] rather than [DateTime.==]. 18 | bool operator <(DateTime other) => isBefore(other); 19 | 20 | /// Returns true if [this] occurs strictly after [other], accounting for time 21 | /// zones. 22 | /// 23 | /// Alias for [DateTime.isAfter]. 24 | /// 25 | /// Note that attempting to use this operator with [DateTime.==] will likely 26 | /// give undesirable results. This operator compares moments (i.e. with time 27 | /// zone taken into account), while [DateTime.==] compares field values (i.e. 28 | /// two [DateTime]s representing the same moment in different time zones will 29 | /// be treated as not equal). To check moment equality with time zone taken 30 | /// into account, use [DateTime.isAtSameMomentAs] rather than [DateTime.==]. 31 | bool operator >(DateTime other) => isAfter(other); 32 | 33 | /// Returns true if [this] occurs at or before [other], accounting for time 34 | /// zones. 35 | /// 36 | /// Alias for [isAtOrBefore]. 37 | /// 38 | /// Note that attempting to use this operator with [DateTime.==] will likely 39 | /// give undesirable results. This operator compares moments (i.e. with time 40 | /// zone taken into account), while [DateTime.==] compares field values (i.e. 41 | /// two [DateTime]s representing the same moment in different time zones will 42 | /// be treated as not equal). To check moment equality with time zone taken 43 | /// into account, use [DateTime.isAtSameMomentAs] rather than [DateTime.==]. 44 | bool operator <=(DateTime other) => isAtOrBefore(other); 45 | 46 | /// Returns true if [this] occurs at or after [other], accounting for time 47 | /// zones. 48 | /// 49 | /// Alias for [isAtOrAfter]. 50 | /// 51 | /// Note that attempting to use this operator with [DateTime.==] will likely 52 | /// give undesirable results. This operator compares moments (i.e. with time 53 | /// zone taken into account), while [DateTime.==] compares field values (i.e. 54 | /// two [DateTime]s representing the same moment in different time zones will 55 | /// be treated as not equal). To check moment equality with time zone taken 56 | /// into account, use [DateTime.isAtSameMomentAs] rather than [DateTime.==]. 57 | bool operator >=(DateTime other) => isAtOrAfter(other); 58 | 59 | /// Returns a new [DateTime] instance with [duration] added to [this]. 60 | /// 61 | /// Alias for [DateTime.add]. 62 | DateTime operator +(Duration duration) => add(duration); 63 | 64 | /// Returns the [Duration] between [this] and [other]. 65 | /// 66 | /// The returned [Duration] will be negative if [other] occurs after [this]. 67 | /// 68 | /// Alias for [DateTime.difference]. 69 | Duration operator -(DateTime other) => difference(other); 70 | 71 | /// Returns true if [this] occurs at or before [other], accounting for time 72 | /// zones. 73 | /// 74 | /// Delegates to [DateTime]'s built-in comparison methods and therefore obeys 75 | /// the same contract. 76 | bool isAtOrBefore(DateTime other) => 77 | isAtSameMomentAs(other) || isBefore(other); 78 | 79 | /// Returns true if [this] occurs at or after [other], accounting for time 80 | /// zones. 81 | /// 82 | /// Delegates to [DateTime]'s built-in comparison methods and therefore obeys 83 | /// the same contract. 84 | bool isAtOrAfter(DateTime other) => isAtSameMomentAs(other) || isAfter(other); 85 | 86 | /// Copies a [DateTime], overriding specified values. 87 | /// 88 | /// A UTC [DateTime] will remain in UTC; a local [DateTime] will remain local. 89 | DateTime copyWith({ 90 | int? year, 91 | int? month, 92 | int? day, 93 | int? hour, 94 | int? minute, 95 | int? second, 96 | int? millisecond, 97 | int? microsecond, 98 | }) { 99 | return (isUtc ? DateTime.utc : DateTime.new)( 100 | year ?? this.year, 101 | month ?? this.month, 102 | day ?? this.day, 103 | hour ?? this.hour, 104 | minute ?? this.minute, 105 | second ?? this.second, 106 | millisecond ?? this.millisecond, 107 | microsecond ?? this.microsecond, 108 | ); 109 | } 110 | 111 | /// Adds a specified number of days to this [DateTime]. 112 | /// 113 | /// Unlike `DateTime.add(Duration(days: numberOfDays))`, this adds calendar 114 | /// days and not 24-hour increments. When possible, it therefore leaves the 115 | /// time of day unchanged if a DST change would occur during the time 116 | /// interval. (The returned time can still be different from the original if 117 | /// it would be invalid for the returned date.) 118 | DateTime addCalendarDays(int numberOfDays) => 119 | copyWith(day: day + numberOfDays); 120 | 121 | /// Returns the number of calendar days till the specified date. 122 | /// 123 | /// Returns a negative value if the specified date is in the past. Ignores 124 | /// the time of day. 125 | /// 126 | /// Example: 127 | /// ``` 128 | /// DateTime(2020, 12, 31).calendarDaysTill(2021, 1, 1); // 1 129 | /// DateTime(2020, 12, 31, 23, 59).calendarDaysTill(2021, 1, 1); // 1 130 | /// ``` 131 | /// 132 | /// This function intentionally does not take a [DateTime] argument to: 133 | /// * More clearly indicate that it does not take time of day into account. 134 | /// * Avoid potential problems if one [DateTime] is in UTC and the other is 135 | /// not. 136 | int calendarDaysTill(int year, int month, int day) { 137 | // Discard the time of day, and perform all calculations in UTC so that 138 | // Daylight Saving Time adjustments are not a factor. 139 | // 140 | // Note that this intentionally isn't the same as `toUtc()`; we instead 141 | // want to treat this `DateTime` object *as* a UTC `DateTime`. 142 | final startDay = DateTime.utc(this.year, this.month, this.day); 143 | final endDay = DateTime.utc(year, month, day); 144 | return (endDay - startDay).inDays; 145 | } 146 | } 147 | -------------------------------------------------------------------------------- /lib/int_basics.dart: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2019, Google Inc. Please see the AUTHORS file for details. 2 | // All rights reserved. Use of this source code is governed by a BSD-style 3 | // license that can be found in the LICENSE file. 4 | 5 | /// Utility extension methods for the native [int] class. 6 | extension IntBasics on int { 7 | /// Returns an iterable from `0` up to but not including [this]. 8 | /// 9 | /// Example: 10 | /// ```dart 11 | /// 5.range; // (0, 1, 2, 3, 4) 12 | /// ``` 13 | Iterable get range => Iterable.generate(this); 14 | 15 | /// Returns an iterable from [this] inclusive to [end] exclusive. 16 | /// 17 | /// Example: 18 | /// ```dart 19 | /// 3.to(6); // (3, 4, 5) 20 | /// 2.to(-2); // (2, 1, 0, -1) 21 | /// ``` 22 | /// 23 | /// If [by] is provided, it will be used as step size for iteration. [by] is 24 | /// always positive, even if the direction of iteration is decreasing. 25 | /// 26 | /// Example: 27 | /// ```dart 28 | /// 8.to(3, by: 2); // (8, 6, 4) 29 | /// ``` 30 | Iterable to(int end, {int by = 1}) { 31 | if (by < 1) { 32 | throw ArgumentError( 33 | 'Invalid step size: $by. Step size must be greater than 0'); 34 | } 35 | final count = ((end - this).abs() / by).ceil(); 36 | // Explicit type declaration required for function argument. 37 | final int Function(int) generator = this >= end 38 | ? (index) => this - (by * index) 39 | : (index) => this + (by * index); 40 | return Iterable.generate(count, generator); 41 | } 42 | 43 | /// Returns [Duration] of [this] in days. 44 | Duration get days => Duration(days: this); 45 | 46 | /// Returns [Duration] of [this] in hours. 47 | Duration get hours => Duration(hours: this); 48 | 49 | /// Returns [Duration] of [this] in minutes. 50 | Duration get minutes => Duration(minutes: this); 51 | 52 | /// Returns [Duration] of [this] in seconds. 53 | Duration get seconds => Duration(seconds: this); 54 | 55 | /// Returns [Duration] of [this] in milliseconds. 56 | Duration get milliseconds => Duration(milliseconds: this); 57 | 58 | /// Returns [Duration] of [this] in microseconds. 59 | Duration get microseconds => Duration(microseconds: this); 60 | } 61 | -------------------------------------------------------------------------------- /lib/iterable_basics.dart: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2019, Google Inc. Please see the AUTHORS file for details. 2 | // All rights reserved. Use of this source code is governed by a BSD-style 3 | // license that can be found in the LICENSE file. 4 | 5 | import 'dart:math' as math; 6 | 7 | import 'src/sort_key_compare.dart'; 8 | 9 | /// Utility extension methods for the native [Iterable] class. 10 | extension IterableBasics on Iterable { 11 | /// Alias for [Iterable]`.every`. 12 | bool all(bool Function(E) test) => this.every(test); 13 | 14 | /// Returns `true` if no element of [this] satisfies [test]. 15 | /// 16 | /// Example: 17 | /// ```dart 18 | /// [1, 2, 3].none((e) => e > 4); // true 19 | /// [1, 2, 3].none((e) => e > 2); // false 20 | /// ``` 21 | bool none(bool Function(E) test) => !this.any(test); 22 | 23 | /// Returns `true` if there is exactly one element of [this] which satisfies 24 | /// [test]. 25 | /// 26 | /// Example: 27 | /// ```dart 28 | /// [1, 2, 3].one((e) => e == 2); // 1 element satisfies. Returns true. 29 | /// [1, 2, 3].one((e) => e > 4); // No element satisfies. Returns false. 30 | /// [1, 2, 3].one((e) => e > 1); // >1 element satisfies. Returns false. 31 | /// ``` 32 | bool one(bool Function(E) test) { 33 | bool foundOne = false; 34 | for (var e in this) { 35 | if (test(e)) { 36 | if (foundOne) return false; 37 | foundOne = true; 38 | } 39 | } 40 | return foundOne; 41 | } 42 | 43 | /// Returns `true` if [this] contains at least one element also contained in 44 | /// [other]. 45 | /// 46 | /// Example: 47 | /// ```dart 48 | /// [1, 2, 3].containsAny([5, 2]); // true 49 | /// [1, 2, 3].containsAny([4, 5, 6]); // false 50 | /// ``` 51 | bool containsAny(Iterable other) => this.any(other.contains); 52 | 53 | /// Returns true if every element in [other] also exists in [this]. 54 | /// 55 | /// Example: 56 | /// ```dart 57 | /// [1, 2, 3].containsAll([1, 2]); // true 58 | /// [1, 2].containsAll([1, 2, 3]); // false 59 | /// ``` 60 | /// 61 | /// If [collapseDuplicates] is true, only the presence of a value will be 62 | /// considered, not the number of times it occurs. If [collapseDuplicates] is 63 | /// false, the number of occurrences of a given value in [this] must be 64 | /// greater than or equal to the number of occurrences of that value in 65 | /// [other] for the result to be true. 66 | /// 67 | /// Example: 68 | /// ``` 69 | /// [1, 2, 3].containsAll([1, 1, 1, 2]); // true 70 | /// [1, 2, 3].containsAll([1, 1, 1, 2], collapseDuplicates: false); // false 71 | /// [1, 1, 2, 3].containsAll([1, 1, 2], collapseDuplicates: false); // true 72 | /// ``` 73 | bool containsAll(Iterable other, {bool collapseDuplicates = true}) { 74 | if (other.isEmpty) return true; 75 | if (collapseDuplicates) { 76 | return Set.from(this).containsAll(Set.from(other)); 77 | } 78 | 79 | final thisElementCounts = _elementCountsIn(this); 80 | final otherElementCounts = _elementCountsIn(other); 81 | 82 | for (final element in otherElementCounts.keys) { 83 | final countInThis = thisElementCounts[element] ?? 0; 84 | final countInOther = otherElementCounts[element] ?? 0; 85 | if (countInThis < countInOther) { 86 | return false; 87 | } 88 | } 89 | return true; 90 | } 91 | 92 | /// Returns the greatest element of [this] as ordered by [compare], or [null] 93 | /// if [this] is empty. 94 | /// 95 | /// Example: 96 | /// ```dart 97 | /// ['a', 'aaa', 'aa'] 98 | /// .max((a, b) => a.length.compareTo(b.length)).value; // 'aaa' 99 | /// ``` 100 | E? max(Comparator compare) => 101 | this.isEmpty ? null : this.reduce(_generateCustomMaxFunction(compare)); 102 | 103 | /// Returns the smallest element of [this] as ordered by [compare], or [null] 104 | /// if [this] is empty. 105 | /// 106 | /// Example: 107 | /// ```dart 108 | /// ['a', 'aaa', 'aa'] 109 | /// .min((a, b) => a.length.compareTo(b.length)).value; // 'a' 110 | /// ``` 111 | E? min(Comparator compare) => 112 | this.isEmpty ? null : this.reduce(_generateCustomMinFunction(compare)); 113 | 114 | /// Returns the element of [this] with the greatest value for [sortKey], or 115 | /// [null] if [this] is empty. 116 | /// 117 | /// This method is guaranteed to calculate [sortKey] only once for each 118 | /// element. 119 | /// 120 | /// Example: 121 | /// ```dart 122 | /// ['a', 'aaa', 'aa'].maxBy((e) => e.length).value; // 'aaa' 123 | /// ``` 124 | E? maxBy(Comparable Function(E) sortKey) { 125 | final sortKeyCache = >{}; 126 | return this.max((a, b) => sortKeyCompare(a, b, sortKey, sortKeyCache)); 127 | } 128 | 129 | /// Returns the element of [this] with the least value for [sortKey], or 130 | /// [null] if [this] is empty. 131 | /// 132 | /// This method is guaranteed to calculate [sortKey] only once for each 133 | /// element. 134 | /// 135 | /// Example: 136 | /// ```dart 137 | /// ['a', 'aaa', 'aa'].minBy((e) => e.length).value; // 'a' 138 | /// ``` 139 | E? minBy(Comparable Function(E) sortKey) { 140 | final sortKeyCache = >{}; 141 | return this.min((a, b) => sortKeyCompare(a, b, sortKey, sortKeyCache)); 142 | } 143 | 144 | /// Returns the sum of all the values in this iterable, as defined by 145 | /// [addend]. 146 | /// 147 | /// Returns 0 if [this] is empty. 148 | /// 149 | /// Example: 150 | /// ```dart 151 | /// ['a', 'aa', 'aaa'].sum((s) => s.length); // 6 152 | /// ``` 153 | num sum(num Function(E) addend) => this.isEmpty 154 | ? 0 155 | : this.fold(0, (prev, element) => prev + addend(element)); 156 | 157 | /// Returns the average of all the values in this iterable, as defined by 158 | /// [value]. 159 | /// 160 | /// Returns null if [this] is empty. 161 | /// 162 | /// Example: 163 | /// ```dart 164 | /// ['a', 'aa', 'aaa'].average((s) => s.length); // 2 165 | /// [].average(); // null 166 | /// ``` 167 | num? average(num Function(E) value) { 168 | if (this.isEmpty) return null; 169 | 170 | return this.sum(value) / this.length; 171 | } 172 | 173 | /// Returns a random element of [this], or [null] if [this] is empty. 174 | /// 175 | /// If [seed] is provided, will be used as the random seed for determining 176 | /// which element to select. (See [math.Random].) 177 | E? getRandom({int? seed}) => this.isEmpty 178 | ? null 179 | : this.elementAt(math.Random(seed).nextInt(this.length)); 180 | 181 | /// Returns an [Iterable] containing the first [end] elements of [this], 182 | /// excluding the first [start] elements. 183 | /// 184 | /// This method is a generalization of [List.getRange] to [Iterable]s, 185 | /// and obeys the same contract. 186 | /// 187 | /// Example: 188 | /// ```dart 189 | /// {3, 8, 12, 4, 1}.range(2, 4); // [12, 4] 190 | /// ``` 191 | Iterable getRange(int start, int end) { 192 | RangeError.checkValidRange(start, end, this.length); 193 | return this.skip(start).take(end - start); 194 | } 195 | } 196 | 197 | /// Utility extension methods for [Iterable]s containing [num]s. 198 | extension NumIterableBasics on Iterable { 199 | /// Returns the greatest number in [this], or [null] if [this] is empty. 200 | /// 201 | /// Example: 202 | /// ```dart 203 | /// [104, 3, 18].max().value; // 104 204 | /// ``` 205 | /// 206 | /// If [compare] is provided, it will be used to order the elements. 207 | /// 208 | /// Example: 209 | /// ```dart 210 | /// [-47, 10, 2].max((a, b) => 211 | /// a.toString().length.compareTo(b.toString().length)).value; // -47 212 | /// ``` 213 | E? max([Comparator? compare]) => this.isEmpty 214 | ? null 215 | : this.reduce( 216 | compare == null ? math.max : _generateCustomMaxFunction(compare)); 217 | 218 | /// Returns the least number in [this], or [null] if [this] is empty. 219 | /// 220 | /// Example: 221 | /// ```dart 222 | /// [104, 3, 18].min().value; // 3 223 | /// ``` 224 | /// 225 | /// If [compare] is provided, it will be used to order the elements. 226 | /// 227 | /// Example: 228 | /// ```dart 229 | /// [-100, -200, 5].min((a, b) => 230 | /// a.toString().length.compareTo(b.toString().length)).value; // 5 231 | /// ``` 232 | E? min([Comparator? compare]) => this.isEmpty 233 | ? null 234 | : this.reduce( 235 | compare == null ? math.min : _generateCustomMinFunction(compare)); 236 | 237 | /// Returns the sum of all the values in this iterable. 238 | /// 239 | /// If [addend] is provided, it will be used to compute the value to be 240 | /// summed. 241 | /// 242 | /// Returns 0 if [this] is empty. 243 | /// 244 | /// Example: 245 | /// ```dart 246 | /// [1, 2, 3].sum(); // 6. 247 | /// [2, 3, 4].sum((i) => i * 0.5); // 4.5. 248 | /// [].sum() // 0. 249 | /// ``` 250 | num sum([num Function(E)? addend]) { 251 | if (this.isEmpty) return 0; 252 | return addend == null 253 | ? this.reduce((a, b) => (a + b) as E) 254 | : this.fold(0, (prev, element) => prev + addend(element)); 255 | } 256 | 257 | /// Returns the average of all the values in this iterable. 258 | /// 259 | /// If [value] is provided, it will be used to compute the value to be 260 | /// averaged. 261 | /// 262 | /// Returns null if [this] is empty. 263 | /// 264 | /// Example: 265 | /// ```dart 266 | /// [2, 2, 4, 8].average(); // 4. 267 | /// [2, 2, 4, 8].average((i) => i + 1); // 5. 268 | /// [].average() // null. 269 | /// ``` 270 | num? average([num Function(E)? value]) { 271 | if (this.isEmpty) return null; 272 | 273 | return this.sum(value) / this.length; 274 | } 275 | } 276 | 277 | T Function(T, T) _generateCustomMaxFunction(Comparator compare) { 278 | T max(T a, T b) { 279 | if (compare(a, b) >= 0) return a; 280 | return b; 281 | } 282 | 283 | return max; 284 | } 285 | 286 | T Function(T, T) _generateCustomMinFunction(Comparator compare) { 287 | T min(T a, T b) { 288 | if (compare(a, b) <= 0) return a; 289 | return b; 290 | } 291 | 292 | return min; 293 | } 294 | 295 | Map _elementCountsIn(Iterable iterable) { 296 | final counts = {}; 297 | for (final element in iterable) { 298 | final currentCount = counts[element] ?? 0; 299 | counts[element] = currentCount + 1; 300 | } 301 | return counts; 302 | } 303 | -------------------------------------------------------------------------------- /lib/list_basics.dart: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2019, Google Inc. Please see the AUTHORS file for details. 2 | // All rights reserved. Use of this source code is governed by a BSD-style 3 | // license that can be found in the LICENSE file. 4 | 5 | import 'dart:math' as math; 6 | 7 | import 'src/slice_indices.dart'; 8 | import 'src/sort_key_compare.dart'; 9 | 10 | /// Utility extension methods for the native [List] class. 11 | extension ListBasics on List { 12 | /// Returns a new list containing the elements of [this] from [start] 13 | /// inclusive to [end] exclusive, skipping by [step]. 14 | /// 15 | /// Example: 16 | /// ```dart 17 | /// [1, 2, 3, 4].slice(start: 1, end: 3); // [2, 3] 18 | /// [1, 2, 3, 4].slice(start: 1, end: 4, step: 2); // [2, 4] 19 | /// ``` 20 | /// 21 | /// [start] defaults to the first element if [step] is positive and to the 22 | /// last element if [step] is negative. [end] does the opposite. 23 | /// 24 | /// Example: 25 | /// ```dart 26 | /// [1, 2, 3, 4].slice(end: 2); // [1, 2] 27 | /// [1, 2, 3, 4].slice(start: 1); // [2, 3, 4] 28 | /// [1, 2, 3, 4].slice(end: 1, step: -1); // [4, 3] 29 | /// [1, 2, 3, 4].slice(start: 2, step: -1); // [3, 2, 1] 30 | /// ``` 31 | /// 32 | /// If [start] or [end] is negative, it will be counted backwards from the 33 | /// last element of [this]. If [step] is negative, the elements will be 34 | /// returned in reverse order. 35 | /// 36 | /// Example: 37 | /// ```dart 38 | /// [1, 2, 3, 4].slice(start: -2); // [3, 4] 39 | /// [1, 2, 3, 4].slice(end: -1); // [1, 2, 3] 40 | /// [1, 2, 3, 4].slice(step: -1); // [4, 3, 2, 1] 41 | /// ``` 42 | /// 43 | /// Any out-of-range values for [start] or [end] will be truncated to the 44 | /// maximum in-range value in that direction. 45 | /// 46 | /// Example: 47 | /// ```dart 48 | /// [1, 2, 3, 4].slice(start: -100); // [1, 2, 3, 4] 49 | /// [1, 2, 3, 4].slice(end: 100); // [1, 2, 3, 4] 50 | /// ``` 51 | /// 52 | /// Will return an empty list if [start] and [end] are equal, [start] is 53 | /// greater than [end] while [step] is positive, or [end] is greater than 54 | /// [start] while [step] is negative. 55 | /// 56 | /// Example: 57 | /// ```dart 58 | /// [1, 2, 3, 4].slice(start: 1, end: -3); // [] 59 | /// [1, 2, 3, 4].slice(start: 3, end: 1); // [] 60 | /// [1, 2, 3, 4].slice(start: 1, end: 3, step: -1); // [] 61 | /// ``` 62 | List slice({int? start, int? end, int step = 1}) { 63 | final indices = sliceIndices(start, end, step, this.length); 64 | if (indices == null) { 65 | return []; 66 | } 67 | 68 | final _start = indices.start; 69 | final _end = indices.end; 70 | final slice = []; 71 | 72 | if (step > 0) { 73 | for (var i = _start; i < _end; i += step) { 74 | slice.add(this[i]); 75 | } 76 | } else { 77 | for (var i = _start; i > _end; i += step) { 78 | slice.add(this[i]); 79 | } 80 | } 81 | return slice; 82 | } 83 | 84 | /// Returns a sorted copy of this list. 85 | List sortedCopy() { 86 | return List.of(this)..sort(); 87 | } 88 | 89 | /// Sorts this list by the value returned by [sortKey] for each element. 90 | /// 91 | /// This method is guaranteed to calculate [sortKey] only once for each 92 | /// element. 93 | /// 94 | /// Example: 95 | /// ```dart 96 | /// var list = [-12, 3, 10]; 97 | /// list.sortBy((e) => e.toString().length); // list is now [3, 10, -12]. 98 | /// ``` 99 | void sortBy(Comparable Function(E) sortKey) { 100 | final sortKeyCache = >{}; 101 | this.sort((a, b) => sortKeyCompare(a, b, sortKey, sortKeyCache)); 102 | } 103 | 104 | /// Returns a copy of this list sorted by the value returned by [sortKey] for 105 | /// each element. 106 | /// 107 | /// This method is guaranteed to calculate [sortKey] only once for each 108 | /// element. 109 | /// 110 | /// Example: 111 | /// ```dart 112 | /// var list = [-12, 3, 10]; 113 | /// var sorted = list.sortedCopyBy((e) => e.toString().length); 114 | /// // list is still [-12, 3, 10]. sorted is [3, 10, -12]. 115 | /// ``` 116 | List sortedCopyBy(Comparable Function(E) sortKey) { 117 | return List.of(this)..sortBy(sortKey); 118 | } 119 | 120 | /// Removes a random element of [this] and returns it. 121 | /// 122 | /// Returns [null] if [this] is empty. 123 | /// 124 | /// If [seed] is provided, will be used as the random seed for determining 125 | /// which element to select. (See [math.Random].) 126 | E? takeRandom({int? seed}) => this.isEmpty 127 | ? null 128 | : this.removeAt(math.Random(seed).nextInt(this.length)); 129 | } 130 | -------------------------------------------------------------------------------- /lib/map_basics.dart: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2019, Google Inc. Please see the AUTHORS file for details. 2 | // All rights reserved. Use of this source code is governed by a BSD-style 3 | // license that can be found in the LICENSE file. 4 | 5 | /// Utility extension methods for the native [Map] class. 6 | extension MapBasics on Map { 7 | /// A type-checked version of [operator []] that additionally supports 8 | /// returning a default value. 9 | /// 10 | /// Returns [defaultValue] if the key is not found. This is slightly 11 | /// different from `map[key] ?? defaultValue` if the [Map] stores `null` 12 | /// values. 13 | // 14 | // Remove if implemented upstream: 15 | // https://github.com/dart-lang/sdk/issues/37392 16 | V? get(K key, {V? defaultValue}) => 17 | this.containsKey(key) ? this[key] : defaultValue; 18 | 19 | /// Returns a new [Map] containing all the entries of [this] for which the key 20 | /// satisfies [test]. 21 | /// 22 | /// Example: 23 | /// ```dart 24 | /// var map = {'a': 1, 'bb': 2, 'ccc': 3} 25 | /// map.whereKey((key) => key.length > 1); // {'bb': 2, 'ccc': 3} 26 | /// ``` 27 | Map whereKey(bool Function(K) test) => 28 | // Entries do not need to be cloned because they are const. 29 | Map.fromEntries(this.entries.where((entry) => test(entry.key))); 30 | 31 | /// Returns a new [Map] containing all the entries of [this] for which the 32 | /// value satisfies [test]. 33 | /// 34 | /// Example: 35 | /// ```dart 36 | /// var map = {'a': 1, 'b': 2, 'c': 3}; 37 | /// map.whereValue((value) => value > 1); // {'b': 2, 'c': 3} 38 | /// ``` 39 | Map whereValue(bool Function(V) test) => 40 | // Entries do not need to be cloned because they are const. 41 | Map.fromEntries(this.entries.where((entry) => test(entry.value))); 42 | 43 | /// Returns a new [Map] where each entry is inverted, with the key becoming 44 | /// the value and the value becoming the key. 45 | /// 46 | /// Example: 47 | /// ```dart 48 | /// var map = {'a': 1, 'b': 2, 'c': 3}; 49 | /// map.invert(); // {1: 'a', 2: 'b', 3: 'c'} 50 | /// ``` 51 | /// 52 | /// As Map does not guarantee an order of iteration over entries, this method 53 | /// does not guarantee which key will be preserved as the value in the case 54 | /// where more than one key is associated with the same value. 55 | /// 56 | /// Example: 57 | /// ```dart 58 | /// var map = {'a': 1, 'b': 2, 'c': 2}; 59 | /// map.invert(); // May return {1: 'a', 2: 'b'} or {1: 'a', 2: 'c'}. 60 | /// ``` 61 | Map invert() => Map.fromEntries( 62 | this.entries.map((entry) => MapEntry(entry.value, entry.key))); 63 | } 64 | -------------------------------------------------------------------------------- /lib/set_basics.dart: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2019, Google Inc. Please see the AUTHORS file for details. 2 | // All rights reserved. Use of this source code is governed by a BSD-style 3 | // license that can be found in the LICENSE file. 4 | 5 | import 'dart:math' as math; 6 | 7 | /// Utility extension methods for the native [Set] class. 8 | extension SetBasics on Set { 9 | /// Returns `true` if [this] and [other] contain exactly the same elements. 10 | /// 11 | /// Example: 12 | /// ```dart 13 | /// var set = {'a', 'b', 'c'}; 14 | /// set.isEqualTo({'b', 'a', 'c'}); // true 15 | /// set.isEqualTo({'b', 'a', 'f'}); // false 16 | /// set.isEqualTo({'a', 'b'}); // false 17 | /// set.isEqualTo({'a', 'b', 'c', 'd'}); // false 18 | /// ``` 19 | bool isEqualTo(Set