actor: Add ActorIter.is_valid()

It can be useful to check whether a ClutterActorIter is currently valid,
i.e. if the iterator has been initialized *and* if the actor to which it
refers to hasn't been updated.

We can also use the is_valid() method in the conformance test suite to
check that initialization has been successful, and that changing the
children list through the ClutterActorIter API leaves the iterator in a
valid state.

clutter/clutter-actor.c

@@ -17193,6 +17193,33 @@ clutter_actor_iter_init (ClutterActorIter *iter,
   ri->age = root->priv->age;
 }
 
+/**
+ * clutter_actor_iter_is_valid:
+ * @iter: a #ClutterActorIter
+ *
+ * Checks whether a #ClutterActorIter is still valid.
+ *
+ * An iterator is considered valid if it has been initialized, and
+ * if the #ClutterActor that it refers to hasn't been modified after
+ * the initialization.
+ *
+ * Return value: %TRUE if the iterator is valid, and %FALSE otherwise
+ *
+ * Since: 1.12
+ */
+gboolean
+clutter_actor_iter_is_valid (const ClutterActorIter *iter)
+{
+  RealActorIter *ri = (RealActorIter *) iter;
+
+  g_return_val_if_fail (iter != NULL, FALSE);
+
+  if (ri->root == NULL)
+    return FALSE;
+
+  return ri->root->priv->age == ri->age;
+}
+
 /**
  * clutter_actor_iter_next:
  * @iter: a #ClutterActorIter

clutter/clutter-actor.h

@@ -617,6 +617,8 @@ CLUTTER_AVAILABLE_IN_1_10
 void                            clutter_actor_iter_remove                       (ClutterActorIter           *iter);
 CLUTTER_AVAILABLE_IN_1_10
 void                            clutter_actor_iter_destroy                      (ClutterActorIter           *iter);
+CLUTTER_AVAILABLE_IN_1_12
+gboolean                        clutter_actor_iter_is_valid                     (const ClutterActorIter     *iter);
 
 /* Transformations */
 gboolean                        clutter_actor_is_rotated                        (ClutterActor               *self);

clutter/clutter.symbols

@@ -178,6 +178,7 @@ clutter_actor_is_rotated
 clutter_actor_is_scaled
 clutter_actor_iter_destroy
 clutter_actor_iter_init
+clutter_actor_iter_is_valid
 clutter_actor_iter_next
 clutter_actor_iter_prev
 clutter_actor_iter_remove