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 towards 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 in the 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.

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 the supplied array

lume.shuffle(t)

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

lume.array(...)

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

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

lume.map(t, fn)

Iterates the table t on all its values, replaces each value in place with the return of fn when called on that value.

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

lume.all(t, fn)

Iterates the table t and calls fn on each value. 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)

Iterates the table t and calls fn on each value. 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 t2 overwrites the value of any key which t already has when both table not treating the tables as arrays.

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)

Serialises 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 rather than 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 rather than the 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. Useful for 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.