此頁面為 Module:TableTools 的說明文件
本模組包含一系列用於處理Lua表的函數。這是個元模組,用於其他Lua模組呼叫,而不應該由#invoke直接呼叫。
載入模組
如需載入任何函數,首先需要載入模組。
local TableTools = require('Module:TableTools')
isPositiveInteger
TableTools.isPositiveInteger(value)
如果value
是正整數,返回true
,否則返回false
。雖然此函數不是應用於表的,但這裏仍收錄了此函數以決定一個給定的鍵是否在表的陣列部分或雜湊部分。
isNan
TableTools.isNan(value)
如果value
是NaN值,返回true
,否則返回false
。雖然此函數不是應用於表的,但這裏仍收錄了此函數以決定一個值能否作為有效的鍵。(將NaN作為鍵會報錯。)
shallowClone
TableTools.shallowClone(t)
返回表格的副本。返回的值是一個新表,但是所有的子表和函數都會共用。不會繞過元表,但返回的表自身不會帶有元表。如需在建立新表時不共用子表格且要複製元表,可以使用mw.clone。
shallowCloneArray
TableTools.shallowCloneArray(t)
返回陣列的副本。返回的值是一個新的陣列類似於shallowClone
,但是只會複製陣列部分。
rawShallowClone
TableTools.rawShallowClone(t)
類似於TableTools.shallowClone
,但是迭代時會繞過__pairs
元表。
appendAll
TableTools.appendAll(t, anotherArray)
在陣列t的末尾添加陣列anotherArray的所有內容。會修改t,不返回值。
removeDuplicates
TableTools.removeDuplicates(t)
從陣列中返回重複值。此函數僅用於標準的陣列,所有非正整數鍵的一律忽略,第一個nil
後的值也會忽略。(對於包含nil
的陣列,可以先使用compressSparseArray。)此函數嘗試保護陣列的順序:有重複值時,僅保留最早出現的那個。例如,對於表{5, 4, 4, 3, 4, 2, 2, 1}
,removeDuplicates返回{5, 4, 3, 2, 1}
。
numKeys
TableTools.numKeys(t)
接收表t
並以數字順序返回擁有非nil值的正整數鍵的數量。例如,對於{'foo', nil, 'bar', 'baz', a = 'b'}
,numKeys返回{1, 3, 4}
。
allNumKeys
TableTools.allNumKeys(t)
類似於numKeys
,但是不限於正整數。
affixNums
TableTools.affixNums(t, prefix, suffix)
接收表t
並返回包含含有可選字首prefix
和可選字尾suffix
的鍵的數量的陣列。例如,對於表{a1 = 'foo', a3 = 'bar', a6 = 'baz'}
和字首'a'
,affixNums返回{1, 3, 6}
。prefix
和suffix
的值均按字面解釋(不使用正則表達式)。
allAffixNums
TableTools.allAffixNums(t, prefix, suffix)
類似於affixNums
,但是不限於正整數。
numData
TableTools.numData(t, compress)
假如一個表有像foo1、bar1、foo2、baz2這樣的鍵,返回如下格式的子表的表{ [1] = {foo = 'text', bar = 'text'}, [2] = {foo = 'text', baz = 'text'} }
。不以整數結尾的鍵儲存在命名為other的子表中。compress選項會壓縮表以便通過ipairs迭代。
allPrefixedNumKeys
TableTools.allPrefixedNumKeys(t, pattern)
假設有{a1 = 'a1', a2 = 'a2', a3 = 'a3', b1 = 'b1', b2 = 'b2'}
這樣的表,返回{a = {'a1', 'a2', 'a3'}, b = {'b1', 'b2'} }
這樣的表。非以數字結尾的表會被忽略,且該表的子表可能是稀疏陣列。
pattern用於指定正則表達式匹配。例如,若pattern
為'^(category)(.+)$'
只會匹配以「category」開頭,任意數字(可以是小數、負數)結尾的部分。這個正則表達式需要擷取兩個值,第一個值是字首,即返回的表的鍵,第二個值是可能是數字的部分,應當有可能用tonumber轉化為數字。
compressSparseArray
TableTools.compressSparseArray(t)
接收一個帶有一個或更多nil值的陣列t
,移除所有的nil值,不影響其他值的順序,以便於安全地通過ipairs遍歷。所有非正整數的鍵都會移除。例如,對於表{1, nil, foo = 'bar', 3, 2}
,compressSparseArray返回{1, 3, 2}
。
compressExtendedSparseArray
TableTools.compressExtendedSparseArray(t)
類似於compressSparseArray
,但是不會移除非正整數鍵和小數鍵。
sparseIpairs
TableTools.sparseIpairs(t)
這是用於遍歷稀疏陣列t
的迭代器函數。類似於ipairs,但會一直迭代直到最高的數字鍵,而ipairs遇到第一個nil
就可能會終止。忽略所有的非正整數鍵。
sparseIpairs常用於通用的for
迴圈。
for i, v in TableTools.sparseIpairs(t) do
-- 代码
end
注意sparseIpairs會在實現時使用pairs。儘管一些鍵看上去被忽略,但實際上執行時也會遍歷到。
extendedSparseIpairs
TableTools.extendedSparseIpairs(t)
類似於sparseIpairs
,但是不會忽略非正整數鍵和小數鍵。
size
TableTools.size(t)
尋找「鍵/值對」表的大小。例如,對於{foo = 'foo', bar = 'bar'}
,size返回2
。函數也可以用於陣列,但是對於陣列,使用#運算子更高效。注意,為了尋找表的大小,函數會使用pairs函數以遍歷所有的表鍵。
rawSize
TableTools.rawSize(t)
類似於size
,但是會忽略__pairs
元方法。
keysToList
TableTools.keysToList(t, keySort)
返回表的鍵的列表,並按預設比較函數或者自訂keySort
函數排序,與table.sort
的comp
函數類似。
rawKeysToList
TableTools.rawKeysToList(t, keySort)
類似於keysToList
,但是會忽略__pairs
元方法。
sortedPairs
TableTools.sortedPairs(t, keySort)
迭代表,並使用keysToList
函數來排序鍵。如果只有數字鍵,sparseIpairs
可能更高效。
該函數不能作為表的__pairs
元方法,否則會出現堆疊溢位。
rawSortedPairs
TableTools.rawSortedPairs(t, keySort)
類似於rawSortedPairs
,但是會忽略__pairs
元方法,可以作為表的__pairs
元方法。
isArray
TableTools.isArray(t)
如果表中的所有鍵都是以1
開始的接連不斷的整數,返回true。
listToSet
TableTools.listToSet(arr)
從表arr
的陣列部分建立一個集(set)。用arr
的任何值來索引集都會返回true
。
local set = TableTools.listToSet { "a", "b", "c" }
assert(set["a"] == true)
invert
TableTools.invert(t)
交換陣列中的鍵和值。例如,invert{ "a", "b", "c" }
產生{ a = 1, b = 2, c = 3 }
。
deepCopy
TableTools.deepCopy(orig, noMetatable, alreadySeen)
返回表orig
的副本,類似於mw.clone
,所有非函數的值都會複製,並保留表的唯一性。如果noMetatable
為true
,則不會複製元表(如有)。可以複製由mw.loadData
載入的表。
與mw.clone
類似,但mw.clone
不能夠複製由mw.loadData
載入的表,也不允許拒絕複製元表。
sparseConcat
TableTools.sparseConcat(t, sep)
按順序連接被正整數索引的表的所有值。
inArray
TableTools.inArray(arr, valueToFind)
如果valueToFind
是陣列arr
的成員,返回true
,否則返回false
。