LuaAPI/functional - Revision history

Laela at 18:04, 18 April 2024

2024-04-18T18:04:07Z

Celtic Minstrel: /* functional.map_array */ Missed dev-tag

2022-06-28T04:04:40Z

‎functional.map_array: Missed dev-tag

Celtic Minstrel: /* functional.map */ Update and add new map_array function

2022-06-28T04:04:18Z

‎functional.map: Update and add new map_array function

Celtic Minstrel: Move comma out of optional brackets

2021-07-04T22:18:29Z

Move comma out of optional brackets

Celtic Minstrel: Document zip

2021-07-02T23:06:43Z

Document zip

Celtic Minstrel: Categorize

2021-06-30T02:33:11Z

Categorize

Celtic Minstrel: Document functional module

2019-12-06T13:44:14Z

Document functional module

New page

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

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

<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'') → ''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.

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

<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'') → ''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.

← Older revision		Revision as of 18:04, 18 April 2024
Line 1:		Line 1:
	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>.		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 ===

← Older revision		Revision as of 04:04, 28 June 2022
Line 49:		Line 49:

	=== functional.map_array ===		=== functional.map_array ===
		+
		+	{{DevFeature1.17\|?}}

	* '''functional.map_array'''(''array'', ''function'') → ''mapped array''		* '''functional.map_array'''(''array'', ''function'') → ''mapped array''

@@ Line 46: / Line 46: @@
 * '''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.
+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.reduce ===

@@ Line 50: / Line 50: @@
 === functional.reduce ===
-* '''functional.reduce'''(''array'', ''operator'' [, ''identity'']) &rarr; ''result''
+* '''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.

← Older revision		Revision as of 23:06, 2 July 2021
Line 67:		Line 67:

	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.		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.
		+
		+	<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]]		[[Category:Lua Reference]]

← Older revision		Revision as of 02:33, 30 June 2021
Line 67:		Line 67:

	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.		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.
		+
		+	[[Category:Lua Reference]]