feat!: Introduce new ReadOnlyOrderedSet super-interface

README.md

@@ -67,17 +67,15 @@ Note that you could instead just create a `MappingOrderedSet` instead:
   // ...
 ```
 
-## Mapping vs Comparing vs Queryable
+## Mapping vs Comparing
 
-There are three main implementations of the `OrderedSet` interface:
+There are two main implementations of the `OrderedSet` interface:
 
 * `ComparingOrderedSet`: the simplest implementation, takes in a `Comparator` and does not cache
    priorities. It uses Dart's `SplayTreeSet` as a backing implementation.
 * `MappingOrderedSet`: a slightly more advanced implementation that takes in a mapper function
    (maps elements to their priorities) and caches them. It uses Dart's `SplayTreeMap` as a backing
    implementation.
-* `QueryableOrderedSet`: a simple wrapper over either `OrderedSet` that allows for O(1) type
-   queries; if you find yourself doing `.whereType<T>()` a lot, you should consider using this.
 
 In order to create an `OrderedSet`, however, you can just use the static methods on the interface
 itself:
@@ -90,7 +88,19 @@ itself:
   a `MappingOrderedSet` with identity mapping.
 * `OrderedSet.simple<E>()`: if `E extends Comparable<E>`, this is an even simpler way of creating
   a `MappingOrderedSet` with identity mapping.
-* `OrderedSet.queryable<E>(orderedSet)`: wraps the given `OrderedSet` into a `QueryableOrderedSet`.
+
+## Querying
+
+You can [register] a set of queries, i.e., predefined sub-types, whose results, 
+i.e., subsets of this set, are then cached.
+Since the queries have to be type checks, and types are runtime constants, this
+can be vastly optimized.
+
+You can then filter by type by using the [query] method (or using [whereType];
+which is overridden).
+
+Note that you can change [strictMode] to allow for querying for unregistered
+types; if you do so, the registration cost is payed on the first query.
 
 ## Contributing
 

benchmark/main.dart

@@ -8,7 +8,7 @@ import 'types.dart';
 
 void main() {
   OrderedSet<K> comparing<K>(Mapper<K> mapper) {
-    return OrderedSet.comparing<K>(Comparing.on(mapper));
+    return OrderedSet.comparing<K>(compare: Comparing.on(mapper));
   }
 
   OrderedSet<K> priority<K>(Mapper<K> mapper) {

example/ordered_set_example.dart

@@ -9,7 +9,7 @@ void main() {
   items.add(1);
   print(items.toList()); // [1, 2]
 
-  final a = OrderedSet.comparing<Person>((a, b) => a.age - b.age);
+  final a = OrderedSet.comparing<Person>(compare: (a, b) => a.age - b.age);
   a.add(Person(12, 'Klaus'));
   a.add(Person(1, 'Sunny'));
   a.add(Person(14, 'Violet'));
@@ -25,7 +25,7 @@ void main() {
   // use Comparing for simpler creation:
   // sort by age desc and then name asc
   final b = OrderedSet.comparing<Person>(
-    Comparing.join([(p) => -p.age, (p) => p.name]),
+    compare: Comparing.join([(p) => -p.age, (p) => p.name]),
   );
   b.addAll(a.toList());
   print(b.toList().map((e) => e.name));

lib/comparing_ordered_set.dart

@@ -3,14 +3,16 @@ import 'dart:collection';
 import 'package:ordered_set/mapping_ordered_set.dart';
 import 'package:ordered_set/ordered_set.dart';
 import 'package:ordered_set/ordered_set_iterator.dart';
+import 'package:ordered_set/queryable_ordered_set_impl.dart';
 
 /// A simple implementation of [OrderedSet] that uses a [SplayTreeSet] as the
 /// backing store.
 ///
 /// This does not store the elements priorities, so it is susceptible to race
 /// conditions if priorities are changed while iterating.
 /// For a safer implementation, use [MappingOrderedSet].
-class ComparingOrderedSet<E> extends OrderedSet<E> {
+class ComparingOrderedSet<E> extends OrderedSet<E>
+    with QueryableOrderedSetImpl<E> {
   // If the default implementation of `Set` changes from `LinkedHashSet` to
   // something else that isn't ordered we'll have to change this to explicitly
   // be `LinkedHashSet` (or some other data structure that preserves order).
@@ -20,6 +22,9 @@ class ComparingOrderedSet<E> extends OrderedSet<E> {
   bool _validReverseCache = true;
   Iterable<E> _reverseCache = const Iterable.empty();
 
+  @override
+  final bool strictMode;
+
   // Copied from SplayTreeSet, but those are private there
   static int _dynamicCompare(dynamic a, dynamic b) => Comparable.compare(
         a as Comparable,
@@ -37,7 +42,10 @@ class ComparingOrderedSet<E> extends OrderedSet<E> {
   ///
   /// If the [compare] function is omitted, it defaults to [Comparable.compare],
   /// and the elements must be comparable.
-  ComparingOrderedSet([int Function(E e1, E e2)? compare]) {
+  ComparingOrderedSet({
+    int Function(E e1, E e2)? compare,
+    this.strictMode = true,
+  }) {
     final comparator = compare ?? _defaultCompare<E>();
     _backingSet = SplayTreeSet<LinkedHashSet<E>>((Set<E> l1, Set<E> l2) {
       if (l1.isEmpty) {
@@ -81,6 +89,7 @@ class ComparingOrderedSet<E> extends OrderedSet<E> {
     if (added) {
       _length++;
       _validReverseCache = false;
+      onAdd(e);
     }
     return added;
   }
@@ -122,6 +131,7 @@ class ComparingOrderedSet<E> extends OrderedSet<E> {
       // If the removal resulted in an empty bucket, remove the bucket as well.
       _backingSet.remove(<E>{});
       _validReverseCache = false;
+      onRemove(e);
     }
     return result;
   }
@@ -131,5 +141,6 @@ class ComparingOrderedSet<E> extends OrderedSet<E> {
     _validReverseCache = false;
     _backingSet.clear();
     _length = 0;
+    onClear();
   }
 }

lib/mapping_ordered_set.dart

@@ -3,22 +3,27 @@ import 'dart:collection';
 import 'package:ordered_set/comparing_ordered_set.dart';
 import 'package:ordered_set/ordered_set.dart';
 import 'package:ordered_set/ordered_set_iterator.dart';
+import 'package:ordered_set/queryable_ordered_set_impl.dart';
 
 /// A simple implementation of [OrderedSet] that uses a [SplayTreeMap] as the
 /// backing store.
 ///
 /// This allows it to keep a cache of elements priorities, so they can be used
 /// changed without rebalancing.
 /// For an alternative implementation, use [ComparingOrderedSet].
-class MappingOrderedSet<K extends Comparable<K>, E> extends OrderedSet<E> {
+class MappingOrderedSet<K extends Comparable<K>, E> extends OrderedSet<E>
+    with QueryableOrderedSetImpl<E> {
   final K Function(E a) _mappingFunction;
   late SplayTreeMap<K, Set<E>> _backingSet;
   late int _length;
 
   bool _validReverseCache = true;
   Iterable<E> _reverseCache = const Iterable.empty();
 
-  MappingOrderedSet(this._mappingFunction) {
+  @override
+  final bool strictMode;
+
+  MappingOrderedSet(this._mappingFunction, {this.strictMode = true}) {
     _backingSet = SplayTreeMap((K k1, K k2) {
       return k1.compareTo(k2);
     });
@@ -49,6 +54,7 @@ class MappingOrderedSet<K extends Comparable<K>, E> extends OrderedSet<E> {
     if (added) {
       _length++;
       _validReverseCache = false;
+      onAdd(e);
     }
     return added;
   }
@@ -94,6 +100,7 @@ class MappingOrderedSet<K extends Comparable<K>, E> extends OrderedSet<E> {
         _backingSet.remove(key);
       }
       _validReverseCache = false;
+      onRemove(e);
     }
     return result;
   }
@@ -103,5 +110,6 @@ class MappingOrderedSet<K extends Comparable<K>, E> extends OrderedSet<E> {
     _validReverseCache = false;
     _backingSet.clear();
     _length = 0;
+    onClear();
   }
 }

lib/ordered_set.dart

@@ -2,18 +2,15 @@ import 'dart:collection';
 
 import 'package:ordered_set/comparing_ordered_set.dart';
 import 'package:ordered_set/mapping_ordered_set.dart';
-import 'package:ordered_set/queryable_ordered_set.dart';
+import 'package:ordered_set/read_only_ordered_set.dart';
 
 /// A simple interface of an ordered set for Dart.
 ///
 /// It accepts some way of comparing items for their priority. Unlike
 /// [SplayTreeSet], it allows for several different elements with the same
 /// priority to be added. It also implements [Iterable], so you can iterate it
 /// in O(n).
-abstract class OrderedSet<E> extends IterableMixin<E> {
-  /// The tree's elements in reversed order; should be cached when possible.
-  Iterable<E> reversed();
-
+abstract class OrderedSet<E> extends ReadOnlyOrderedSet<E> {
   /// Adds the element [e] to this, and returns whether the element was
   /// added or not. If the element already exists in the collection, it isn't
   /// added.
@@ -86,43 +83,40 @@ abstract class OrderedSet<E> extends IterableMixin<E> {
   ///
   /// This implementation will not store component priorities, so it is
   /// susceptible to race conditions if priorities are changed while iterating.
-  static ComparingOrderedSet<E> comparing<E>([
+  static ComparingOrderedSet<E> comparing<E>({
     int Function(E a, E b)? compare,
-  ]) {
-    return ComparingOrderedSet<E>(compare);
+    bool strictMode = true,
+  }) {
+    return ComparingOrderedSet<E>(compare: compare, strictMode: strictMode);
   }
 
   /// Creates an instance of [OrderedSet] using the [MappingOrderedSet]
   /// implementation and the provided [mappingFunction].
   static MappingOrderedSet<K, E> mapping<K extends Comparable<K>, E>(
-    K Function(E a) mappingFunction,
-  ) {
-    return MappingOrderedSet(mappingFunction);
+    K Function(E a) mappingFunction, {
+    bool strictMode = true,
+  }) {
+    return MappingOrderedSet(mappingFunction, strictMode: strictMode);
   }
 
   /// Creates an instance of [OrderedSet] for items that are already
   /// [Comparable] using the [MappingOrderedSet] implementation.
   /// Use this for classes that implement [Comparable] of a different class.
   /// Equivalent to `mapping<K, E>((a) => a)`.
   static MappingOrderedSet<K, E>
-      comparable<K extends Comparable<K>, E extends K>() {
-    return mapping<K, E>((a) => a);
+      comparable<K extends Comparable<K>, E extends K>({
+    bool strictMode = true,
+  }) {
+    return mapping<K, E>((a) => a, strictMode: strictMode);
   }
 
   /// Creates an instance of [OrderedSet] for items that are already
   /// [Comparable] of themselves, using the [MappingOrderedSet] implementation.
   /// Use this for classes that implement [Comparable] of themselves.
   /// Equivalent to `mapping<K, K>((a) => a)`.
-  static MappingOrderedSet<E, E> simple<E extends Comparable<E>>() {
-    return comparable<E, E>();
-  }
-
-  /// Creates an instance of [OrderedSet] using the [QueryableOrderedSet]
-  /// by wrapping the provided [backingSet].
-  static QueryableOrderedSet<E> queryable<E>(
-    OrderedSet<E> backingSet, {
+  static MappingOrderedSet<E, E> simple<E extends Comparable<E>>({
     bool strictMode = true,
   }) {
-    return QueryableOrderedSet<E>(backingSet, strictMode: strictMode);
+    return comparable<E, E>(strictMode: strictMode);
   }
 }