Modifications
Sauter à la navigation
Sauter à la recherche
aucun résumé de modification
{{Shared Template Warning|Module:TableTools}}
This module includes a number of functions for dealing with Lua tables. It is a meta-module, meant to be called from other Lua modules, and should not be called directly from #invoke.
== Module Quality ==
{| class=wikitable
| [[Module:TableTools]] || {{#invoke:TableTools/testcases|run|displayMode=short}}
|-
| [[Module:TableTools/sandbox]] || {{#invoke:TableTools/testcases|run||displayMode=short|module=TableTools/sandbox}}
|}
* See [[Module:TableTools/testcases|testcases]]
* [https://www.mediawiki.org/w/index.php?title=Special%3AComparePages&page1=Module%3ATNT&page2=Module%3ATableTools%2Fsandbox Diff] sandbox code
== Loading the module ==
To use any of the functions, first you must load the module.
<source lang="lua">
local TableTools = require('Module:TableTools')
</source>
== Functions ==
=== isPositiveInteger ===
<source lang="lua">
TableTools.isPositiveInteger(value)
</source>
Returns <code>true</code> if <code>''value''</code> is a positive integer, and <code>false</code> if not. Although it doesn't operate on tables, it is included here as it is useful for determining whether a given table key is in the array part or the hash part of a table.
=== isNan ===
<source lang="lua">
TableTools.isNan(value)
</source>
Returns <code>true</code> if <code>''value''</code> is a [[NaN]] value, and <code>false</code> if not. Although it doesn't operate on tables, it is included here as it is useful for determining whether a value can be a valid table key. (Lua will generate an error if a NaN value is used as a table key.)
=== shallowClone ===
<source lang="lua">
TableTools.shallowClone(t)
</source>
Returns a clone of a table. The value returned is a new table, but all subtables and functions are shared. Metamethods are respected, but the returned table will have no metatable of its own. If you want to make a new table with no shared subtables and with metatables transferred, you can use <code>[[mw:Extension:Scribunto/Lua reference manual#mw.clone|mw.clone]]</code> instead. If you want to make a new table with no shared subtables and without metatables transferred, use <code>[[#deepCopy|deepCopy]]</code> with the <code>noMetatable</code> option.
=== removeDuplicates ===
<source lang="lua">
TableTools.removeDuplicates(t)
</source>
Removes duplicate values from an array. This function is only designed to work with standard arrays: keys that are not positive integers are ignored, as are all values after the first <code>nil</code> value. (For arrays containing <code>nil</code> values, you can use <code>[[#compressSparseArray|compressSparseArray]]</code> first.) The function tries to preserve the order of the array: the earliest non-unique value is kept, and all subsequent duplicate values are removed. For example, for the table {{code|code={5, 4, 4, 3, 4, 2, 2, 1}|lang=lua}} <code>removeDuplicates</code> will return {{code|code={5, 4, 3, 2, 1}|lang=lua}}
=== numKeys ===
<source lang="lua">
TableTools.numKeys(t)
</source>
Takes a table <code>''t''</code> and returns an array containing the numbers of any positive integer keys that have non-nil values, sorted in numerical order. For example, for the table {{code|code={'foo', nil, 'bar', 'baz', a = 'b'}|lang=lua}}, <code>numKeys</code> will return {{code|code={1, 3, 4}|lang=lua}}.
=== affixNums ===
<source lang="lua">
TableTools.affixNums(t, prefix, suffix)
</source>
Takes a table <code>''t''</code> and returns an array containing the numbers of keys with the optional prefix <code>''prefix''</code> and the optional suffix <code>''suffix''</code>. For example, for the table {{code|code={a1 = 'foo', a3 = 'bar', a6 = 'baz'}|lang=lua}} and the prefix <code>'a'</code>, <code>affixNums</code> will return {{code|code={1, 3, 6}|lang=lua}}. All characters in <code>''prefix''</code> and <code>''suffix''</code> are interpreted literally.
=== numData ===
<source lang="lua">
TableTools.numData(t, compress)
</source>
Given a table with keys like <code>"foo1"</code>, <code>"bar1"</code>, <code>"foo2"</code>, and <code>"baz2"</code>, returns a table of subtables in the format {{code|code={ [1] = {foo = 'text', bar = 'text'}, [2] = {foo = 'text', baz = 'text'} }|lang=lua}}. Keys that don't end with an integer are stored in a subtable named <code>"other"</code>. The compress option compresses the table so that it can be iterated over with <code>ipairs</code>.
=== compressSparseArray ===
<source lang="lua">
TableTools.compressSparseArray(t)
</source>
Takes an array <code>''t''</code> with one or more nil values, and removes the nil values while preserving the order, so that the array can be safely traversed with <code>ipairs</code>. Any keys that are not positive integers are removed. For example, for the table {{code|code={1, nil, foo = 'bar', 3, 2}|lang=lua}}, <code>compressSparseArray</code> will return {{code|code={1, 3, 2}|lang=lua}}.
=== sparseIpairs ===
<source lang="lua">
TableTools.sparseIpairs(t)
</source>
This is an iterator function for traversing a sparse array <code>''t''</code>. It is similar to <code>[[mw:Extension:Scribunto/Lua reference manual#ipairs|ipairs]]</code>, but will continue to iterate until the highest numerical key, whereas <code>ipairs</code> may stop after the first <code>nil</code> value. Any keys that are not positive integers are ignored.
Usually <code>sparseIpairs</code> is used in a generic <code>for</code> loop.
<source lang="lua">
for i, v in TableTools.sparseIpairs(t) do
-- code block
end
</source>
Note that <code>sparseIpairs</code> uses the <code>[[mw:Extension:Scribunto/Lua reference manual#pairs|pairs]]</code> function in its implementation. Although some table keys appear to be ignored, all table keys are accessed when it is run.
=== size ===
<source lang="lua">
TableTools.size(t)
</source>
Finds the size of a key/value pair table. For example, for the table {{code|code={foo = 'foo', bar = 'bar'}|lang=lua}}, <code>size</code> will return <code>2</code>. The function will also work on arrays, but for arrays it is more efficient to use the <code>#</code> operator. Note that to find the table size, this function uses the <code>[[mw:Extension:Scribunto/Lua reference manual#pairs|pairs]]</code> function to iterate through all of the table keys.
=== keysToList ===
<source lang="lua">
TableTools.keysToList(t, keySort)
</source>
Returns a list of the keys in a table, sorted using either a default comparison function or a custom <code>keySort</code> function, which follows the same rules as the <code>comp</code> function supplied to [[mw:Extension:Scribunto/Lua reference manual#table.sort|<code>table.sort</code>]].
=== sortedPairs ===
<source lang="lua">
TableTools.sortedPairs(t, keySort)
</source>
Iterates through a table, with the keys sorted using the <code>keysToList</code> function. If there are only numerical keys, <code>sparseIpairs</code> is probably more efficient.
=== isArray ===
<source lang="lua">
TableTools.isArray(t)
</source>
Returns true if all keys in the table are consecutive integers starting at <code>1</code>.
=== listToSet ===
<source lang="lua">
TableTools.listToSet(arr)
</source>
Creates a set from the array part of the table <code>arr</code>. Indexing the set by any of the values in <code>arr</code> returns <code>true</code>.
<source lang="lua">
local set = TableTools.listToSet { "a", "b", "c" }
assert(set["a"] === true)
</source>
=== invert ===
<source lang="lua">
TableTools.invert(t)
</source>
Transposes the keys and values in an array. For example, <code>invert{ "a", "b", "c" }</code> yields <code>{ a = 1, b = 2, c = 3 }</code>.
=== deepCopy ===
<source lang="lua">
TableTools.deepCopy(orig, noMetatable, alreadySeen)
</source>
Creates a copy of the table <code>orig</code>. As with <code>mw.clone</code>, all values that are not functions are duplicated and the identity of tables is preserved. If <code>noMetatable</code> is <code>true</code>, then the metatable (if any) is not copied. Can copy tables loaded with <code>mw.loadData</code>.
Similar to <code>mw.clone</code>, but <code>mw.clone</code> cannot copy tables loaded with <code>mw.loadData</code> and does not allow metatables <em>not</em> to be copied.
=== sparseConcat ===
<source lang="lua">
TableTools.sparseConcat(t, sep)
</source>
Concatenates all values in the table that are indexed by a positive integer, in order.
=== length ===
<source lang="lua">
TableTools.length(t)
</source>
Returns the length of a table, or the first integer key <code>n</code> counting from <code>0</code> such that <code>t[n + 1]</code> is <code>nil</code>. It is similar to the operator <code>#</code>, but may return a different value when there are gaps in the array portion of the table. Intended to be used on data loaded with [[mw:Extension:Scribunto/Lua reference manual#mw.loadData|<code>mw.loadData</code>]] and on [[mw:Extension:Scribunto/Lua reference manual#frame.args|<code>frame.args</code>]]. Both use a metatable such that <code>#mw.loadData("module:...")</code> and <code>#frame.args</code> don't work correctly. For other tables, use <code>#</code>.
=== inArray ===
<source lang="lua">
TableTools.inArray(arr, valueToFind)
</source>
Returns <syntaxhighlight lang="lua" inline>true</syntaxhighlight> if <code>valueToFind</code> is a member of the array <code>arr</code>, and <syntaxhighlight lang="lua" inline>false</syntaxhighlight> otherwise.
<includeonly>{{Sandbox other||
[[Category:Lua metamodules|TableTools]]
}}</includeonly>
This module includes a number of functions for dealing with Lua tables. It is a meta-module, meant to be called from other Lua modules, and should not be called directly from #invoke.
== Module Quality ==
{| class=wikitable
| [[Module:TableTools]] || {{#invoke:TableTools/testcases|run|displayMode=short}}
|-
| [[Module:TableTools/sandbox]] || {{#invoke:TableTools/testcases|run||displayMode=short|module=TableTools/sandbox}}
|}
* See [[Module:TableTools/testcases|testcases]]
* [https://www.mediawiki.org/w/index.php?title=Special%3AComparePages&page1=Module%3ATNT&page2=Module%3ATableTools%2Fsandbox Diff] sandbox code
== Loading the module ==
To use any of the functions, first you must load the module.
<source lang="lua">
local TableTools = require('Module:TableTools')
</source>
== Functions ==
=== isPositiveInteger ===
<source lang="lua">
TableTools.isPositiveInteger(value)
</source>
Returns <code>true</code> if <code>''value''</code> is a positive integer, and <code>false</code> if not. Although it doesn't operate on tables, it is included here as it is useful for determining whether a given table key is in the array part or the hash part of a table.
=== isNan ===
<source lang="lua">
TableTools.isNan(value)
</source>
Returns <code>true</code> if <code>''value''</code> is a [[NaN]] value, and <code>false</code> if not. Although it doesn't operate on tables, it is included here as it is useful for determining whether a value can be a valid table key. (Lua will generate an error if a NaN value is used as a table key.)
=== shallowClone ===
<source lang="lua">
TableTools.shallowClone(t)
</source>
Returns a clone of a table. The value returned is a new table, but all subtables and functions are shared. Metamethods are respected, but the returned table will have no metatable of its own. If you want to make a new table with no shared subtables and with metatables transferred, you can use <code>[[mw:Extension:Scribunto/Lua reference manual#mw.clone|mw.clone]]</code> instead. If you want to make a new table with no shared subtables and without metatables transferred, use <code>[[#deepCopy|deepCopy]]</code> with the <code>noMetatable</code> option.
=== removeDuplicates ===
<source lang="lua">
TableTools.removeDuplicates(t)
</source>
Removes duplicate values from an array. This function is only designed to work with standard arrays: keys that are not positive integers are ignored, as are all values after the first <code>nil</code> value. (For arrays containing <code>nil</code> values, you can use <code>[[#compressSparseArray|compressSparseArray]]</code> first.) The function tries to preserve the order of the array: the earliest non-unique value is kept, and all subsequent duplicate values are removed. For example, for the table {{code|code={5, 4, 4, 3, 4, 2, 2, 1}|lang=lua}} <code>removeDuplicates</code> will return {{code|code={5, 4, 3, 2, 1}|lang=lua}}
=== numKeys ===
<source lang="lua">
TableTools.numKeys(t)
</source>
Takes a table <code>''t''</code> and returns an array containing the numbers of any positive integer keys that have non-nil values, sorted in numerical order. For example, for the table {{code|code={'foo', nil, 'bar', 'baz', a = 'b'}|lang=lua}}, <code>numKeys</code> will return {{code|code={1, 3, 4}|lang=lua}}.
=== affixNums ===
<source lang="lua">
TableTools.affixNums(t, prefix, suffix)
</source>
Takes a table <code>''t''</code> and returns an array containing the numbers of keys with the optional prefix <code>''prefix''</code> and the optional suffix <code>''suffix''</code>. For example, for the table {{code|code={a1 = 'foo', a3 = 'bar', a6 = 'baz'}|lang=lua}} and the prefix <code>'a'</code>, <code>affixNums</code> will return {{code|code={1, 3, 6}|lang=lua}}. All characters in <code>''prefix''</code> and <code>''suffix''</code> are interpreted literally.
=== numData ===
<source lang="lua">
TableTools.numData(t, compress)
</source>
Given a table with keys like <code>"foo1"</code>, <code>"bar1"</code>, <code>"foo2"</code>, and <code>"baz2"</code>, returns a table of subtables in the format {{code|code={ [1] = {foo = 'text', bar = 'text'}, [2] = {foo = 'text', baz = 'text'} }|lang=lua}}. Keys that don't end with an integer are stored in a subtable named <code>"other"</code>. The compress option compresses the table so that it can be iterated over with <code>ipairs</code>.
=== compressSparseArray ===
<source lang="lua">
TableTools.compressSparseArray(t)
</source>
Takes an array <code>''t''</code> with one or more nil values, and removes the nil values while preserving the order, so that the array can be safely traversed with <code>ipairs</code>. Any keys that are not positive integers are removed. For example, for the table {{code|code={1, nil, foo = 'bar', 3, 2}|lang=lua}}, <code>compressSparseArray</code> will return {{code|code={1, 3, 2}|lang=lua}}.
=== sparseIpairs ===
<source lang="lua">
TableTools.sparseIpairs(t)
</source>
This is an iterator function for traversing a sparse array <code>''t''</code>. It is similar to <code>[[mw:Extension:Scribunto/Lua reference manual#ipairs|ipairs]]</code>, but will continue to iterate until the highest numerical key, whereas <code>ipairs</code> may stop after the first <code>nil</code> value. Any keys that are not positive integers are ignored.
Usually <code>sparseIpairs</code> is used in a generic <code>for</code> loop.
<source lang="lua">
for i, v in TableTools.sparseIpairs(t) do
-- code block
end
</source>
Note that <code>sparseIpairs</code> uses the <code>[[mw:Extension:Scribunto/Lua reference manual#pairs|pairs]]</code> function in its implementation. Although some table keys appear to be ignored, all table keys are accessed when it is run.
=== size ===
<source lang="lua">
TableTools.size(t)
</source>
Finds the size of a key/value pair table. For example, for the table {{code|code={foo = 'foo', bar = 'bar'}|lang=lua}}, <code>size</code> will return <code>2</code>. The function will also work on arrays, but for arrays it is more efficient to use the <code>#</code> operator. Note that to find the table size, this function uses the <code>[[mw:Extension:Scribunto/Lua reference manual#pairs|pairs]]</code> function to iterate through all of the table keys.
=== keysToList ===
<source lang="lua">
TableTools.keysToList(t, keySort)
</source>
Returns a list of the keys in a table, sorted using either a default comparison function or a custom <code>keySort</code> function, which follows the same rules as the <code>comp</code> function supplied to [[mw:Extension:Scribunto/Lua reference manual#table.sort|<code>table.sort</code>]].
=== sortedPairs ===
<source lang="lua">
TableTools.sortedPairs(t, keySort)
</source>
Iterates through a table, with the keys sorted using the <code>keysToList</code> function. If there are only numerical keys, <code>sparseIpairs</code> is probably more efficient.
=== isArray ===
<source lang="lua">
TableTools.isArray(t)
</source>
Returns true if all keys in the table are consecutive integers starting at <code>1</code>.
=== listToSet ===
<source lang="lua">
TableTools.listToSet(arr)
</source>
Creates a set from the array part of the table <code>arr</code>. Indexing the set by any of the values in <code>arr</code> returns <code>true</code>.
<source lang="lua">
local set = TableTools.listToSet { "a", "b", "c" }
assert(set["a"] === true)
</source>
=== invert ===
<source lang="lua">
TableTools.invert(t)
</source>
Transposes the keys and values in an array. For example, <code>invert{ "a", "b", "c" }</code> yields <code>{ a = 1, b = 2, c = 3 }</code>.
=== deepCopy ===
<source lang="lua">
TableTools.deepCopy(orig, noMetatable, alreadySeen)
</source>
Creates a copy of the table <code>orig</code>. As with <code>mw.clone</code>, all values that are not functions are duplicated and the identity of tables is preserved. If <code>noMetatable</code> is <code>true</code>, then the metatable (if any) is not copied. Can copy tables loaded with <code>mw.loadData</code>.
Similar to <code>mw.clone</code>, but <code>mw.clone</code> cannot copy tables loaded with <code>mw.loadData</code> and does not allow metatables <em>not</em> to be copied.
=== sparseConcat ===
<source lang="lua">
TableTools.sparseConcat(t, sep)
</source>
Concatenates all values in the table that are indexed by a positive integer, in order.
=== length ===
<source lang="lua">
TableTools.length(t)
</source>
Returns the length of a table, or the first integer key <code>n</code> counting from <code>0</code> such that <code>t[n + 1]</code> is <code>nil</code>. It is similar to the operator <code>#</code>, but may return a different value when there are gaps in the array portion of the table. Intended to be used on data loaded with [[mw:Extension:Scribunto/Lua reference manual#mw.loadData|<code>mw.loadData</code>]] and on [[mw:Extension:Scribunto/Lua reference manual#frame.args|<code>frame.args</code>]]. Both use a metatable such that <code>#mw.loadData("module:...")</code> and <code>#frame.args</code> don't work correctly. For other tables, use <code>#</code>.
=== inArray ===
<source lang="lua">
TableTools.inArray(arr, valueToFind)
</source>
Returns <syntaxhighlight lang="lua" inline>true</syntaxhighlight> if <code>valueToFind</code> is a member of the array <code>arr</code>, and <syntaxhighlight lang="lua" inline>false</syntaxhighlight> otherwise.
<includeonly>{{Sandbox other||
[[Category:Lua metamodules|TableTools]]
}}</includeonly>
