View source for LuaAPI/functional

The <tt>functional</tt> module provides higher-order functions, primarily modelled off equivalent functions in the [[Wesnoth Formula Language]]. It can be loaded via <syntaxhighlight lang=lua inline>local functional = wesnoth.require "functional"</syntaxhighlight>.

== Functions ==

=== functional.filter ===

* '''functional.filter'''(''array'', ''predicate'') &rarr; ''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'') &rarr; ''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'') &rarr; ''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'') &rarr; ''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'') &rarr; ''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.

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

=== functional.choose_map ===

* '''functional.choose_map'''(''table'', ''score_function'') &rarr; ''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'') &rarr; ''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. {{DevFeature1.17|?}} The array portion of the table is no longer treated specially. Use [[#functional.map_array|functional.map_array]] instead if you want the original behaviour.

=== functional.map_array ===

{{DevFeature1.17|?}}

* '''functional.map_array'''(''array'', ''function'') &rarr; ''mapped array''

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

=== functional.reduce ===

* '''functional.reduce'''(''array'', ''operator'', [''identity'']) &rarr; ''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.

<syntaxhighlight lang=lua>
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'
</syntaxhighlight>

=== functional.take_while ===

* '''functional.take_while'''(''array'', ''predicate'') &rarr; ''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'') &rarr; ''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.

<syntaxhighlight lang=lua>
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}}
</syntaxhighlight>

[[Category:Lua Reference]]