add awful.util.table.cycle

add awful.util.table.cycle to iterate through elements that match given
condition

This will help writing concise code when one wants to apply a function to
(read, take some action) on a select list of elements in a table (of say,
clients and tags).

Signed-off-by: Anurag Priyam <anurag08priyam@gmail.com>
Signed-off-by: Uli Schlachter <psychon@znc.in>

lib/awful/util.lua.in

@@ -367,4 +367,25 @@ function table.clone(t)
     return c
 end
 
+---
+-- Returns an iterator to cycle through, starting from the first element or the
+-- given index, all elments of a table that match a given criteria.
+-- @param t      the table to iterate
+-- @param filter a function that returns true to indicate a positive match
+-- @param start  what index to start iterating from.  Default is 1 (=> start of
+-- the table)
+function table.cycle(t, filter, start)
+    local count  = 0
+    local index  = start or 1
+    local length = #t
+
+    return function ()
+        while count < length do
+            local item = t[index]
+            index = cycle(#t, index + 1)
+            count = count + 1
+            if filter(item) then return item end
+        end
+    end
+end
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80