View source for LuaAPI/location set

The <tt>location_set</tt> module provides an interface for working with sets of locations, optionally with custom data associated to each location (so, it can be used either as a set or a map). It can be loaded via <syntaxhighlight lang=lua inline>local location_set = wesnoth.require "location_set"</syntaxhighlight>.

== Functions ==

=== location_set.create ===

* '''location_set.create'''() &rarr; ''empty set''

Creates an empty location set.

=== location_set.of_raw ===

{{DevFeature1.17|?}}

* '''location_set.of_raw'''(''data'') &rarr; ''converted set''

Some built-in Wesnoth functions return a table that's formatted like a location set but does not have the location set metatable applied. Such data can be converted into a proper location set with this function.

=== location_set.of_pairs ===

* '''location_set.of_pairs'''(''table'') &rarr; ''new set''
* ''location_set'':'''of_pairs'''(''table'')

Converts a table of pairs (as <syntaxhighlight lang=lua inline>{ {1,2}, {7,8} }</syntaxhighlight>) into a location set. The first form outputs a new location set with the specified locations, while the second form adds them into an existing location set.

=== location_set.of_triples ===

* '''location_set.of_triples'''(''table'') &rarr; ''new set''
* ''location_set'':'''of_triples'''(''table'')

Similar to '''of_pairs''', but additionally adds data if any of the subtables contains a third element. For example:

<syntaxhighlight lang=lua>
local ls = location_set.of_triples{ {1,2,'best'}, [7,8,'next-best'} }
print(ls) -- outputs {(1,2) = best; (7,8) = next-best}
</syntaxhighlight>

=== location_set.of_map ===

{{DevFeature1.17|?}}

* '''location_set.of_map'''(''table'') &rarr; ''new set''
* ''location_set'':'''of_map'''(''table'')

Similar to '''of_pairs''', but the input data is in the form of an associative table rather than an array of pairs. The keys may be any location-like type – that is, anything that has x and y keys. For example:

<syntaxhighlight lang=lua>
local ls = location_set.of_map{ [{1,2}] = 'best', [{7,8}] = 'next-best' }
print(ls) -- outputs {(1,2) = best; (7,8) = next-best}
</syntaxhighlight>

=== location_set.of_wml_var ===

* '''location_set.of_wml_var'''(''name'') &rarr; ''new set''
* ''location_set'':'''of_wml_var'''(''name'')

Converts a WML variable to a location set. The variable should be an array where each element has x and y keys. For example, the result of '''[store_location]'''.

=== location_set.of_shroud_data ===

* '''location_set.of_shroud_data'''(''shroud data string'') &rarr; ''new set''
* ''location_set'':'''of_shroud_data'''(''shroud data string'')

Converts a shroud data string to a location set. Each 1 in the string is converted to a location in the resulting set.

=== location_set.to_pairs ===

* ''location_set'':'''to_pairs'''() &rarr; ''array of pairs''

Converts a location set to pairs of the contained locations. The order of the locations is not guaranteed.

=== location_set.to_stable_pairs ===

* ''location_set'':'''to_stable_pairs'''() &rarr; ''array of pairs''

Like '''to_pairs''', but the locations are sorted lexicographically.

=== location_set.to_triples ===

