warning about invalid tree model iterators

[Tim Janik <timj imendio com>]

hi all.

tree model iterators are easily advanced/setup/created in a way that yields
an invalid iterator, because the denoted location doesn't exist (anymore).
to cath those cases, the tree model API returns booleans indicating success,
but testing those booleans is easily forgotton and a common error source.

to help the compiler catch these mistakes, i've prepared a patch that adds
G_GNUC_WARN_UNUSED_RESULT to all relevant iterator functions, and intend
to commit that next week unless objections pop up. in principle it does:

 gboolean          gtk_tree_model_iter_next       (GtkTreeModel *tree_model,
-						  GtkTreeIter  *iter);
+						  GtkTreeIter  *iter) G_GNUC_WARN_UNUSED_RESULT;

the exact diff is attached.

---
ciaoTJ

Index: ChangeLog
===================================================================
RCS file: /cvs/gnome/gtk+/ChangeLog,v
retrieving revision 1.7530
diff -u -p -r1.7530 ChangeLog
--- ChangeLog	16 Feb 2006 18:34:09 -0000	1.7530
+++ ChangeLog	17 Feb 2006 13:22:29 -0000
@@ -1,3 +1,10 @@
+Fri Feb 17 14:20:29 2006  Tim Janik  <timj imendio com>
+
+	* gtk/gtktreemodel.h: 
+	* gtk/gtktextbtree.h: added G_GNUC_WARN_UNUSED_RESULT warnings for
+	iterator functions, to avoid invalid iterators go unnoticed,
+	suggested by Markku Vire <markku vire movial fi>.
+
 2006-02-16  Federico Mena Quintero  <federico novell com>
 
 	* gtk/gtkfilechooserdialog.c (gtk_file_chooser_dialog_map): Call
Index: gtk/gtktextbtree.h
===================================================================
RCS file: /cvs/gnome/gtk+/gtk/gtktextbtree.h,v
retrieving revision 1.26
diff -u -p -r1.26 gtktextbtree.h
--- gtk/gtktextbtree.h	13 Jul 2005 05:44:21 -0000	1.26
+++ gtk/gtktextbtree.h	17 Feb 2006 13:22:30 -0000
@@ -155,10 +155,10 @@ void     _gtk_text_btree_get_iter_at_lin
                                                    gint                byte_index);
 gboolean _gtk_text_btree_get_iter_from_string     (GtkTextBTree       *tree,
                                                    GtkTextIter        *iter,
-                                                   const gchar        *string);
+                                                   const gchar        *string) G_GNUC_WARN_UNUSED_RESULT;
 gboolean _gtk_text_btree_get_iter_at_mark_name    (GtkTextBTree       *tree,
                                                    GtkTextIter        *iter,
-                                                   const gchar        *mark_name);
+                                                   const gchar        *mark_name) G_GNUC_WARN_UNUSED_RESULT;
 void     _gtk_text_btree_get_iter_at_mark         (GtkTextBTree       *tree,
                                                    GtkTextIter        *iter,
                                                    GtkTextMark        *mark);
