Module:Includes

Module documentation[view] [edit] [history] [purge]

Lua equivalent to the javascript Array.prototype.includes() function, except fromIndex is 1-indexed instead of zero-indexed. Determines whether an array includes a certain value and returns true or false.

Syntax

includes(array, searchElement)
includes(array, searchElement, fromIndex)

array

array is the array to search. If type(array) ~= 'table' the module will return false.

value

value is the value to be tested. If value is present in the array, the module will return true. If value is missing the module will return false.

fromIndex

fromIndex is the optional 1-based index at which to start searching. If fromIndex is not present, all values in the array will be searched and the array will be treated as a table/associative array (it will be iterated over using pairs()).

If fromIndex is present and an integer, the array is assumed to be a conventional array/sequence/list (indexed with consecutive integer keys starting at 1, and interated over using ipairs()). Only the values whose index is fromIndex or higher will be searched.

In the following examples, #array represents the length of the integer-keyed portion of the array.

• If fromIndex < 0 it will count back from the end of the array, e.g. a value of -1 will only search the last integer-keyed element in the array. If fromIndex <= (-1 * #array), the entire integer-keyed portion of the array will be searched.
• If fromIndex = 0 it will be treated as a 1 and the entire integer-keyed portion of the array will be searched.
• If fromIndex > #array, the array is not searched and false is returned.

Usage

local includes = require('Module:Includes')

-- These will return true
includes({"a", "b", "c", "d"}, "b")
includes({"a", "b", "c", "d"}, "b", 0)
includes({"a", "b", "c", "d"}, "b", 1)
includes({"a", "b", "c", "d"}, "b", 2)
includes({"a", "b", "c", "d"}, "b", -3)
includes({"a", "b", "c", "d"}, "b", -5)
includes({[1] = "a",[100] = "b",[101] = "c"}, "b")
includes({[1] = "a",[2] = "b",[3] = "c"}, "b", 0)
includes({first = "a", second = "b", third = "c"}, "b")

--these will return false
includes("b","b") -- array is not a table
includes({"a", "b", "c", "d"}) -- value missing
includes({"a", "b", "c", "d"}, "e") -- "e" is not in array
includes({"a", "b", "c", "d"}, "b", 3) -- "b" is before position 3
includes({"a", "b", "c", "d"}, "b", 5) -- 5 is larger than #array
includes({"a", "b", "c", "d"}, "b", -2) -- "b" is not in the last two positions
includes({[1] = "a", [100] = "b", [101] = "c"}, "b", 0) -- key 100 is non-consecutive
includes({first = "a", second = "b", third = "c"}, "b", 0) -- key "second" is not an integer

The above documentation is transcluded from Module:Includes/doc. (edit | history)
Editors can experiment in this module's sandbox (create | mirror) and testcases (edit | run) pages.
Subpages of this module.

-- Equivalent to JavaScript array.includes(searchElement) or
-- array.includes(searchElement, fromIndex), except fromIndex is 1 indexed
return function (array, searchElement, fromIndex)
	fromIndex = tonumber(fromIndex)
	if (fromIndex and #array > 0) then
		if (fromIndex < 0) then
			fromIndex = #array + fromIndex + 1
		end
		if fromIndex < 1 then fromIndex = 1 end
		local iter, a = ipairs(array)
		for _, v in iter, a, (fromIndex - 1) do
			if v == searchElement then
				return true
			end
		end
	else
		for _, v in pairs(array) do
			if v == searchElement then
				return true
			end
		end
	end
	return false
end