Version 1.2.1

Using lua pattern special chars in the `chars` argument of lume.trim()
are now handled correctly and treated like any other character.

README.md

@@ -64,6 +64,16 @@ raised.
 lume.randomchoice({true, false}) -- Returns either true or false
 ```
 
+### lume.weightedchoice(t)
+Takes the argument table `t` where the keys are the possible choices and the
+value is the choice's weight. A weight should be 0 or above, the larger the
+number the higher the probability of that choice being picked. If the table is
+empty, a weight is below zero or all the weights are 0 then an error is raised.
+```lua
+lume.weightedchoice({ ["cat"] = 10, ["dog"] = 5, ["frog"] = 0 })
+-- Returns either "cat" or "dog" with "cat" being twice as likely to be chosen.
+```
+
 ### lume.shuffle(t)
 Shuffles the values of array `t` in place, returns the array.
 
@@ -120,7 +130,7 @@ Returns a copy of the `t` table with all the duplicate values removed. If
 `retainkeys` is true the table is not treated as an array and retains its
 original keys.
 ```lua
-lume.set({2, 1, 2, "cat", "cat"}) -- Returns {1, 2, cat}
+lume.set({2, 1, 2, "cat", "cat"}) -- Returns {1, 2, "cat"}
 ```
 
 ### lume.filter(t, fn [, retainkeys])
@@ -190,6 +200,15 @@ seconds the function `fn` took to execute followed by `fn`'s returned values.
 lume.time(function(x) return x end, "hello") -- Returns 0, "hello"
 ```
 
+### lume.lambda(str)
+Takes a string lambda and returns a function. `str` should be a list of
+comma-separated parameters, followed by `->`, followed by the expression which
+will be evaluated and returned.
+```lua
+local f = lume.lambda "x,y -> 2*x+y"
+f(10, 5) -- Returns 25
+```
+
 ### lume.serialize(x)
 Serializes the argument `x` into a string which can be loaded again using
 `lume.deserialize()`. Only booleans, numbers, tables and strings can be
@@ -208,11 +227,12 @@ lume.deserialize("{1, 2, 3}") -- Returns {1, 2, 3}
 ```
 
 ### lume.split(str [, sep])
-Splits the string `str` into words and returns a table of the sub strings. If
-`sep` is provided the string will be split at any of the characters in `sep`
-instead of on whitespace.
+Returns an array of the words in the string `str`. If `sep` is provided it is
+used as the delimiter, consecutive delimiters are not grouped together and will
+delimit empty strings.
 ```lua
 lume.split("One two three") -- Returns {"One", "two", "three"}
