模組:TableTools/doc

本模塊包含一系列用於處理Lua表的函數。這是個元模塊，用於其他Lua模塊調用，而不應該由#invoke直接調用。

加載模塊

如需加載任何函數，首先需要加載模塊。

<syntaxhighlight lang="lua"> local TableTools = require('Module:TableTools') </syntaxhighlight>

isPositiveInteger

<syntaxhighlight lang="lua"> TableTools.isPositiveInteger(value) </syntaxhighlight>

如果value是正整數，返回true，否則返回false。雖然此函數不是應用於表的，但這裡仍收錄了此函數以決定一個給定的鍵是否在表的數組部分或哈希部分。

isNan

<syntaxhighlight lang="lua"> TableTools.isNan(value) </syntaxhighlight>

如果value是NaN值，返回true，否則返回false。雖然此函數不是應用於表的，但這裡仍收錄了此函數以決定一個值能否作為有效的鍵。（將NaN作為鍵會報錯。）

shallowClone

<syntaxhighlight lang="lua"> TableTools.shallowClone(t) </syntaxhighlight>

返回表格的副本。返回的值是一個新表，但是所有的子表和函數都會共用。不會繞過元表，但返回的表自身不會帶有元表。如需在創建新表時不共享子表格且要複製元表，可以使用mw.clone。

removeDuplicates

<syntaxhighlight lang="lua"> TableTools.removeDuplicates(t) </syntaxhighlight>

從數組中返回重複值。此函數僅用於標準的數組，所有非正整數鍵的一律忽略，第一個nil後的值也會忽略。（對於包含nil的數組，可以先使用compressSparseArray。）此函數嘗試保護數組的順序：有重複值時，僅保留最早出現的那個。例如，對於表<syntaxhighlight lang="lua" inline="">{5, 4, 4, 3, 4, 2, 2, 1}</syntaxhighlight>，removeDuplicates返回<syntaxhighlight lang="lua" inline="">{5, 4, 3, 2, 1}</syntaxhighlight>。

numKeys

<syntaxhighlight lang="lua"> TableTools.numKeys(t) </syntaxhighlight>

接收表t並以數字順序返回擁有非nil值的正整數鍵的數量。例如，對於<syntaxhighlight lang="lua" inline="">{'foo', nil, 'bar', 'baz', a = 'b'}</syntaxhighlight>，numKeys返回<syntaxhighlight lang="lua" inline="">{1, 3, 4}</syntaxhighlight>。

affixNums

<syntaxhighlight lang="lua"> TableTools.affixNums(t, prefix, suffix) </syntaxhighlight>

接收表t並返回包含含有可選前綴prefix和可選後綴suffix的鍵的數量的數組。例如，對於表<syntaxhighlight lang="lua" inline="">{a1 = 'foo', a3 = 'bar', a6 = 'baz'}</syntaxhighlight>和前綴'a'，affixNums返回<syntaxhighlight lang="lua" inline="">{1, 3, 6}</syntaxhighlight>。prefix和suffix的值均按字面解釋（不使用正則表達式）。

numData

<syntaxhighlight lang="lua"> TableTools.numData(t, compress) </syntaxhighlight>

假如一個表有像foo1、bar1、foo2、baz2這樣的鍵，返回如下格式的子表的表<syntaxhighlight lang="lua" inline="">{ [1] = {foo = 'text', bar = 'text'}, [2] = {foo = 'text', baz = 'text'} }</syntaxhighlight>。不以整數結尾的鍵存儲在命名為other的子表中。compress選項會壓縮表以便通過ipairs迭代。

compressSparseArray

<syntaxhighlight lang="lua"> TableTools.compressSparseArray(t) </syntaxhighlight>

接收一個帶有一個或更多nil值的數組t，移除所有的nil值，不影響其他值的順序，以便於安全地通過ipairs遍歷。所有非正整數的鍵都會移除。例如，對於表<syntaxhighlight lang="lua" inline="">{1, nil, foo = 'bar', 3, 2}</syntaxhighlight>，compressSparseArray返回<syntaxhighlight lang="lua" inline="">{1, 3, 2}</syntaxhighlight>。

