[folks] Add AbstractFieldDetails.values_equal().

[Travis Reitter <treitter src gnome org>]

commit 8b991be5f2ab4fd8d81956c973c656479f899144
Author: Travis Reitter <travis reitter collabora co uk>
Date:   Fri Oct 21 09:37:26 2011 -0700

    Add AbstractFieldDetails.values_equal().
    
    This function is lets subclasses to provide "smart" value comparisons
    without needing to factor in the parameters. This is particularly
    important for uses like PotententialMatches.
    
    This clarifies the roles of AbstractFieldDetails.equal() and
    parameters_equal() (both in form and documentation).
    
    Closes: bgo#662433 - AbstractFieldDetails.equal() is ambiguous about
    checking parameters.

 NEWS                              |    3 +
 folks/abstract-field-details.vala |   78 +++++++++++++++++++++++++++++--------
 folks/phone-details.vala          |   12 ++++++
 folks/potential-match.vala        |    2 +-
 4 files changed, 77 insertions(+), 18 deletions(-)
---
diff --git a/NEWS b/NEWS
index 0f973c6..e3e59cd 100644
--- a/NEWS
+++ b/NEWS
@@ -2,12 +2,15 @@ Overview of changes from libfolks 0.6.4.1 to libfolks 0.6.5
 =============================================================
 Bugs fixed:
 * Bug 662285 â Error with email -> im_addresses when updating a contact
+* Bug 662433 â AbstractFieldDetails.equal() is ambiguous about checking
+  parameters.
 
 API changes:
 * Add AbstractFieldDetails.id to identify instances of details
 * Deprecate PostalAddress.uid in favor of AbstractFieldDetails.id
 * Deprecate NoteFieldDetails.uid in favor of AbstractFieldDetails.id
 * Deprecate Role.uid in favor of AbstractFieldDetails.id
+* Add AbstractFieldDetails.values_equal() to compare values (but not parameters)
 
 Behavior changes:
 * PostalAddress.equal() now ignores PostalAddress.uid
diff --git a/folks/abstract-field-details.vala b/folks/abstract-field-details.vala
index c89e762..f54670a 100644
--- a/folks/abstract-field-details.vala
+++ b/folks/abstract-field-details.vala
@@ -229,33 +229,32 @@ public abstract class Folks.AbstractFieldDetails<T> : Object
     }
 
   /**
-   * An equality function for { link AbstractFieldDetails}.
+   * A fairly-strict equality function for { link AbstractFieldDetails}.
    *
-   * This defaults to string comparison of the
-   * { link AbstractFieldDetails.value}s if the generic type is string;
-   * otherwise, direct pointer comparison of the
-   * { link AbstractFieldDetails.value}s.
+   * This function compares:
+   *  * { link AbstractFieldDetails.value}s
+   *  * { link AbstractFieldDetails.parameters}
+   *
+   * And does not compare:
+   *  * { link AbstractFieldDetails.id}s
+   *
+   * See the description of { link AbstractFieldDetails.values_equal} for
+   * details on the value comparison.
+   *
+   * To check equality not including the parameters, see
+   * { link AbstractFieldDetails.values_equal}.
    *
    * @param that another { link AbstractFieldDetails}
    *
    * @return whether the elements are equal
    *
+   * @see AbstractFieldDetails.parameters_equal
+   * @see AbstractFieldDetails.values_equal
    * @since 0.6.0
    */
   public virtual bool equal (AbstractFieldDetails<T> that)
     {
-      EqualFunc equal_func = direct_equal;
-
-      if (typeof (T) == typeof (string))
-        equal_func = str_equal;
-
-      if ((this.get_type () != that.get_type ()) ||
-          !equal_func (this.value, that.value))
-        {
-          return false;
-        }
-
-      return this.parameters_equal<T> (that);
+      return this.values_equal<T> (that) && this.parameters_equal<T> (that);
     }
 
   /**
@@ -320,6 +319,51 @@ public abstract class Folks.AbstractFieldDetails<T> : Object
     }
 
   /**
+   * An equality function which does not consider parameters.
+   *
+   * Specific classes may override this function to provide "smart" value
+   * comparisons (eg, considering the phone number values "+1 555 123 4567" and
+   * "123-4567" equal). If you wish to do strict comparisons, simply compare the
+   * { link AbstractFieldDetails.value}s directly.
+   *
+   * This function compares:
+   *  * { link AbstractFieldDetails.value}s
+   *
+   * And does not compare:
+   *  * { link AbstractFieldDetails.parameters}
+   *  * { link AbstractFieldDetails.id}s
+   *
+   * This defaults to string comparison of the
+   * { link AbstractFieldDetails.value}s if the generic type is string;
+   * otherwise, direct pointer comparison of the
+   * { link AbstractFieldDetails.value}s.
+   *
+   * @param that another { link AbstractFieldDetails}
+   *
+   * @return whether the elements' { link AbstractFieldDetails.value}s are
+   * equal.
+   *
+   * @see AbstractFieldDetails.equal
+   * @see AbstractFieldDetails.parameters_equal
+   * @since UNRELEASED
+   */
+  public virtual bool values_equal (AbstractFieldDetails<T> that)
+    {
+      EqualFunc equal_func = direct_equal;
+
+      if (typeof (T) == typeof (string))
+        equal_func = str_equal;
+
+      if ((this.get_type () != that.get_type ()) ||
+          !equal_func (this.value, that.value))
+        {
+          return false;
+        }
+
+      return true;
+    }
+
+  /**
    * A hash function for the { link AbstractFieldDetails}.
    *
    * This defaults to a string hash of the
diff --git a/folks/phone-details.vala b/folks/phone-details.vala
index 384c05a..95aff2b 100644
--- a/folks/phone-details.vala
+++ b/folks/phone-details.vala
@@ -85,6 +85,18 @@ public class Folks.PhoneFieldDetails : AbstractFieldDetails<string>
       if (that_fd == null)
         return false;
 
+      return this.values_equal (that_fd);
+    }
+
+  /**
+   * { inheritDoc}
+   */
+  public override bool values_equal (AbstractFieldDetails<string> that)
+    {
+      var that_fd = that as PhoneFieldDetails;
+      if (that_fd == null)
+        return false;
+
       var n1 = this._drop_extension (this.get_normalised ());
       var n2 = this._drop_extension (that_fd.get_normalised ());
 
diff --git a/folks/potential-match.vala b/folks/potential-match.vala
index 8f4d528..44ac2d2 100644
--- a/folks/potential-match.vala
+++ b/folks/potential-match.vala
@@ -153,7 +153,7 @@ public class Folks.PotentialMatch : Object
         {
           foreach (var phone_fd_b in set_b)
             {
-              if (phone_fd_a.equal (phone_fd_b))
+              if (phone_fd_a.values_equal (phone_fd_b))
                 {
                   this._result = MatchResult.HIGH;
                   return;