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

• location_set:random() → x, y

Selects a random location from the set and returns it.