@@ -170,10 +170,10 @@ void     _gtk_text_btree_get_iter_at_lin
                                                    gint                byte_offset);
 gboolean _gtk_text_btree_get_iter_at_first_toggle (GtkTextBTree       *tree,
                                                    GtkTextIter        *iter,
-                                                   GtkTextTag         *tag);
+                                                   GtkTextTag         *tag) G_GNUC_WARN_UNUSED_RESULT;
 gboolean _gtk_text_btree_get_iter_at_last_toggle  (GtkTextBTree       *tree,
                                                    GtkTextIter        *iter,
-                                                   GtkTextTag         *tag);
+                                                   GtkTextTag         *tag) G_GNUC_WARN_UNUSED_RESULT;
 
 void     _gtk_text_btree_get_iter_at_child_anchor  (GtkTextBTree       *tree,
                                                     GtkTextIter        *iter,
Index: gtk/gtktreemodel.h
===================================================================
RCS file: /cvs/gnome/gtk+/gtk/gtktreemodel.h,v
retrieving revision 1.51
diff -u -p -r1.51 gtktreemodel.h
--- gtk/gtktreemodel.h	13 Jul 2005 21:27:03 -0000	1.51
+++ gtk/gtktreemodel.h	17 Feb 2006 13:22:30 -0000
@@ -136,8 +136,8 @@ GType        gtk_tree_path_get_type     
 gint         gtk_tree_path_compare          (const GtkTreePath *a,
 					     const GtkTreePath *b);
 void         gtk_tree_path_next             (GtkTreePath       *path);
-gboolean     gtk_tree_path_prev             (GtkTreePath       *path);
-gboolean     gtk_tree_path_up               (GtkTreePath       *path);
+gboolean     gtk_tree_path_prev             (GtkTreePath       *path) G_GNUC_WARN_UNUSED_RESULT;
+gboolean     gtk_tree_path_up               (GtkTreePath       *path) G_GNUC_WARN_UNUSED_RESULT;
 void         gtk_tree_path_down             (GtkTreePath       *path);
 
 gboolean     gtk_tree_path_is_ancestor      (GtkTreePath       *path,
@@ -191,14 +191,14 @@ GType             gtk_tree_model_get_col
 /* Iterator movement */
 gboolean          gtk_tree_model_get_iter        (GtkTreeModel *tree_model,
 						  GtkTreeIter  *iter,
-						  GtkTreePath  *path);
+						  GtkTreePath  *path) G_GNUC_WARN_UNUSED_RESULT;
 gboolean          gtk_tree_model_get_iter_from_string (GtkTreeModel *tree_model,
 						       GtkTreeIter  *iter,
-						       const gchar  *path_string);
+						       const gchar  *path_string) G_GNUC_WARN_UNUSED_RESULT;
 gchar *           gtk_tree_model_get_string_from_iter (GtkTreeModel *tree_model,
                                                        GtkTreeIter  *iter);
 gboolean          gtk_tree_model_get_iter_first  (GtkTreeModel *tree_model,
-						  GtkTreeIter  *iter);
+						  GtkTreeIter  *iter) G_GNUC_WARN_UNUSED_RESULT;
 GtkTreePath *     gtk_tree_model_get_path        (GtkTreeModel *tree_model,
 						  GtkTreeIter  *iter);
 void              gtk_tree_model_get_value       (GtkTreeModel *tree_model,
@@ -206,10 +206,10 @@ void              gtk_tree_model_get_val
 						  gint          column,
 						  GValue       *value);
 gboolean          gtk_tree_model_iter_next       (GtkTreeModel *tree_model,
-						  GtkTreeIter  *iter);
+						  GtkTreeIter  *iter) G_GNUC_WARN_UNUSED_RESULT;
 gboolean          gtk_tree_model_iter_children   (GtkTreeModel *tree_model,
 						  GtkTreeIter  *iter,
-						  GtkTreeIter  *parent);
+						  GtkTreeIter  *parent) G_GNUC_WARN_UNUSED_RESULT;
 gboolean          gtk_tree_model_iter_has_child  (GtkTreeModel *tree_model,
 						  GtkTreeIter  *iter);
 gint              gtk_tree_model_iter_n_children (GtkTreeModel *tree_model,
@@ -217,10 +217,10 @@ gint              gtk_tree_model_iter_n_
 gboolean          gtk_tree_model_iter_nth_child  (GtkTreeModel *tree_model,
 						  GtkTreeIter  *iter,
 						  GtkTreeIter  *parent,
-						  gint          n);
+						  gint          n) G_GNUC_WARN_UNUSED_RESULT;
 gboolean          gtk_tree_model_iter_parent     (GtkTreeModel *tree_model,
 						  GtkTreeIter  *iter,
-						  GtkTreeIter  *child);
+						  GtkTreeIter  *child) G_GNUC_WARN_UNUSED_RESULT;
 void              gtk_tree_model_ref_node        (GtkTreeModel *tree_model,
 						  GtkTreeIter  *iter);
 void              gtk_tree_model_unref_node      (GtkTreeModel *tree_model,