* ''location_set'':'''to_triples'''() &rarr; ''array of triples'''

Converts a location set to triples of the contained locations and their associated data.

=== location_set.to_map ===

{{DevFeature1.17|?}}

* ''location_set'':'''to_map'''() &rarr; ''associative table''

Converts a location set to an associative table. Note that this does not mean you can simply look up data by location, as the indices are tables which have a unique address; it can be iterated over, however. This is mainly provided so that there is an inverse for '''of_map'''.

=== location_set.to_wml_var ===

* ''location_set'':'''to_wml_var'''(''name'')

Stores a location set into a WML variable.

=== location_set.to_shroud_data ===

* ''location_set'':'''to_shroud_data'''() &rarr; ''shroud data string''

Converts a location set to a shroud data string. The string will contain a 1 for each location in the set, and will be the minimum size needed to contain all the locations contained in the set.

=== location_set.clone ===

* ''location_set'':'''clone'''() &rarr; ''cloned set''

Creates a copy of a location set, including the values. Note that the values themselves are not copied, so if the value is a table, then both location sets still reference the same table.

=== location_set.get ===

* ''location_set'':'''get'''(''x'', ''y'') &rarr; ''value''
* {{DevFeature1.15|3}} ''location_set''(''x'', ''y'') &rarr; ''value''
* {{DevFeature1.15|3}} ''location_set''[''location''] &rarr; ''value''

Gets the value associated with a given location. In the third form, the location must be specified either as a pair <syntaxhighlight lang=lua inline>{3, 4}</syntaxhighlight> or as a coordinate table <syntaxhighlight lang=lua inline>{x = 3, y = 4}</syntaxhighlight>

=== location_set.insert ===

* ''location_set'':'''insert'''(''x'', ''y'', [''value''])
* {{DevFeature1.15|3}} ''location_set''[''location''] = ''value''

Sets the value associated with a given location. If the value is not specified, '''true''' is used. Specifying '''nil''' in the first form will ''not'' erase the value &ndash; instead it will set it to '''true'''. In the second form, the location must be specified either as a pair <syntaxhighlight lang=lua inline>{3, 4}</syntaxhighlight> or as a coordinate table <syntaxhighlight lang=lua inline>{x = 3, y = 4}</syntaxhighlight>

=== location_set.remove ===

* ''location_set'':'''remove'''(''x'', ''y'')
* {{DevFeature1.15|3}} ''location_set''[''location''] = '''nil'''

Deletes a location from the location set. In the second form, the location must be specified either as a pair <syntaxhighlight lang=lua inline>{3, 4}</syntaxhighlight> or as a coordinate table <syntaxhighlight lang=lua inline>{x = 3, y = 4}</syntaxhighlight>

=== location_set.clear ===

{{DevFeature1.17|?}}

* ''location_set'':'''clear'''()

Removes all locations from the set, leaving it empty.

=== location_set.size ===

* ''location_set'':'''size'''() &rarr; ''number of locations''

Returns the number of locations in the set.

=== location_set.empty ===

* ''location_set'':'''empty'''() &rarr; ''true or false''

Tests if there are any locations in the set.

=== location_set.iter ===

* ''location_set'':'''iter'''(''function'')
* ''location_set'':'''iter'''() &rarr; ''iterator'' &rArr; ''x'', ''y'', ''value''

Iterates over a location set. If a function is provided, it is called on every element of the set with three parameters - x, y, and value. Otherwise, this function returns an iterator that can be used in a for-loop as follows:

<syntaxhighlight lang=lua>
for x, y, value in ls:iter() do
    -- do stuff here
end
</syntaxhighlight>

=== location_set.stable_iter ===

* ''location_set'':'''stable_iter'''(''function'')
* ''location_set'':'''stable_iter'''() &rarr; ''iterator'' &rArr; ''x'', ''y'', ''value''

Like '''iter''', but yields the locations in lexicographical order.

=== location_set.filter ===

* ''location_set'':'''filter'''(''function'')

Removes locations from the set for which the given function returns false.

=== location_set.union ===

* ''location_set'':'''union'''(''other location_set'')
* {{DevFeature1.15|3}} ''location_set'' | ''other location_set'' &rarr; ''new location_set''

Combines two location sets into one. If the locations have associated values, the value in the right-hand set takes precedence. The functional form merges the right-hand set into the left-hand set, but the operator form creates a new location set with the merged locations. Note that if the value is a table, the table is not copied even with the operator form.

=== location_set.union_merge ===

* ''location_set'':'''union_merge'''(''other location_set'', ''function'')

Similar to '''union''', but instead of the right-hand values overriding the left-hand values, the provided function is called to determine the course of action. For every element of the right-hand set, it is called with four parameters: the x coordinate, the y coordinate, the old value from the left-hand set (which could be nil), and the new value from the right-hand set. The function's return value is used as the new value for that location.

=== location_set.inter ===

* ''location_set'':'''inter'''(''other location_set'')
* {{DevFeature1.15|3}} ''location_set'' & ''other location_set'' &rarr; ''new location_set''

Computes the intersection of two location sets. If the locations have associated values, the value in the left-hand set takes precedence. The functional form removes from the left-hand set any elements that are not in the right-hand set, but the operator form creates a new location set with only the locations present in both sets. Note that if the value is a table, the table is not copied even with the operator form.

=== location_set.inter_merge ===

* ''location_set'':'''inter_merge'''(''other location_set'', ''function'')

Similar to '''inter''', but instead of the left-hand values overriding the right-hand values, the provided function is called to determine the course of action. For every element in the left-hand set, it is called with four parameters: the x coordinate, the y coordinate, the old value from the left-hand set, and the new value from the right-hand set (which could be nil).

=== location_set.diff ===

{{DevFeature1.15|3}}

* ''location_set'':'''diff'''(''other location_set'')
* ''location_set'' - ''other location_set'' &rarr; ''new location_set''

Computes the difference of two location sets. The functional form removes all locations in the right-hand set from the left-hand set, while the operator form creates a new location set with only those locations that are in the left-hand set but not the right-hand set. In both cases, values are preserved. Note that if the value is a table, the table is not copied even with the operator form.

=== location_set.symm ===

{{DevFeature1.15|3}}

* ''location_set''::'''symm'''(''other location_set'')
* ''location_set'' ~ ''other location_set'' &rarr; ''new location_set''

Computes the symmetric difference of two location sets. The functional form removes from the left-hand set any locations that are present in both sets, while the operator form creates a new location set with only those locations that are not in both sets. In both cases, values are preserved. Note that if the value is a table, the table is not copied even with the operator form.

=== location_set.invert ===

{{DevFeature1.17|?}}

* ''location_set'':'''invert'''(''width'', ''height'', ''border_size'') &rarr; ''new set''
* ''location_set'':'''invert'''(''map'') &rarr; ''new set''
* {{LuaGameOnly}} ~ ''location_set'' &rarr; ''new set''

Computes the inverse of a location set, resulting in a new set that contains all locations that are ''not'' in the input set. This requires knowledge of the map size to function, so you can pass either the dimensions or the map itself as an argument. The operator form, only available in game contexts, automatically uses '''wesnoth.current.map''' as the map.

The output set does not have objects associated with any of the locations.

=== location_set.random ===

* ''location_set'':'''random'''() &rarr; ''x'', ''y''

Selects a random location from the set and returns it.

[[Category:Lua Reference]]