Модуль:TableTools/doc
Это страница документации Модуль:TableTools.
 |
Данный модуль предоставляет функции для работы с таблицами Lua. В общем случае, его функции не должны вызываться напрямую через #invoke, а только использоваться в других модулях.
Подключение
Для использования функционала модуль сперва следует подключить.
<syntaxhighlight lang="lua"> local TableTools = require('Module:TableTools') </syntaxhighlight>
isPositiveInteger
<syntaxhighlight lang="lua"> TableTools.isPositiveInteger(value) </syntaxhighlight> Возвращает
<syntaxhighlight lang="lua" inline="1">true</syntaxhighlight> если
value — положительное целое число и
<syntaxhighlight lang="lua" inline="1">false</syntaxhighlight> иначе. Хотя эта функция и не относится напрямую к таблицам, она нужна для определения, является ли ключ ключом массива либо же хэш-таблицы.
isNan
<syntaxhighlight lang="lua"> TableTools.isNan(value) </syntaxhighlight> Возвращает
<syntaxhighlight lang="lua" inline="1">true</syntaxhighlight> если
value представляет собой NaN и
<syntaxhighlight lang="lua" inline="1">false</syntaxhighlight> иначе. Хотя эта функция и не относится напрямую к таблицам, она нужна для определения, может ли значение быть ключом таблицы.
shallowClone
<syntaxhighlight lang="lua">
TableTools.shallowClone(t)
</syntaxhighlight>
Возвращает клон таблицы. Возвращаемое значение представляет собой новую таблицу, но все подтаблицы и функции являются разделяемыми. Метаметоды переносятся, но возвращаемая таблица не будет включать метатаблицу. Если вы хотите скопировать подтаблицы и метатаблицу, используйте mw.clone. Если вы хотите скопировать подтаблицы, но не переносить метатаблицы, используйте <syntaxhighlight lang="text" class="" id="" style="" inline="1">deepCopy</syntaxhighlight> с параметром <syntaxhighlight lang="text" class="" id="" style="" inline="1">noMetatable</syntaxhighlight>.
removeDuplicates
<syntaxhighlight lang="lua"> TableTools.removeDuplicates(t) </syntaxhighlight> Удаляет из массива значения-дубликаты. Функция предназначена для работы только со стандартными массивами: обрабатываются только ключи-положительные целые числа, а все значения после первого <syntaxhighlight lang="lua" inline="1">nil</syntaxhighlight> игнорируются. (Для массивов, содержащих <syntaxhighlight lang="lua" inline="1">nil</syntaxhighlight>, используйте <syntaxhighlight lang="text" class="" id="" style="" inline="1">compressSparseArray</syntaxhighlight> перед этой функцией.) Функция старается сохранить порядок следования элементов — оставляется первое вхождение значения, а все последующие удаляются. Например, для таблицы <syntaxhighlight lang="lua" inline="1">{5, 4, 4, 3, 4, 2, 2, 1}</syntaxhighlight> <syntaxhighlight lang="text" class="" id="" style="" inline="1">removeDuplicates</syntaxhighlight> вернёт <syntaxhighlight lang="lua" inline="1">{5, 4, 3, 2, 1}</syntaxhighlight>.
numKeys
<syntaxhighlight lang="lua">
TableTools.numKeys(t)
</syntaxhighlight>
Принимает на вход таблицу
t и возвращает массив из положительных целых чисел, которые являются ключами таблицы для данных с непустым значением, отсортированный в порядке возрастания. Например, для таблицы
<syntaxhighlight lang="lua" inline="1">{'foo', nil, 'bar', 'baz', a = 'b'}</syntaxhighlight> вызов <syntaxhighlight lang="text" class="" id="" style="" inline="1">numKeys</syntaxhighlight> вернёт
<syntaxhighlight lang="lua" inline="1">{1, 3, 4}</syntaxhighlight>.
affixNums
<syntaxhighlight lang="lua">
TableTools.affixNums(t, prefix, suffix)
</syntaxhighlight>
Принимает на вход таблицу
t и возвращает массив из положительных целых чисел, которым соответствуют ключи таблицы с опциональным префиксом
prefix и опциональным суффиксом
suffix. Например, для таблицы
<syntaxhighlight lang="lua" inline="1">{a1 = 'foo', a3 = 'bar', a6 = 'baz'}</syntaxhighlight> и префикса
a вызов <syntaxhighlight lang="text" class="" id="" style="" inline="1">affixNums</syntaxhighlight> вернёт
<syntaxhighlight lang="lua" inline="1">{1, 3, 6}</syntaxhighlight>. Все символы в
prefix и
suffix интерпретируются буквально.
numData
<syntaxhighlight lang="lua">
TableTools.numData(t, compress)
</syntaxhighlight>
Дла таблицы с ключами вида
foo1,
bar1,
foo2 и
baz2 возвращает таблицы с подтаблицами в формате
<syntaxhighlight lang="lua" inline="1">{ [1] = {foo = 'text', bar = 'text'}, [2] = {foo = 'text', baz = 'text'} }</syntaxhighlight>. Ключи, не заканчивающиеся числом размещаются в подтаблице
other. Опция
compress позволяет использовать таблицу для цикла с помощью <syntaxhighlight lang="text" class="" id="" style="" inline="1">ipairs</syntaxhighlight>.
compressSparseArray
<syntaxhighlight lang="lua">
TableTools.compressSparseArray(t)
</syntaxhighlight>
Принимает на вход массив
t с пустыми значениями (
<syntaxhighlight lang="lua" inline="1">nil</syntaxhighlight>) и убирает их, сохраняя порядок, чтобы массив мог использоваться в <syntaxhighlight lang="text" class="" id="" style="" inline="1">ipairs</syntaxhighlight>. Нечисловые ключи удаляются. Например, для таблицы
<syntaxhighlight lang="lua" inline="1">{1, nil, foo = 'bar', 3, 2}</syntaxhighlight> вызов <syntaxhighlight lang="text" class="" id="" style="" inline="1">compressSparseArray</syntaxhighlight> вернёт
<syntaxhighlight lang="lua" inline="1">{1, 3, 2}</syntaxhighlight>.
sparseIpairs
<syntaxhighlight lang="lua">
TableTools.sparseIpairs(t)
</syntaxhighlight>
Итератор для перебора элементов разреженного массива
t. Аналогичен ipairs, но продолжится до достижения ключа с максимальным числовым значением, в отличе от обычного <syntaxhighlight lang="text" class="" id="" style="" inline="1">ipairs</syntaxhighlight>, останавливающегося на первом
<syntaxhighlight lang="lua" inline="1">nil</syntaxhighlight>. Нечисловые ключи игнорируются.
<syntaxhighlight lang="text" class="" id="" style="" inline="1">sparseIpairs</syntaxhighlight> может использоваться для цикла <syntaxhighlight lang="text" class="" id="" style="" inline="1">for</syntaxhighlight>.
<syntaxhighlight lang="lua">
for i, v in TableTools.sparseIpairs(t) do
-- code block
end </syntaxhighlight>
Обратите внимание, что функция <syntaxhighlight lang="text" class="" id="" style="" inline="1">sparseIpairs</syntaxhighlight> основана на pairs. Хота в итератор для цикла могут передаваться не все ключи, читаться будут всё равно все.
size
<syntaxhighlight lang="lua">
TableTools.size(t)
</syntaxhighlight>
Возращает размер таблицы пар ключ-значение. Например, для таблицы
<syntaxhighlight lang="lua" inline="1">{foo = 'foo', bar = 'bar'}</syntaxhighlight> вызов <syntaxhighlight lang="text" class="" id="" style="" inline="1">size</syntaxhighlight> вернёт <syntaxhighlight lang="text" class="" id="" style="" inline="1">2</syntaxhighlight>. Функция также работает и для массивов, но для них следует использовать встроенный оператор языка <syntaxhighlight lang="text" class="" id="" style="" inline="1">#</syntaxhighlight>. Обратите внимание, что в своей работе функция использует функцию pairs для итерирования по всем ключам.
keysToList
<syntaxhighlight lang="lua">
TableTools.keysToList(t, keySort)
</syntaxhighlight>
Возвращает список ключей таблицы, используя либо сортировку по умолчанию, либо произвольную функцию
keySort, соотвествующую правилам для функции <syntaxhighlight lang="text" class="" id="" style="" inline="1">comp</syntaxhighlight> для table.sort.
sortedPairs
<syntaxhighlight lang="lua"> TableTools.sortedPairs(t, keySort) </syntaxhighlight> Итератор, перебирающий ключи таблицы в порядке, возвращаемом функцией <syntaxhighlight lang="text" class="" id="" style="" inline="1">keysToList</syntaxhighlight>. Если в таблице используются только числовые ключи, <syntaxhighlight lang="text" class="" id="" style="" inline="1">sparseIpairs</syntaxhighlight> будет эффективнее.
isArray
<syntaxhighlight lang="lua"> TableTools.isArray(t) </syntaxhighlight> Возвращает
<syntaxhighlight lang="lua" inline="1">true</syntaxhighlight>, если все ключи таблицы — положительные числа, начиная с <syntaxhighlight lang="text" class="" id="" style="" inline="1">1</syntaxhighlight>.
listToSet
<syntaxhighlight lang="lua">
TableTools.listToSet(arr)
</syntaxhighlight>
Создаёт множество на основе значений числовых ключей таблицы
arr. Получение значения множества для значений
arr вернёт
<syntaxhighlight lang="lua" inline="1">true</syntaxhighlight>.
<syntaxhighlight lang="lua">local set = TableTools.listToSet { "a", "b", "c" } assert(set["a"] == true)</syntaxhighlight>
invert
<syntaxhighlight lang="lua"> TableTools.invert(t) </syntaxhighlight> Транспонирует ключи и значения массива. Например, <syntaxhighlight lang="text" class="" id="" style="" inline="1">invert{ "a", "b", "c" </syntaxhighlight>} вернёт <syntaxhighlight lang="text" class="" id="" style="" inline="1">{ a = 1, b = 2, c = 3</syntaxhighlight>}. Работает только для числовых ключей.
deepCopy
<syntaxhighlight lang="lua">
TableTools.deepCopy(orig, noMetatable, alreadySeen)
</syntaxhighlight>
Создаёт копию таблицы
orig. Как и при использовании <syntaxhighlight lang="text" class="" id="" style="" inline="1">mw.clone</syntaxhighlight> все значения, не являющиеся функциями, дублируются и идентичность таблиц сохраняется. Если
noMetatable выставляется в
<syntaxhighlight lang="lua" inline="1">true</syntaxhighlight>, метатаблица (если имеется) не копируется. Может копировать таблицы, загруженные с помощью <syntaxhighlight lang="text" class="" id="" style="" inline="1">mw.loadData</syntaxhighlight>.
В отличие от этой функции <syntaxhighlight lang="text" class="" id="" style="" inline="1">mw.clone</syntaxhighlight> не работает с таблицами, загруженными с помощью <syntaxhighlight lang="text" class="" id="" style="" inline="1">mw.loadData</syntaxhighlight>, и не имеет возможности не копировать метатаблицы.
sparseConcat
<syntaxhighlight lang="lua"> TableTools.sparseConcat(t, sep) </syntaxhighlight> Производит конкатенацию всех значений для числовых ключей с сохранением их порядка.
length
<syntaxhighlight lang="lua"> TableTools.length(t) </syntaxhighlight> Возвращает длину массива или псевдомассива с ключами вида <syntaxhighlight lang="text" class="" id="" style="" inline="1">data1</syntaxhighlight>, <syntaxhighlight lang="text" class="" id="" style="" inline="1">data2</syntaxhighlight> и т.д. Использует алгоритм экспоненциального поиска, поэтому производится минимальное количество обращений.
Алгоритм полезен для массивов с метатаблицами (например, frame.args) и для псевдомассивов. Для обычных массивов предпочтительнее оператор #, реализованный на Си, он будет работать заметно быстрее.
inArray
<syntaxhighlight lang="lua"> TableTools.inArray(arr, valueToFind) </syntaxhighlight> Возвращает
<syntaxhighlight lang="lua" inline="1">true</syntaxhighlight> если
valueToFind входит в
arr или
<syntaxhighlight lang="lua" inline="1">false</syntaxhighlight> иначе.
