G_BEGIN_DECLS
-struct _ModestPair {
+typedef struct _ModestPair {
gpointer *first;
gpointer *second;
gboolean own;
-};
-typedef struct _ModestPair ModestPair;
+} ModestPair;
+
+typedef GSList ModestPairList;
/**
- * modest_pait_new
+ * modest_pair_new:
+ * @first: the first element of the pair
+ * @second: the second element of the pair
+ * @own: does the pair own the item (ie. should the items be freed when the pair is destroyed)
*
* create a new ModestPair instance
*
* Returns: a newly allocated ModestPair instance
*/
-ModestPair* modest_pair_new (gpointer first, gpointer second, gboolean own);
-void modest_pair_destroy (ModestPair *pair);
+ModestPair* modest_pair_new (gpointer first, gpointer second, gboolean own);
+
-GSList *modest_pair_gslist_destroy (GSList *pairs);
+/**
+ * modest_pair_free:
+ * @self: a valid ModestPair instance or NULL
+ *
+ * free a ModestPair instance. If it was created with own==TRUE, the elements
+ * will be g_free'd as well. If pair==NULL, nothing will be done.
+ */
+void modest_pair_free (ModestPair *self);
+
+/**
+ * modest_pair_list_free:
+ * @pairs: a valid ModestPairList
+ *
+ * Convenience function to destroy all pairs in a list and the list itself.
+ *
+ */
+void modest_pair_list_free (ModestPairList *pairs);
+
+/**
+ * modest_pair_list_find_by_first
+ * @pairs: A valid ModestPairList
+ * @first: The first element of the pair to be found.
+ * @func: The function to call for each element. It should return 0 when the desired element is found.
+ *
+ * Find an element with a matching first entry.
+ *
+ * Returns: a previously allocated ModestPair instance, or NULL if none was found.
+ */
+ModestPair* modest_pair_list_find_by_first_as_string (ModestPairList *pairs,
+ const gchar* first);
G_END_DECLS