LuaAPI/functional

The functional module provides higher-order functions, primarily modelled off equivalent functions in the Wesnoth Formula Language. It can be loaded via local functional = wesnoth.require "functional".

Functions

functional.filter

• functional.filter(array, predicate) → filtered array

Returns a new table containing only the values for which the predicate returns true. Though it returns a new table, the values themselves are not copied. It only operates on the array portion of the table. The predicate takes one argument, the value to be tested.

functional.filter_map

• functional.filter_map(table, predicate) → filtered table

Returns a new table containing only the key-value pairs for which the predicate returns true. Though it returns a new table, the values themselves are not copied. It operates on all keys, both numeric and non-numeric. The predicate takes two arguments, the key and value to be tested.

functional.find

• functional.find(array, predicate) → value

Returns the first value in the table for which the predicate returns true. It only operates on the array portion of the table. The predicate takes one argument, the value to be tested.

functional.find_map

• functional.find_map(table, predicate) → key, value

Returns the first key-value pair in the table for which the predicate returns true. It operates on all keys, both numeric and non-numeric. The predicate takes two arguments, the key and value to be tested.

functional.choose

• functional.choose(array, score_function) → best value, score, index

Returns the value for which the score function returns the highest value. If multiple entries return the same maximal value, the first entry is returned. It also returns the score and index of that value. It operates on the array portion of the table. The score function takes one argument, the value to be tested.

-- Find my unit with the highest health
local strongest_unit = functional.choose(wesnoth.units.find{side = 1}, function(u) return u.hitpoints end)

functional.choose_map

• functional.choose_map(table, score_function) → best pair, score

Returns the key-value pair for which the score function returns the highest value. If multiple entries return the same maximal value, the first entry is returned. It also returns the score and index of that value. It operates on all keys, both numeric and non-numeric. The score function takes two arguments, the key and value to be tested. The best pair is returned as a table with keys key and value.

functional.map

• functional.map(table, function) → mapped table

Returns a new table with the return value of function for each key-value pair. The function takes the value first, then the key; for the array portion of the table, only the value is passed. (Version 1.17.? and later only) The array portion of the table is no longer treated specially. Use functional.map_array instead if you want the original behaviour.

functional.map_array

(Version 1.17.? and later only)

• functional.map_array(array, function) → mapped array

Returns a new array with the return value of function for each element, preserving order.

functional.reduce

• functional.reduce(array, operator, [identity]) → result

Combines all elements of the array to produce a single result. If omitted, the identity is 0. The function will be called with the current cumulative result (starting with the identity) as the first argument, and the current element of the array as the second argument. It only operates on the array portion of the table.

local values = {1, 3, 5, 9}
local sum = functional.reduce(values, function(a,b) return a + b end)
local prod = functional.reduce(values, function(a,b) return a * b end, 1)
local cat = functional.reduce(values, function(a,b) return a .. b end, '')
print(sum, prod, cat) -- outputs 18, 135, '1359'

functional.take_while

• functional.take_while(array, predicate) → truncated table

Returns a new array containing all elements up to but excluding the first element for which the predicate returns false. It only operates on the array portion of the table.

functional.zip

• functional.zip(array of arrays) → array of arrays

Given an array of arrays, returns a new array of arrays where the first array has the first element of the original arrays, the second array has all the second elements, and so forth. Applying zip twice recovers the original array.

local test = {{1, 2, 3}, {'hello', 'happy', 'world'}, {2.5, 3.97, 1.2}}
ilua._pretty_print(functional.zip(test))
-- Output:
-- {{1,'hello',2.5},{2,'happy',3.97},{3,'world',1.2}}