Editing Module:Includes/doc

{{documentation subpage}}
<!-- Add categories where indicated at the bottom of this page and interwikis at Wikidata -->

Lua equivalent to the javascript [https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/includes Array.prototype.includes()] function, except fromIndex is 1-indexed instead of zero-indexed. Determines whether an array includes a certain value and returns <code>true</code> or <code>false</code>.

== Syntax ==

<syntaxhighlight lang="lua">includes(array, searchElement)
includes(array, searchElement, fromIndex)</syntaxhighlight>

=== array ===
<code>array</code> is the array to search. If <syntaxhighlight lang="lua" inline>type(array) ~= 'table'</syntaxhighlight> the module will return <code>false</code>.

=== value ===
<code>value</code> is the value to be tested. If <code>value</code> is present in the array, the module will return <code>true</code>. If <code>value</code> is missing the module will return <code>false</code>.

=== fromIndex ===
<code>fromIndex</code> is the optional 1-based index at which to start searching. If <code>fromIndex</code> 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 <syntaxhighlight lang="lua" inline>pairs()</syntaxhighlight>).

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

In the following examples, <code>#array</code> represents the length of the integer-keyed portion of the array.

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

== Usage ==

<syntaxhighlight lang="lua">
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
</syntaxhighlight>


<includeonly>{{Sandbox other||
<!-- Categories below this line; interwikis at Wikidata -->
[[Category:Lua metamodules]]
}}</includeonly>