开源软件名称（OpenSource Name）：

开源软件地址(OpenSource Url)：

开源编程语言(OpenSource Language)：

开源软件介绍(OpenSource Introduction)：

Lume

A collection of functions for Lua, geared towards game development.

Installation

The lume.lua file should be dropped into an existing project and required by it:

lume = require "lume"

Function Reference

lume.clamp(x, min, max)

Returns the number x clamped between the numbers min and max

lume.round(x [, increment])

Rounds x to the nearest integer; rounds away from zero if we're midway between two integers. If increment is set then the number is rounded to the nearest increment.

lume.round(2.3) -- Returns 2
lume.round(123.4567, .1) -- Returns 123.5

lume.sign(x)

Returns 1 if x is 0 or above, returns -1 when x is negative.

lume.lerp(a, b, amount)

Returns the linearly interpolated number between a and b, amount should be in the range of 0 - 1; if amount is outside of this range it is clamped.

lume.lerp(100, 200, .5) -- Returns 150

lume.smooth(a, b, amount)

Similar to lume.lerp() but uses cubic interpolation instead of linear interpolation.

lume.pingpong(x)

Ping-pongs the number x between 0 and 1.

lume.distance(x1, y1, x2, y2 [, squared])

Returns the distance between the two points. If squared is true then the squared distance is returned -- this is faster to calculate and can still be used when comparing distances.

lume.angle(x1, y1, x2, y2)

Returns the angle between the two points.

lume.vector(angle, magnitude)

Given an angle and magnitude, returns a vector.

local x, y = lume.vector(0, 10) -- Returns 10, 0

lume.random([a [, b]])

Returns a random number between a and b. If only a is supplied a number between 0 and a is returned. If no arguments are supplied a random number between 0 and 1 is returned.

lume.randomchoice(t)

Returns a random value from array t. If the array is empty an error is 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.

lume.weightedchoice({ ["cat"] = 10, ["dog"] = 5, ["frog"] = 0 })
-- Returns either "cat" or "dog" with "cat" being twice as likely to be chosen.

lume.isarray(x)

Returns true if x is an array -- the value is assumed to be an array if it is a table which contains a value at the index 1. This function is used internally and can be overridden if you wish to use a different method to detect arrays.

lume.push(t, ...)

Pushes all the given values to the end of the table t and returns the pushed values. Nil values are ignored.

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.

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.

local t = { 1, 2, 3 }
lume.clear(t) -- `t` becomes {}

lume.extend(t, ...)

Copies all the fields from the source tables to the table t and returns t. If a key exists in multiple tables the right-most table's value is used.

local t = { a = 1, b = 2 }
lume.extend(t, { b = 4, c = 6 }) -- `t` becomes { a = 1, b = 4, c = 6 }

lume.shuffle(t)

Returns a shuffled copy of the array t.

lume.sort(t [, comp])

Returns a copy of the array t with all its items sorted. If comp is a function it will be used to compare the items when sorting. If comp is a string it will be used as the key to sort the items by.

lume.sort({ 1, 4, 3, 2, 5 }) -- Returns { 1, 2, 3, 4, 5 }
lume.sort({ {z=2}, {z=3}, {z=1} }, "z") -- Returns { {z=1}, {z=2}, {z=3} }
lume.sort({ 1, 3, 2 }, function(a, b) return a > b end) -- Returns { 3, 2, 1 }

lume.array(...)

Iterates the supplied iterator and returns an array filled with the values.

lume.array(string.gmatch("Hello world", "%a+")) -- Returns {"Hello", "world"}

lume.each(t, fn, ...)

Iterates the table t and calls the function fn on each value followed by the supplied additional arguments; if fn is a string the method of that name is called for each value. The function returns t unmodified.

lume.each({1, 2, 3}, print) -- Prints "1", "2", "3" on separate lines
lume.each({a, b, c}, "move", 10, 20) -- Does x:move(10, 20) on each value

lume.map(t, fn)

Applies the function fn to each value in table t and returns a new table with the resulting values.

lume.map({1, 2, 3}, function(x) return x * 2 end) -- Returns {2, 4, 6}

lume.all(t [, fn])

Returns true if all the values in t table are true. If a fn function is supplied it is called on each value, true is returned if all of the calls to fn return true.

lume.all({1, 2, 1}, function(x) return x == 1 end) -- Returns false

lume.any(t [, fn])

Returns true if any of the values in t table are true. If a fn function is supplied it is called on each value, true is returned if any of the calls to fn return true.

