lume/README.md

lume

A collection of handy 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 value x clamped between the values min and max

lume.round(x)

Rounds x to the nearest integer. Rounds away from zero if we're midway between two integers.

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 value between a and b, amount should be range of 0 - 1; if amount is outside of this range it is clamped.

lume.smooth(a, b, amount)

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

lume.pingpong(x, len)

Ping-pongs the value x between 0 and len.

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

Returns the distance between the two points.

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

Returns the angle between the two points.

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

Returns a random number between a and b. If only a is supplied an integer 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.

lume.shuffle(t)

Shuffles the values of array t in place, returns the array.

lume.array(...)

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

lume.array(pairs({a = 1, b = 2})) -- Returns {a, b}

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)

Calls fn on each value in t table and returns true if all the calls to fn return true.

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

lume.any(t, fn)

Calls fn on each value in t table and returns true if any of the calls to fn return true.

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

lume.set(t)

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

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

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 the first argument is not supplied the accumulator is initialised to 0.

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

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

Iterates the table t and calls fn on each value. Returns a new table with only the value which fn returned true. If isarray is true the table is treated as an array, isarray is false by default.

lume.filter({1, 2, 3, 4}, function(x) return x % 2 == 0 end, true) 
-- Returns {2, 4}

lume.merge(t, t2 [, isarray])

Merges all the values from the table t2 into t in place. If isarray is true the tables are treated as arrays, isarray is false by default. If isarray is false and t and t2 have a conflicting key, the value from t2 is used.

lume.merge({2, 3}, {4, 5}, true) -- Returns {2, 3, 4, 5}

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.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.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.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.

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

lume.serialize(x)

Serializes the argument x into a string which can be loaded again using lume.deserialize(). x can be a boolean, number, table or string. Circular references are not handled, all nested tables of x are serialised as unique tables.

lume.serialize({a = "test", b = {1, 2, 3}, false})
-- Returns "{[1]=false,["a"]="test",["b"]={[1]=1,[2]=2,[3]=3,},}"

lume.deserialize(str)

Deserializes a string created by lume.serialize() and returns the resulting value. This function should not be run on an untrusted string.

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.

lume.split("One two three") -- Returns {"One", "two", "three}

lume.trim(str [, chars])

Trims the whitespace from the start and end of the string str and returns the new string. If a chars value is set the characters in chars are trimmed instead of whitespace.

lume.trim("  Hello  ") -- Returns "Hello"

lume.format(str, vars)

Returns a formatted string. The values of keys in the table vars can be inserted into the string by using the form "{key}" in str

lume.format("Hello {a}, I hope {a} is {b}.", {a = "world", b = "well"})
-- Returns "Hello world, I hope world is well."

lume.dostring(str)

Executes the lua code inside str.

lume.dostring("print('Hello!')") -- Prints "Hello!"

lume.rgba(color)

Takes the 32bit integer color argument and returns 4 numbers, one for each channel, with a range of 0 - 255. Handy for using as the argument to LÖVE's setColor() function.

lume.rgba(0xFF304050) -- Returns 48, 64, 80, 255

License

This library is free software; you can redistribute it and/or modify it under the terms of the MIT license. See LICENSE for details.