[california] Improvements to the California.Iterable class and helpers

[Jim Nelson <jnelson src gnome org>]

commit 4a4ad2f835a4a09adca9053dd0c985497881c426
Author: Jim Nelson <jim yorba org>
Date:   Tue Jul 1 16:07:13 2014 -0700

    Improvements to the California.Iterable class and helpers

 src/collection/collection-iterable.vala |   81 +++++++++++++++++++++++++-----
 1 files changed, 67 insertions(+), 14 deletions(-)
---
diff --git a/src/collection/collection-iterable.vala b/src/collection/collection-iterable.vala
index b551cd2..395247c 100644
--- a/src/collection/collection-iterable.vala
+++ b/src/collection/collection-iterable.vala
@@ -8,14 +8,38 @@ namespace California {
 
 /**
  * Take a Gee object and return a California.Iterable for convenience.
+ *
+ * An empty Gee.Iterable is created and used if null is passed in.
  */
-public California.Iterable<G> traverse<G>(Gee.Iterable<G> i) {
-    return new California.Iterable<G>(i.iterator());
+public California.Iterable<G> traverse<G>(Gee.Iterable<G>? gee_iterable) {
+    Gee.Iterable<G>? iterable = gee_iterable ?? new Gee.ArrayList<G>();
+    
+    return new California.Iterable<G>(iterable.iterator());
 }
 
 /**
- * Take some non-null items (all must be of type G) and return a
- * California.Iterable for convenience.
+ * Like { link traverse}, but make a copy of the Gee.Iterable to allow for safe iteration over
+ * it.
+ *
+ * "Safe iteration" means later operations that remove elements while iterating do not cause an
+ * assertion.
+ *
+ * An empty Gee.Iterable is created and used if null is passed in.
+ */
+public California.Iterable<G> traverse_safely<G>(Gee.Iterable<G>? iterable) {
+    Gee.ArrayList<G> list = new Gee.ArrayList<G>();
+    
+    if (iterable != null) {
+        foreach (G element in iterable)
+            list.add(element);
+    }
+    
+    return California.traverse<G>(list);
+}
+
+/**
+ * Take some non-null items (all must be of type G) and return a California.Iterable for
+ * convenience.
  */
 public California.Iterable<G> iterate<G>(G g, ...) {
     va_list args = va_list();
@@ -30,27 +54,35 @@ public California.Iterable<G> iterate<G>(G g, ...) {
 }
 
 /**
- * Take a non-null array of non-null items (all of type G) and return a California.Iterable
- * for convenience.
+ * Take an array of non-null items (all of type G) and return a California.Iterable for convenience.
+ *
+ * An empty Gee.Iterable is created and used if null is passed in.
  */
-public California.Iterable<G> from_array<G>(G[] ar) {
+public California.Iterable<G> from_array<G>(G[]? ar) {
     Gee.ArrayList<G> list = new Gee.ArrayList<G>();
-    foreach (G item in ar)
-        list.add(item);
+    
+    if (ar != null) {
+        foreach (G item in ar)
+            list.add(item);
+    }
     
     return California.traverse<G>(list);
 }
 
 /**
  * Returns an { link Iterable} of Unicode characters for each in the supplied string.
+ *
+ * An empty Gee.Iterable is created and used if null is passed in.
  */
-public Iterable<unichar> from_string(string str) {
+public Iterable<unichar> from_string(string? str) {
     Gee.ArrayList<unichar> list = new Gee.ArrayList<unichar>();
     
-    int index = 0;
-    unichar ch;
-    while (str.get_next_char(ref index, out ch))
-        list.add(ch);
+    if (!String.is_empty(str)) {
+        int index = 0;
+        unichar ch;
+        while (str.get_next_char(ref index, out ch))
+            list.add(ch);
+    }
     
     return California.traverse<unichar>(list);
 }
@@ -72,6 +104,11 @@ public class Iterable<G> : Object {
     public delegate string? ToString<G>(G element);
     
     /**
+     * For simple iteration of the { link Iterable}.
+     */
+    public delegate void Iterate<G>(G element);
+    
+    /**
      * A private class that lets us take a California.Iterable and convert it back
      * into a Gee.Iterable.
      */
@@ -106,6 +143,22 @@ public class Iterable<G> : Object {
         return i;
     }
     
+    /**
+     * Be called for each element in the { link Iterable}.
+     *
+     * No transformation of the Iterable is made.  The returned Iterable is for the same set of
+     * elements as had been iterated over.
+     */
+    public Iterable<G> iterate(Iterate<G> iteratee) {
+        Gee.ArrayList<G> list = new Gee.ArrayList<G>();
+        foreach (G g in this) {
+            iteratee(g);
+            list.add(g);
+        }
+        
+        return new Iterable<G>(list.iterator());
+    }
+    
     public Iterable<A> map<A>(Gee.MapFunc<A, G> f) {
         return new Iterable<A>(i.map<A>(f));
     }