[geary/mjog/invert-folder-class-hierarchy: 345/362] Geary.Email: Add `new_identifier_based_set` static method

[Michael Gratton <mjog src gnome org>]

commit d7f6286f7319f1b81732d95350a6956f0cc689e6
Author: Michael Gratton <mike vee net>
Date:   Wed Feb 17 21:25:22 2021 +1100

    Geary.Email: Add `new_identifier_based_set` static method
    
    Add some API docs about email object identity, add new method to
    support constructing sets emails based on their ids.

 src/engine/api/geary-email.vala | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)
---
diff --git a/src/engine/api/geary-email.vala b/src/engine/api/geary-email.vala
index b7b98fd52..2759534ee 100644
--- a/src/engine/api/geary-email.vala
+++ b/src/engine/api/geary-email.vala
@@ -1,6 +1,6 @@
 /*
  * Copyright 2016 Software Freedom Conservancy Inc.
- * Copyright 2018 Michael Gratton <mike vee net>
+ * Copyright 2018-2021 Michael Gratton <mike vee net>
  *
  * This software is licensed under the GNU Lesser General Public License
  * (version 2.1 or later).  See the COPYING file in this distribution.
@@ -25,6 +25,14 @@
  * a database. This can be checked via an email's {@link fields}
  * property, and if the currently loaded fields are not sufficient,
  * then additional fields can be loaded via a folder.
+ *
+ * Email objects are mutable and hence do not define equality. This
+ * makes them unsuitable for use in collections dependent on object
+ * identity, such as sets and maps. However they can be somewhat
+ * safely in these collections if their identity is based on their
+ * {@link id}, which is generally immutable. See {@link
+ * new_identifier_based_set} and {@link emails_to_map} for support for
+ * this.
  */
 public class Geary.Email : BaseObject, EmailHeaderSet {
 
@@ -179,6 +187,20 @@ public class Geary.Email : BaseObject, EmailHeaderSet {
         }
     }
 
+
+    /**
+     * Returns a new email set, with identity defined by identifier identity.
+     *
+     * Email objects are not immutable, hence do not define equality,
+     * which makes them
+     */
+    public static Gee.Set<Email>? new_identifier_based_set() {
+        return new Gee.HashSet<Geary.Email>(
+            e => e.id.hash(),
+            (e1, e2) => e1.id.equal_to(e2.id)
+        );
+    }
+
     /**
      * A unique identifier for the Email in the Folder.
      *