+lume.split("a,b,,c", ",") -- Returns {"a", "b", "", "c"}
 ```
 
 ### lume.trim(str [, chars])

lume.lua

@@ -7,7 +7,25 @@
 -- under the terms of the MIT license. See LICENSE for details.
 --
 
-local lume = { _version = "1.1.2" }
+local lume = { _version = "1.2.1" }
+
+local pairs, ipairs = pairs, ipairs
+local type, assert, unpack = type, assert, unpack 
+local tostring, tonumber = tostring, tonumber
+local math_floor = math.floor
+local math_ceil = math.ceil
+local math_random = math.random
+local math_cos = math.cos
+local math_atan2 = math.atan2
+local math_sqrt = math.sqrt
+local math_abs = math.abs
+local math_min = math.min
+local math_max = math.max
+local math_pi = math.pi
+
+local patternescape = function(str)
+  return str:gsub("[%(%)%.%%%+%-%*%?%[%]%^%$]", "%%%1")
+end
 
 
 function lume.clamp(x, min, max)
@@ -17,7 +35,7 @@ end
 
 function lume.round(x, increment)
   if increment then return lume.round(x / increment) * increment end
-  return x > 0 and math.floor(x + .5) or math.ceil(x - .5)
+  return x > 0 and math_floor(x + .5) or math_ceil(x - .5)
 end
 
 
@@ -32,13 +50,13 @@ end
 
 
 function lume.smooth(a, b, amount)
-  local m = (1 - math.cos(lume.clamp(amount, 0, 1) * math.pi)) / 2
+  local m = (1 - math_cos(lume.clamp(amount, 0, 1) * math_pi)) / 2
   return a + (b - a) * m
 end
 
 
 function lume.pingpong(x)
-  return 1 - math.abs(1 - x % 2)
+  return 1 - math_abs(1 - x % 2)
 end
 
 
@@ -46,30 +64,45 @@ function lume.distance(x1, y1, x2, y2, squared)
   local dx = x1 - x2
   local dy = y1 - y2
   local s = dx * dx + dy * dy
-  return squared and s or math.sqrt(s)
+  return squared and s or math_sqrt(s)
 end
 
 
 function lume.angle(x1, y1, x2, y2)
-  return math.atan2(y2 - y1, x2 - x1)
+  return math_atan2(y2 - y1, x2 - x1)
 end
 
 
 function lume.random(a, b)
   if not a then a, b = 0, 1 end
   if not b then b = 0 end
-  return a + math.random() * (b - a)
+  return a + math_random() * (b - a)
 end
 
 
 function lume.randomchoice(t)
-  return t[math.random(#t)]
+  return t[math_random(#t)]
+end
+
+
+function lume.weightedchoice(t)
+  local sum = 0
+  for k, v in pairs(t) do
+    assert(v >= 0, "weight value less than zero")
+    sum = sum + v
+  end
+  assert(sum ~= 0, "all weights are zero")
+  local rnd = lume.random(sum)
+  for k, v in pairs(t) do
+    if rnd < v then return k end
+    rnd = rnd - v
+  end
 end
 
 
 function lume.shuffle(t)
   for i = 1, #t do
-    local r = math.random(#t)
+    local r = math_random(#t)
     t[i], t[r] = t[r], t[i]
   end
   return t
@@ -161,10 +194,11 @@ end
 
 
 function lume.slice(t, i, j)
-  i = i or 1
-  j = j and (j < 0 and (#t + j + 1) or j) or #t
+  local function index(x) return x < 0 and (#t + x + 1) or x end
+  i = i and index(i) or 1
+  j = j and index(j) or #t
   local rtn = {}
-  for i = math.max(i, 1), math.min(j, #t) do
+  for i = math_max(i, 1), math_min(j, #t) do
     rtn[#rtn + 1] = t[i]
   end
   return rtn
@@ -212,6 +246,19 @@ function lume.time(fn, ...)
 end
 
 
+local lambda_cache = {}
+
+function lume.lambda(str)
+  if not lambda_cache[str] then
+    local args, body = str:match([[^([%w,_ ]-)%->(.-)$]])
+    assert(args and body, "bad string lambda")
+    local s = "return function(" .. args .. ")\nreturn " .. body .. "\nend"
+    lambda_cache[str] = lume.dostring(s)
+  end
+  return lambda_cache[str]
+end
+
+
 function lume.serialize(x)
   local f = { string = function(v) return string.format("%q", v) end,
               number = tostring, boolean = tostring }
@@ -222,6 +269,8 @@ function lume.serialize(x)
     end
     return "{" .. table.concat(rtn) .. "}"
   end
+  local err = function(t,k) error("unsupported serialize type: " .. k) end
+  setmetatable(f, { __index = err })
   return f[type(x)](x)
 end
 
@@ -232,12 +281,19 @@ end
 
 
 function lume.split(str, sep)
-  return lume.array(str:gmatch("([^" .. (sep or "%s") .. "]+)"))
+  if not sep then
+    return lume.array(str:gmatch("([%S]+)"))
+  else
+    assert(sep ~= "", "empty separator")
+    local psep = patternescape(sep)
+    return lume.array((str..sep):gmatch("(.-)("..psep..")"))
+  end
 end
 
 
 function lume.trim(str, chars)
-  chars = chars or "%s"
+  if not chars then return str:match("^[%s]*(.-)[%s]*$") end
+  chars = patternescape(chars)
   return str:match("^[" .. chars .. "]*(.-)[" .. chars .. "]*$")
 end
 
@@ -300,11 +356,10 @@ end
 
 
 function lume.rgba(color)
-  local floor = math.floor
-  local a = floor((color / 2 ^ 24) % 256)
-  local r = floor((color / 2 ^ 16) % 256)
-  local g = floor((color / 2 ^ 08) % 256)
-  local b = floor((color) % 256)
+  local a = math_floor((color / 2 ^ 24) % 256)
+  local r = math_floor((color / 2 ^ 16) % 256)
+  local g = math_floor((color / 2 ^ 08) % 256)
+  local b = math_floor((color) % 256)
   return r, g, b, a
 end
 

test/test_lume.lua

@@ -82,6 +82,9 @@ end
 
 -- lume.random
 tests["lume.random"] = function()
+  testeq( type(lume.random()),      "number" )
+  testeq( type(lume.random(1)),     "number" )
+  testeq( type(lume.random(1, 2)),  "number" )
 end
 
 -- lume.randomchoice
@@ -94,6 +97,15 @@ tests["lume.randomchoice"] = function()
   testeq( lume.randomchoice({true}),    true )
 end
 
+-- lume.weightedchoice
+tests["lume.weightedchoice"] = function()
+  testeq( lume.weightedchoice( {a = 1} ),         "a" )
+  testeq( lume.weightedchoice( {a = 0, b = 1} ),  "b" )
+  tester.test.error( lume.weightedchoice, {}                  )
+  tester.test.error( lume.weightedchoice, { a = 0, b = 0 }    )
+  tester.test.error( lume.weightedchoice, { a = 1, b = -1 }   )
+end
+
 -- lume.shuffle
 tests["lume.shuffle"] = function()
   local t = {1, 2, 3, 4, 5}
@@ -155,7 +167,7 @@ tests["lume.reduce"] = function()
   testeq( lume.reduce({"cat", "dog"}, concat, "pig"), "pigcatdog" )
   testeq( lume.reduce({"me", "ow"}, concat),          "meow"      )
   testeq( lume.reduce({1, 2, 3, 4}, add),             10          )
-  testeq( lume.reduce({1, 2, 3, 4}, add),             10          )
+  testeq( lume.reduce({1, 2, 3, 4}, add, 5),          15          )
   testeq( lume.reduce({1}, add),                      1           )
   testeq( lume.reduce({}, concat, "potato"),          "potato"    )
 end
@@ -194,13 +206,18 @@ end
 
 -- lume.slice
 tests["lume.slice"] = function()
-  testeq( lume.slice({"a", "b", "c", "d", "e"}, 2, 4),  {"b", "c", "d"} )
-  testeq( lume.slice({"a", "b", "c", "d", "e"}, 2, -2), {"b", "c", "d"} )
-  testeq( lume.slice({"a", "b", "c", "d", "e"}, 3, -1), {"c", "d", "e"} )
-  testeq( lume.slice({"a", "b", "c", "d", "e"}, 3),     {"c", "d", "e"} )
-  testeq( lume.slice({"a", "b", "c", "d", "e"}, 4),     {"d", "e"}      )
-  testeq( lume.slice({"a", "b", "c", "d", "e"}, 1, 1),  {"a"}           )
-  testeq( lume.slice({"a", "b", "c", "d", "e"}, 2, 1),  {}              )
+  testeq( lume.slice({"a", "b", "c", "d", "e"}, 2, 4),    {"b", "c", "d"} )
+  testeq( lume.slice({"a", "b", "c", "d", "e"}, 2, -2),   {"b", "c", "d"} )
+  testeq( lume.slice({"a", "b", "c", "d", "e"}, 3, -1),   {"c", "d", "e"} )
+  testeq( lume.slice({"a", "b", "c", "d", "e"}, 3),       {"c", "d", "e"} )
+  testeq( lume.slice({"a", "b", "c", "d", "e"}, 4),       {"d", "e"}      )
+  testeq( lume.slice({"a", "b", "c", "d", "e"}, 1, 1),    {"a"}           )
+  testeq( lume.slice({"a", "b", "c", "d", "e"}, 2, 1),    {}              )
+  testeq( lume.slice({"a", "b", "c", "d", "e"}, -3, -2),  {"c", "d"}      )
+  testeq( lume.slice({"a", "b", "c", "d", "e"}, -3, 1),   {}              )
+  testeq( lume.slice({"a", "b", "c", "d", "e"}, 0, 1),    {"a"}           )
+  testeq( lume.slice({"a", "b", "c", "d", "e"}, 0, 0),    {}              )
+  testeq( lume.slice({"a", "b", "c", "d", "e"}, -3),      {"c", "d", "e"} )
 end
 
 -- lume.invert
@@ -239,6 +256,21 @@ tests["lume.time"] = function()
   testeq( {a, b, c},  {50, 60, 70}  )
 end
 
+-- lume.lambda
+tests["lume.lambda"] = function()
+  testeq( lume.lambda "x->x*x"(10),                 100         )
+  testeq( lume.lambda "x->x*x"(20),                 400         )
+  testeq( lume.lambda "x,y -> 2*x+y"(10,5),         25          )
+  testeq( lume.lambda "a, b -> a / b"(1, 2),        .5          )
+  testeq( lume.lambda "a -> 'hi->' .. a"("doggy"),  "hi->doggy" )
+  testeq( lume.lambda "A1,_->A1.._"("te","st"),     "test"      )
+  testeq( lume.lambda "->"(1,2,3),                  nil         )
+  tester.test.error( lume.lambda, "abc"         )
+  tester.test.error( lume.lambda, ""            )
+  tester.test.error( lume.lambda, "a,b->a->b"   )
+  tester.test.error( lume.lambda, "(a),b->a+b"  )
+end
+
 -- lume.serialize / lume.deserialize
 tests["lume.serialize, lume.deserialize"] = function()
   local t = { 1, 2, 3, 4, true, false, "cat", "dog", {1, 2, 3} }
@@ -248,9 +280,15 @@ end
 
 -- lume.split
 tests["lume.split"] = function()
-  testeq( lume.split("cat   dog  pig"),     {"cat", "dog", "pig"} )
-  testeq( lume.split(",cat,dog,pig", ","),  {"cat", "dog", "pig"} )
-  testeq( lume.split(",cat,dog;pig", ",;"), {"cat", "dog", "pig"} )
+  testeq( lume.split("cat   dog  pig"),     {"cat", "dog", "pig"}     )
+  testeq( lume.split("cat,dog,pig", ","),   {"cat", "dog", "pig"}     )
+  testeq( lume.split("cat,dog;pig", ";"),   {"cat,dog", "pig"}        )
+  testeq( lume.split("cat,dog,,pig", ","),  {"cat", "dog", "", "pig"} )
+  testeq( lume.split(";;;cat;", ";"),       {"", "", "", "cat", ""}   )
+  testeq( lume.split("cat.dog", "."),       {"cat", "dog"}            )
+  testeq( lume.split("cat%dog", "%"),       {"cat", "dog"}            )
+  testeq( lume.split("1<>2<>3", "<>"),      {"1", "2", "3"}           )
+  tester.test.error( lume.split, "abc", "" )
 end
 
 -- lume.trim
@@ -258,6 +296,8 @@ tests["lume.trim"] = function()
   testeq( lume.trim("   hello world   "),       "hello world"   )
   testeq( lume.trim("-=-hello-world===", "-="), "hello-world"   )
   testeq( lume.trim("***hello world*-*", "*"),  "hello world*-" )
+  testeq( lume.trim("...hello world.", "."),    "hello world"   )
+  testeq( lume.trim("^.hello world]^", "^.]"),  "hello world"   )
 end
 
 -- lume.format

test/tester.lua

@@ -128,6 +128,18 @@ function tester.test.equal(result, expected)
 end
 
 
+function tester.test.error(fn, ...)
+  local passed = not pcall(fn, ...)
+  local info = debug.getinfo(2)
+  if passed then
+    dopass(info.short_src, info.currentline)
+  else
+    dofail(info.short_src, info.currentline)
+    printfailmsg("Expected an error to be raised")
+  end
+end
+
+
 function tester.dotests(t)
   local keys = {}
   for k in pairs(t) do table.insert(keys, k) end