useful list functions

[Maciej Stachowiak <mjs eazel com>]

Here's prototypes outlining some list functions that I think would be
useful for glib HEAD. Most of these are already implemented and in use
(sometimes in slight variants) in Nautilus, gnome-vfs, OAF or other
places; others are things I have wished I had in specifics situations.

I can provide a patch with code and test cases for whichever of these
are approved.

 - Maciej

----------------

/* extra predicates */

/* the next too could trivial be inline functions or macros I guess,
   but are damn useful */
gboolean   g_list_has_exactly_one_item   (GList                      *list);
gboolean   g_list_has_more_than_one_item (GList                      *list);

/* compare for queality elementwise */
gboolean   g_list_equal                  (GList                      *a,
                                          GList                      *b,
                                          GCompareFunc                func);


/* Additional operators */

/* just like for_each, but guaranteed safe against deletion from inside `function' */
void       g_list_safe_for_each               (GList                 *list,
                                               GFunc                  function,
                                               gpointer               user_data);

/* Taking `function' as a predicate with 0 true and nonzero false,
   destructively partition the list, returning the list for which the
   predicate is satisfied, and putting the list for which it is not
   satisfied in the "removed" out argument. */


GList *    g_list_partition                   (GList                 *list,
                                               GCompareFunc           function,
                                               gpointer               user_data,
                                               GList                **removed);

/* Just like `map' in Lisp, Scheme or Perl, i.e. like for_each but
   return a list of the results. (non-destructive) */

typedef   gpointer (*GMapFunc)                (gpointer               data,
                                               gpointer               user_data); 

GList *    g_list_map                         (GList                 *list,
                                               GFunc                  predicate,
                                               gpointer               user_data);

/* nonnegative values index from the beginning of the list, negative values
   from the end [or I could add two gboolean from_end paramters] */
GList *    g_list_copy_sublist                (GList                 *list,
                                               gint                   start,
                                               gint                   end);

GList *    g_list_delete_duplicates           (GList                 *list,
                                               GFreeFunc              func);


/* Free a list and all elements */
void       g_list_free_deep_custom            (GList                 *list, 
                                               GFreeFunc              element_free_func);

/* Free list and free all elements w/ g_free */
void       nautilus_g_list_free_deep          (GList                 *list);



/* lists viewed as stacks */
gpointer   g_list_pop                         (GList                *list);
#define    g_list_push(list,element)           g_list_prepend ((list),(element))



/* "custom" versions for functions that could use them */

GList*     g_list_remove_custom               (GList                *list,
                                               GCompareFunc          func
                                               gpointer              user_data);

GList *    g_list_delete_duplicates_custom    (GList                *list,
                                               GCompareFunc          compare
                                               GFreeFunc             free_func);



/* variants for anything that takes a GCompareFunc which allow a
   user_data arg to the comparison function (you have no idea how much
   it sucks not to have this when you need it) */

typedef gint    (*GExtendedCompareFunc)       (gconstpointer    a,
                                               gconstpointer    b,
                                               gpointer         user_data);


GList*     g_list_insert_sorted_extended      (GList                *list,
                                               gpointer              data,
                                               GExtendedCompareFunc  func,
                                               gpointer              user_data);


GList*     g_list_sort_extended               (GList                *list,
                                               GExtendedCompareFunc  compare_func,
                                               gpointer              user_data);


gboolean   g_list_equal_extended              (GList                *a,
                                               GList                *b,
                                               GExtendedCompareFunc  func,
                                               gpointer              user_data);

/* could be called g_list_delete_duplicates_custom_extended, but that
   seemed excessive */

GList *    g_list_delete_duplicates_extended  (GList                *list,
                                               GExtendedCompareFunc  compare
                                               gpointer              user_data
                                               GFreeFunc             free_func);