Difference between revisions of "LuaAPI/location set"

From The Battle for Wesnoth Wiki
(Move comma out of optional brackets)
(location_set.of_raw: Document of_raw)
Line 6: Line 6:
  
 
Creates an empty location set.
 
Creates an empty location set.
 +
 +
=== location_set.of_raw ===
 +
 +
{{DevFeature1.17|?}}
 +
 +
* '''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 ===

Revision as of 03:20, 14 June 2022

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_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_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_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

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)
  • location_set:iter() → iteratorx, 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

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.