Version 2.1.0

README.md

@@ -74,6 +74,30 @@ lume.weightedchoice({ ["cat"] = 10, ["dog"] = 5, ["frog"] = 0 })
 -- Returns either "cat" or "dog" with "cat" being twice as likely to be chosen.
 ```
 
+### lume.push(t, ...)
+Pushes all the given values to the end of the table `t` and returns the pushed
+values. Nil values are ignored.
+```lua
+local t = { 1, 2, 3 }
+lume.push(t, 4, 5) -- `t` becomes { 1, 2, 3, 4, 5 }
+```
+
+### lume.remove(t, x)
+Removes the first instance of the value `x` if it exists in the table `t`.
+Returns `x`.
+```lua
+local t = { 1, 2, 3 }
+lume.remove(t, 2) -- `t` becomes { 1, 3 }
+```
+
+### lume.clear(t)
+Nils all the values in the table `t`, this renders the table empty. Returns
+`t`.
+```lua
+local t = { 1, 2, 3 }
+lume.clear(t) -- `t` becomes {}
+```
+
 ### lume.shuffle(t)
 Returns a shuffled copy of the array `t`.
 
@@ -149,6 +173,14 @@ an array and retains its original keys.
 lume.filter({1, 2, 3, 4}, function(x) return x % 2 == 0 end) -- Returns {2, 4}
 ```
 
+### lume.reject(t, fn [, retainkeys])
+The opposite of `lume.filter()`: Calls `fn` on each value of `t` table; returns
+a new table with only the values where `fn` returned false. If `retainkeys` is
+true the table is not treated as an array and retains its original keys.
+```lua
+lume.reject({1, 2, 3, 4}, function(x) return x % 2 == 0 end) -- Returns {1, 3}
+```
+
 ### lume.merge(...)
 Returns a new table with all the given tables merged together. If a key exists
 in multiple tables the right-most table's value is used.
