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_raw

(Version 1.17.? and later only)

• location_set.of_raw(data) → 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) → 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_map

(Version 1.17.? and later only)

• location_set.of_map(table) → 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:

local ls = location_set.of_map{ [{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.of_shroud_data

• location_set.of_shroud_data(shroud data string) → 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() → 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() → array of pairs

Like to_pairs, but the locations are sorted lexicographically.

location_set.to_triples

• location_set:'to_triples() → array of triples

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

location_set.to_map

(Version 1.17.? and later only)

• location_set:to_map() → 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() → 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() → 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) → 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 in the first form will not erase the value – instead it will set it to true. 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.clear

(Version 1.17.? and later only)

• location_set:clear()

Removes all locations from the set, leaving it empty.

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)
• location_set:iter() → iterator ⇒ 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:

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

location_set.stable_iter

• location_set:stable_iter(function)
• location_set:stable_iter() → iterator ⇒ 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)
• (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

(Version 1.15.3 and later only)

• location_set::symm(other location_set)
• location_set ~ other location_set → 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

(Version 1.17.? and later only)

• location_set:invert(width, height, border_size) → new set
• location_set:invert(map) → new set
• ♟ ~ location_set → 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() → x, y

Selects a random location from the set and returns it.