Add complexity bound on binary search methods (dart-archive/collectio…

…n#239)

Closes dart-lang/collection#237

In each of the list extensions that mention "Uses binary search" add a
sentence documenting that the search takes `log(n)` comparisons.
Add a sentence about using binary search and the runtime to the top
level algorithm methods.

pkgs/collection/CHANGELOG.md

@@ -1,3 +1,5 @@
+## 1.16.1-dev
+
 ## 1.16.0
 
 * Add an `Iterable.slices` extension method.

pkgs/collection/lib/src/algorithms.dart

@@ -57,6 +57,8 @@ int binarySearchBy<E, K>(List<E> sortedList, K Function(E element) keyOf,
 /// Returns the first position in [sortedList] that does not compare less than
 /// [value].
 ///
+/// Uses binary search to find the location of [value].
+/// This takes on the order of `log(n)` comparisons.
 /// If the list isn't sorted according to the [compare] function, the result
 /// is unpredictable.
 ///
@@ -72,6 +74,8 @@ int lowerBound<E>(List<E> sortedList, E value, {int Function(E, E)? compare}) {
 
 /// Returns the first position in [sortedList] that is not before [value].
 ///
+/// Uses binary search to find the location of [value].
+/// This takes on the order of `log(n)` comparisons.
 /// Elements are compared using the [compare] function of the [keyOf] property of
 /// the elements.
 /// If the list isn't sorted according to this order, the result is unpredictable.

pkgs/collection/lib/src/list_extensions.dart

@@ -16,6 +16,7 @@ extension ListExtensions<E> on List<E> {
   /// Returns the index of [element] in this sorted list.
   ///
   /// Uses binary search to find the location of [element].
+  /// This takes on the order of `log(n)` comparisons.
   /// The list *must* be sorted according to [compare],
   /// otherwise the result is unspecified
   ///
@@ -26,6 +27,7 @@ extension ListExtensions<E> on List<E> {
   /// Returns the index of [element] in this sorted list.
   ///
   /// Uses binary search to find the location of [element].
+  /// This takes on the order of `log(n)` comparisons.
   /// The list *must* be sorted according to [compare] on the [keyOf] of elements,
   /// otherwise the result is unspecified.
   ///
@@ -42,6 +44,7 @@ extension ListExtensions<E> on List<E> {
   /// Returns the index of [element] in this sorted list.
   ///
   /// Uses binary search to find the location of [element].
+  /// This takes on the order of `log(n)` comparisons.
   /// The list *must* be sorted according to the natural ordering of
   /// the [keyOf] of elements, otherwise the result is unspecified.
   ///
@@ -57,6 +60,7 @@ extension ListExtensions<E> on List<E> {
   /// Returns the index where [element] should be in this sorted list.
   ///
   /// Uses binary search to find the location of [element].
+  /// This takes on the order of `log(n)` comparisons.
   /// The list *must* be sorted according to [compare],
   /// otherwise the result is unspecified.
   ///
@@ -71,6 +75,7 @@ extension ListExtensions<E> on List<E> {
   /// Returns the index where [element] should be in this sorted list.
   ///
   /// Uses binary search to find the location of [element].
+  /// This takes on the order of `log(n)` comparisons.
   /// The list *must* be sorted according to [compare] of
   /// the [keyOf] of the elements, otherwise the result is unspecified.
   ///
@@ -90,6 +95,7 @@ extension ListExtensions<E> on List<E> {
   /// Returns the index where [element] should be in this sorted list.
   ///
   /// Uses binary search to find the location of [element].
+  /// This takes on the order of `log(n)` comparisons.
   /// The list *must* be sorted according to the
   /// natural ordering of the [keyOf] of the elements,
   /// otherwise the result is unspecified.
@@ -276,6 +282,7 @@ extension ListComparableExtensions<E extends Comparable<E>> on List<E> {
   /// Returns the index of [element] in this sorted list.
   ///
   /// Uses binary search to find the location of [element].
+  /// This takes on the order of `log(n)` comparisons.
   /// The list *must* be sorted according to [compare],
   /// otherwise the result is unspecified.
   /// If [compare] is omitted, it uses the natural order of the elements.
@@ -288,6 +295,7 @@ extension ListComparableExtensions<E extends Comparable<E>> on List<E> {
   /// Returns the index where [element] should be in this sorted list.
   ///
   /// Uses binary search to find the location of where [element] should be.
+  /// This takes on the order of `log(n)` comparisons.
   /// The list *must* be sorted according to [compare],
   /// otherwise the result is unspecified.
   /// If [compare] is omitted, it uses the natural order of the elements.

pkgs/collection/pubspec.yaml

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