Refactor List diffing/change records, add diffing interface (#5)

* Refactor our a differ/list differ.

* Fix bugs in mergeSplice

* More fixes to the list differ.

* Some debugging.

* More fixes.

* Fix remaining edge case missed.

* Slight cleanups before PR

* Update README

* Add license headers.

.analysis_options

@@ -2,48 +2,27 @@ analyzer:
   strong-mode: true
 linter:
   rules:
-    #- always_declare_return_types
-    #- always_specify_types
-    #- annotate_overrides
-    #- avoid_as
+    # Errors
     - avoid_empty_else
+    - control_flow_in_finally
+    - empty_statements
+    - test_types_in_equals
+    - throw_in_finally
+    - valid_regexps
+
+    # Style
+    - annotate_overrides
     - avoid_init_to_null
     - avoid_return_types_on_setters
     - await_only_futures
     - camel_case_types
-    - cancel_subscriptions
-    #- close_sinks
-    #- comment_references
-    - constant_identifier_names
-    - control_flow_in_finally
+    - comment_references
     - empty_catches
     - empty_constructor_bodies
-    - empty_statements
     - hash_and_equals
-    - implementation_imports
-    - iterable_contains_unrelated_type
-    - library_names
     - library_prefixes
-    - list_remove_unrelated_type
     - non_constant_identifier_names
-    - one_member_abstracts
-    - only_throw_errors
-    - overridden_fields
-    - package_api_docs
-    - package_names
-    - package_prefixed_library_names
     - prefer_is_not_empty
-    #- public_member_api_docs
-    #- slash_for_doc_comments
-    #- sort_constructors_first
-    #- sort_unnamed_constructors_first
-    - super_goes_last
-    - test_types_in_equals
-    - throw_in_finally
-    #- type_annotate_public_apis
+    - slash_for_doc_comments
     - type_init_formals
-    #- unawaited_futures
-    - unnecessary_brace_in_string_interp
-    - unnecessary_getters_setters
     - unrelated_type_equality_checks
-    - valid_regexps

CHANGELOG.md

@@ -1,3 +1,15 @@
+## 0.15.0
+
+* Added the `Differ` interface, as well as `EqualityDiffer`
+* Refactored list diffing into a `ListDiffer`
+* Added concept of `ChangeRecord.ANY` and `ChangeRecord.NONE`
+    * Low-GC ways to expression "something/nothing" changed
+* Refactored `ListChangeRecord`
+    * Added named constructors for common use cases
+    * Added equality and hashCode checks
+    * Added `ListChangeRecord.apply` to apply a change record
+* Added missing `@override` annotations to satisfy `annotate_overrides`
+
 ## 0.14.0+1
 
 * Add a missing dependency on `pkg/meta`.

README.md

@@ -1,5 +1,6 @@
-Support for marking objects as observable, and getting notifications when those
-objects are mutated.
+Support for detecting and being notified when an object is mutated.
 
-This library is used to observe changes to observable types. It also
-has helpers to make implementing and using observable objects easy.
+There are two general ways to detect changes:
+
+* Listen to `Observable.changes` and be notified when an object changes
+* Use `Differ.diff` to determine changes between two objects

lib/observable.dart

@@ -4,8 +4,8 @@
 
 library observable;
 
-export 'src/change_record.dart';
-export 'src/list_diff.dart' show ListChangeRecord;
+export 'src/differs.dart' show Differ, EqualityDiffer, ListDiffer;
+export 'src/records.dart' show ChangeRecord, ListChangeRecord;
 export 'src/observable.dart';
 export 'src/observable_list.dart';
 export 'src/observable_map.dart';

lib/src/differs.dart

@@ -0,0 +1,35 @@
+// Copyright (c) 2016, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+library observable.src.differs;
+
+import 'dart:math' as math;
+
+import 'package:collection/collection.dart';
+
+import 'records.dart';
+
+part 'differs/list_differ.dart';
+
+/// Generic comparisons between two comparable objects.
+abstract class Differ<E> {
+  /// Returns a list of change records between [e1] and [e2].
+  ///
+  /// A return value of an empty [ChangeRecord.NONE] means no changes found.
+  List<ChangeRecord> diff(E e1, E e2);
+}
+
+/// Uses [Equality] to determine a simple [ChangeRecord.ANY] response.
+class EqualityDiffer<E> implements Differ<E> {
+  final Equality<E> _equality;
+
+  const EqualityDiffer([this._equality = const DefaultEquality()]);
+
+  const EqualityDiffer.identity() : this._equality = const IdentityEquality();
+
+  @override
+  List<ChangeRecord> diff(E e1, E e2) {
+    return _equality.equals(e1, e2) ? ChangeRecord.NONE : ChangeRecord.ANY;
+  }
+}