lume.any({1, 2, 1}, function(x) return x == 1 end) -- Returns true

lume.reduce(t, fn [, first])

Applies fn on two arguments cumulative to the items of the array t, from left to right, so as to reduce the array to a single value. If a first value is specified the accumulator is initialised to this, otherwise the first value in the array is used. If the array is empty and no first value is specified an error is raised.

lume.reduce({1, 2, 3}, function(a, b) return a + b end) -- Returns 6

lume.unique(t)

Returns a copy of the t array with all the duplicate values removed.

lume.unique({2, 1, 2, "cat", "cat"}) -- Returns {1, 2, "cat"}

lume.filter(t, fn [, retainkeys])

Calls fn on each value of t table. Returns a new table with only the values where fn returned true. If retainkeys is true the table is not treated as 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.

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.

lume.merge({a=1, b=2, c=3}, {c=8, d=9}) -- Returns {a=1, b=2, c=8, d=9}

lume.concat(...)

Returns a new array consisting of all the given arrays concatenated into one.

lume.concat({1, 2}, {3, 4}, {5, 6}) -- Returns {1, 2, 3, 4, 5, 6}

lume.find(t, value)

Returns the index/key of value in t. Returns nil if that value does not exist in the table.

lume.find({"a", "b", "c"}, "b") -- Returns 2

lume.match(t, fn)

Returns the value and key of the value in table t which returns true when fn is called on it. Returns nil if no such value exists.

lume.match({1, 5, 8, 7}, function(x) return x % 2 == 0 end) -- Returns 8, 3

lume.count(t [, fn])

Counts the number of values in the table t. If a fn function is supplied it is called on each value, the number of times it returns true is counted.

lume.count({a = 2, b = 3, c = 4, d = 5}) -- Returns 4
lume.count({1, 2, 4, 6}, function(x) return x % 2 == 0 end) -- Returns 3

lume.slice(t [, i [, j]])

Mimics the behaviour of Lua's string.sub, but operates on an array rather than a string. Creates and returns a new array of the given slice.

lume.slice({"a", "b", "c", "d", "e"}, 2, 4) -- Returns {"b", "c", "d"}

lume.first(t [, n])

Returns the first element of an array or nil if the array is empty. If n is specificed an array of the first n elements is returned.

lume.first({"a", "b", "c"}) -- Returns "a"

lume.last(t [, n])

Returns the last element of an array or nil if the array is empty. If n is specificed an array of the last n elements is returned.

lume.last({"a", "b", "c"}) -- Returns "c"

lume.invert(t)

Returns a copy of the table where the keys have become the values and the values the keys.

lume.invert({a = "x", b = "y"}) -- returns {x = "a", y = "b"}

lume.pick(t, ...)

Returns a copy of the table filtered to only contain values for the given keys.

lume.pick({ a = 1, b = 2, c = 3 }, "a", "c") -- Returns { a = 1, c = 3 }

lume.keys(t)

Returns an array containing each key of the table.

lume.clone(t)

Returns a shallow copy of the table t.

lume.fn(fn, ...)

Creates a wrapper function around function fn, automatically inserting the arguments into fn which will persist every time the wrapper is called. Any arguments which are passed to the returned function will be inserted after the already existing arguments passed to fn.

local f = lume.fn(print, "Hello")
f("world") -- Prints "Hello world"

lume.once(fn, ...)

Returns a wrapper function to fn which takes the supplied arguments. The wrapper function will call fn on the first call and do nothing on any subsequent calls.

local f = lume.once(print, "Hello")
f() -- Prints "Hello"
f() -- Does nothing

lume.memoize(fn)

Returns a wrapper function to fn where the results for any given set of arguments are cached. lume.memoize() is useful when used on functions with slow-running computations.

fib = lume.memoize(function(n) return n < 2 and n or fib(n-1) + fib(n-2) end)

lume.combine(...)

Creates a wrapper function which calls each supplied argument in the order they were passed to lume.combine(); nil arguments are ignored. The wrapper function passes its own arguments to each of its wrapped functions when it is called.

local f = lume.combine(function(a, b) print(a + b) end,
                       function(a, b) print(a * b) end)
f(3, 4) -- Prints "7" then "12" on a new line

lume.call(fn, ...)

Calls the given function with the provided arguments and returns its values. If fn is nil then no action is performed and the function returns nil.

lume.call(print, "Hello world") -- Prints "Hello world"

lume.time(fn, ...)

Inserts the arguments into function fn and calls it. Returns the time in 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.

local f =