LuaAPI/location set

The location_set 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 local location_set = wesnoth.require "location_set".

location_set.create

location_set.create() → empty set

Creates an empty location set.

location_set.of_pairs(table) → new set
location_set:of_pairs(table)

Converts a table of pairs (as { {1,2}, {7,8} }) 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) → 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:

local ls = location_set.of_triples{ {1,2,'best'}, [7,8,'next-best'} }
print(ls) -- outputs {(1,2) = best; (7,8) = next-best}

location_set.of_wml_var

location_set.of_wml_var(name) → 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.to_pairs

location_set:to_pairs()

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

location_set.to_triples

location_set:to_triples()

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

location_set.to_wml_var

location_set:to_wml_var(name)

Stores a location set into a WML variable.

location_set.clone

location_set:clone()

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) → value
(Version 1.15.3 and later only) location_set(x, y) → value
(Version 1.15.3 and later only) location_set[location] → value

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

location_set.insert

location_set:insert(x, y [, value])
(Version 1.15.3 and later only) location_set[location] = value

Sets the value associated with a given location. If the value is not specified, true is used. Specifying nil will erase the value. In the second form, the location must be specified either as a pair {3, 4} or as a coordinate table {x = 3, y = 4}

location_set.remove

location_set:remove(x, y)
(Version 1.15.3 and later only) location_set[location] = nil

Deletes a location from the location set. In the second form, the location must be specified either as a pair {3, 4} or as a coordinate table {x = 3, y = 4}

location_set.size

location_set:size() → number of locations

Returns the number of locations in the set.

location_set.empty

location_set:empty() → true or false

Tests if there are any locations in the set.

location_set.iter

location_set:iter([function])

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:

for x, y, value in ls:iter() do
    -- do stuff here
end

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)
(Version 1.15.3 and later only) location_set | other location_set → 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)
(Version 1.15.3 and later only) location_set & other location_set → 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

(Version 1.15.3 and later only)

location_set:diff(other location_set)
location_set - other location_set → 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