LuaAPI/location set

From The Battle for Wesnoth Wiki
< LuaAPI
Revision as of 22:10, 7 December 2019 by Celtic Minstrel (talk | contribs) (location_set.insert: Correct note on the behavior of inserting nil)

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

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

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

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

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

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