@@ -396,6 +428,36 @@ as calling `lume.chain()`.
 lume({1, 2, 3}):each(print) -- Prints 1, 2 then 3 on separate lines
 ```
 
+## Iteratee functions
+Several lume functions allow a `table`, `string` or `nil` to be used in place
+of their iteratee function argument. The functions that provide this behaviour
+are: `map()`, `all()`, `any()`, `filter()`, `reject()`, `match()` and
+`count()`.
+
+If the argument is `nil` then each value will return itself.
+```lua
+lume.filter({ true, true, false, true }, nil) -- { true, true, true }
+```
+
+If the argument is a `string` then each value will be assumed to be a table,
+and will return the value of the key which matches the string.
+``` lua
+local t = {{ z = "cat" }, { z = "dog" }, { z = "owl" }}
+lume.map(t, "z") -- Returns { "cat", "dog", "owl" }
+```
+
+If the argument is a `table` then each value will return `true` or `false`,
+depending on whether the values at each of the table's keys match the
+collection's value's values.
+```lua
+local t = {
+  { age = 10, type = "cat" },
+  { age = 8,  type = "dog" },
+  { age = 10, type = "owl" },
+}
+lume.count(t, { age = 10 }) -- returns 2
+```
+
 
 ## License
 

lume.lua

@@ -1,13 +1,13 @@
 --
 -- lume
 --
--- Copyright (c) 2015, rxi
+-- Copyright (c) 2015 rxi
 --
 -- This library is free software; you can redistribute it and/or modify it
 -- under the terms of the MIT license. See LICENSE for details.
 --
 
-local lume = { _version = "2.0.0" }
+local lume = { _version = "2.1.0" }
 
 local pairs, ipairs = pairs, ipairs
 local type, assert, unpack = type, assert, unpack or table.unpack
@@ -43,7 +43,7 @@ local iscallable = function(x)
 end
 
 local isarray = function(x)
-  return (x and x[1]) and true or false
+  return (type(x) == "table" and x[1] ~= nil) and true or false
 end
 
 local iternil = function()
@@ -51,13 +51,12 @@ local iternil = function()
 end
 
 local getiter = function(x)
-  if x == nil then
-    return iternil
-  elseif isarray(x) then
+  if isarray(x) then
     return ipairs
-  else
+  elseif type(x) == "table" then
     return pairs
   end
+  error("expected table", 3)
 end
 
 local iteratee = function(x)
@@ -149,6 +148,41 @@ function lume.weightedchoice(t)
 end
 
 
+function lume.push(t, ...)
+  local n = select("#", ...)
+  for i = 1, n do
+    t[#t + 1] = select(i, ...)
+  end
+  return ...
+end
+
+
+function lume.remove(t, x) 
+  local iter = getiter(t)
+  for i, v in iter(t) do
+    if v == x then
+      if isarray(t) then
+        table.remove(t, i)
+        break
+      else
+        t[i] = nil
+        break
+      end
+    end
+  end
+  return x
+end
+
+
+function lume.clear(t)
+  local iter = getiter(t)
+  for k, v in iter(t) do
+    t[k] = nil
+  end
+  return t
+end
+
+
 function lume.shuffle(t)
   local rtn = {}
   for i = 1, #t do
@@ -225,9 +259,18 @@ end
 
 
 function lume.reduce(t, fn, first)
-  local acc = first or t[1]
-  assert(acc, "reduce of an empty array with no first value")
-  for i = first and 1 or 2, #t do acc = fn(acc, t[i]) end
+  local acc = first
+  local started = first and true or false
+  local iter = getiter(t)
+  for k, v in iter(t) do
+    if started then
+      acc = fn(acc, v)
+    else
+      acc = v
+      started = true
+    end
+  end
+  assert(started, "reduce of an empty table with no first value")
   return acc
 end
 
@@ -245,8 +288,31 @@ function lume.filter(t, fn, retainkeys)
   fn = iteratee(fn)
   local iter = getiter(t)
   local rtn = {}
-  for k, v in iter(t) do
-    if fn(v) then rtn[retainkeys and k or (#rtn + 1)] = v end
+  if retainkeys then
+    for k, v in iter(t) do
+      if fn(v) then rtn[k] = v end
+    end
+  else
+    for k, v in iter(t) do
+      if fn(v) then rtn[#rtn + 1] = v end
+    end
+  end
+  return rtn
+end
+
+
+function lume.reject(t, fn, retainkeys)
+  fn = iteratee(fn)
+  local iter = getiter(t)
+  local rtn = {}
+  if retainkeys then
+    for k, v in iter(t) do
+      if not fn(v) then rtn[k] = v end
+    end
+  else
+    for k, v in iter(t) do
+      if not fn(v) then rtn[#rtn + 1] = v end
+    end
   end
   return rtn
 end
@@ -269,9 +335,11 @@ function lume.concat(...)
   local rtn = {}
   for i = 1, select("#", ...) do
     local t = select(i, ...)
-    local iter = getiter(t)
-    for k, v in iter(t) do
-      rtn[#rtn + 1] = v
+    if t ~= nil then
+      local iter = getiter(t)
+      for k, v in iter(t) do
+        rtn[#rtn + 1] = v
+      end
     end
   end
   return rtn
@@ -400,8 +468,16 @@ end
 
 
 function lume.combine(...)
+  local n = select('#', ...)
+  if n == 0 then return noop end
+  if n == 1 then 
+    local fn = select(1, ...)
+    if not fn then return noop end
+    assert(iscallable(fn), "expected a function or nil")
+    return fn
+  end
   local funcs = {}
-  for i = 1, select("#", ...) do
+  for i = 1, n do
     local fn = select(i, ...)
     if fn ~= nil then
       assert(iscallable(fn), "expected a function or nil")

test/test_lume.lua

@@ -106,6 +106,45 @@ tests["lume.weightedchoice"] = function()
   tester.test.error( lume.weightedchoice, { a = 1, b = -1 }   )
 end
 
+-- lume.push
+tests["lume.push"] = function()
+  local t = { 1, 2 }
+  lume.push(t, 3, 4)
+  testeq(t, { 1, 2, 3, 4 })
+  lume.push(t, 5, nil, 6, nil, 7)
+  testeq(t, { 1, 2, 3, 4, 5, 6, 7 })
+  lume.push(t)
+  testeq(t, { 1, 2, 3, 4, 5, 6, 7 })
+  local x, y = lume.push(t, 123, 456)
+  testeq(x, 123)
+  testeq(y, 456)
+end
+
+-- lume.remove
+tests["lume.remove"] = function()
+  local t = { 1, 2, 3, 4, 5 }
+  lume.remove(t, 3)
+  testeq(t, { 1, 2, 4, 5  })
+  lume.remove(t, 1)
+  testeq(t, { 2, 4, 5 })
+  lume.remove(t, 5)
+  testeq(t, { 2, 4 })
+  local m = { a = 1, b = 2, c = 3 }
+  local x = lume.remove(t, 123)
+  testeq(x, 123)
+end
+
+-- lume.clear
+tests["lume.clear"] = function()
+  local t = { 1, 2, 3 }
+  lume.clear(t)
+  testeq(t, {})
+  local m = { a = 1, b = 2, c = 3 }
+  lume.clear(m)
+  testeq(m, {})
+  testeq( lume.clear(t) == t, true )
+end
+
 -- lume.shuffle
 tests["lume.shuffle"] = function()
   local t = {1, 2, 3, 4, 5}
@@ -191,6 +230,9 @@ tests["lume.reduce"] = function()
   testeq( lume.reduce({1, 2, 3, 4}, add, 5),          15          )
   testeq( lume.reduce({1}, add),                      1           )
   testeq( lume.reduce({}, concat, "potato"),          "potato"    )
+  testeq( lume.reduce({a=1, b=2}, add, 5),            8           )
+  testeq( lume.reduce({a=1, b=2}, add),               3           )
+  tester.test.error(lume.reduce, {}, add)
 end
 
 -- lume.set
@@ -214,6 +256,16 @@ tests["lume.filter"] = function()
   testeq( t, {{ x=1, y=1 }, {x=1, y=3}} )
 end
 
+-- lume.reject
+tests["lume.reject"] = function()
+  local t = lume.reject({1, 2, 3, 4, 5}, function(x) return x % 2 == 0 end  ) 
+  testeq( t, {1, 3, 5} )
+  local t = lume.reject({a=1, b=2, c=3}, function(x) return x == 2 end, true) 
+  testeq( t, {a=1, c=3} )
+  local t = lume.reject({{ x=1, y=1 }, { x=2, y=2 }, { x=1, y=3 }}, { x = 1 })
+  testeq( t, {{ x=2, y=2 }} )
+end
+
 -- lume.merge
 tests["lume.merge"] = function()
   testeq( lume.merge(),                       {}              )
@@ -370,6 +422,12 @@ tests["lume.combine"] = function()
   fn = lume.combine(nil, a, nil, b, nil)
   fn(10, 20)
   testeq( acc, 230 )
+  local x = false
+  fn = lume.combine(function() x = true end)
+  fn()
+  testeq( x, true )
+  testeq( type(lume.combine(nil)), "function" )
+  testeq( type(lume.combine()),    "function" )
 end
 
 -- lume.call