sparseIpairs

<syntaxhighlight lang="lua"> TableTools.sparseIpairs(t) </syntaxhighlight>

這是用於遍歷稀疏數組t的迭代器函數。類似於ipairs，但會一直迭代直到最高的數字鍵，而ipairs遇到第一個nil就可能會終止。忽略所有的非正整數鍵。

sparseIpairs常用於通用的for循環。

<syntaxhighlight lang="lua"> for i, v in TableTools.sparseIpairs(t) do

  -- 代码

end </syntaxhighlight>

注意sparseIpairs會在實現時使用pairs。儘管一些鍵看上去被忽略，但實際上運行時也會遍歷到。

size

<syntaxhighlight lang="lua"> TableTools.size(t) </syntaxhighlight>

尋找「鍵/值對」表的大小。例如，對於<syntaxhighlight lang="lua" inline="">{foo = 'foo', bar = 'bar'}</syntaxhighlight>，size返回2。函數也可以用於數組，但是對於數組，使用#操作符更高效。注意，為了查找表的大小，函數會使用pairs函數以遍歷所有的表鍵。

keysToList

<syntaxhighlight lang="lua"> TableTools.keysToList(t, keySort) </syntaxhighlight>

返回表的鍵的列表，並按默認比較函數或者自定義keySort函數排序，與table.sort的comp函數類似。

sortedPairs

<syntaxhighlight lang="lua"> TableTools.sortedPairs(t, keySort) </syntaxhighlight>

迭代表，並使用keysToList函數來排序鍵。如果只有數字鍵，sparseIpairs可能更高效。

isArray

<syntaxhighlight lang="lua"> TableTools.isArray(t) </syntaxhighlight>

如果表中的所有鍵都是以1開始的接連不斷的整數，返回true。

listToSet

<syntaxhighlight lang="lua"> TableTools.listToSet(arr) </syntaxhighlight>

從表arr的數組部分創建一個集（set）。用arr的任何值來索引集都會返回true。

<syntaxhighlight lang="lua"> local set = TableTools.listToSet { "a", "b", "c" } assert(set["a"] == true) </syntaxhighlight>

invert

<syntaxhighlight lang="lua"> TableTools.invert(t) </syntaxhighlight>

交換數組中的鍵和值。例如，invert{ "a", "b", "c" }產生{ a = 1, b = 2, c = 3 }。

deepCopy

<syntaxhighlight lang="lua"> TableTools.deepCopy(orig, noMetatable, alreadySeen) </syntaxhighlight>

返回表orig的副本，類似於mw.clone，所有非函數的值都會複製，並保留表的唯一性。如果noMetatable為true，則不會複製元表（如有）。可以複製由mw.loadData加載的表。

與mw.clone類似，但mw.clone不能夠複製由mw.loadData加載的表，也不允許拒絕複製元表。

sparseConcat

<syntaxhighlight lang="lua"> TableTools.sparseConcat(t, sep) </syntaxhighlight>

按順序連接被正整數索引的表的所有值。

length

<syntaxhighlight lang="lua"> TableTools.length(t) </syntaxhighlight>

查找數組的長度，或者帶有像data1、data2這樣的鍵的准數組。使用指數搜索算法以查找長度，以便於儘可能少地使用表查找（table lookup）。

對於准數組，此算法對使用元表的數組有用（例如frame.args）。對於正常數組，只需要使用#操作符，因為#操作符是由C語言實現的，速度更快。

inArray

<syntaxhighlight lang="lua"> TableTools.inArray(arr, valueToFind) </syntaxhighlight>

如果valueToFind是數組arr的成員，返回<syntaxhighlight lang="lua" inline>true</syntaxhighlight>，否則返回<syntaxhighlight lang="lua" inline>false</syntaxhighlight>。