ArrayForLua
Array.lua contains a collection of Array methods for working with tables and arrays in Lua.
Roblox Developers:
- Click on
📄 Array.lua- Click the Raw button
- Press Ctrl+A to Select All then Ctrl+C to Copy the code
- Open Roblox Studio
- Insert a ModuleScript into ReplicatedStorage
- Rename the ModuleScript to Array and open the file
- Delete the starter code in the file, then press Ctrl+V to paste in the Array code
- To include the Array module in other scripts:
local ReplicatedStorage = game:GetService('ReplicatedStorage')
local Array = require(ReplicatedStorage:WaitForChild('Array'))
- Non-copylocked "Game" with full test coverage and implementation examples here
How to Use
-
There are two easy ways to use ArrayForLua methods:
- Wrap the table to give it Array methods (internally, via setmetatable).
local t = {4, 1, 3, 2} Array(t) t:Sort() -- {1, 2, 3, 4}
- Call Array methods directly, passing them a table as the first argument
local t = {4, 1, 3, 2} Array.Sort(t) -- {1, 2, 3, 4}
The API documentation below uses the first method to illustrate implementation as the syntax looks more like native Lua.
ArrayForLua API
| Array Methods: B - F | Array Methods: I - R | Array Methods: S - V | Array Utility Methods |
|---|---|---|---|
| BinaryFirst() | Includes() | Shift() | Length() |
| BinaryLast() | IndexOf() | Slice() | getTableType() |
| BlockSwap() | InsertionSort() | Some() | isArray() |
| Concat() | Join() | Sort() | isDictionary() |
| Entries() | Keys() | Splice() | isEmpty() |
| Every() | LastIndexOf() | Swap() | isMixed() |
| Fill() | Map() | Unshift() | isTable() |
| Filter() | Pop() | Values() | toString() |
| Find() | Push() | ||
| FindIndex() | Reduce() | ||
| ForEach() | ReduceRight() | ||
| From() | Reverse() | ||
| Rotate() |
BinaryFirst
The BinaryFirst() method uses a binary search algorithm to locate instances of searchElement in table and returns the index of the first occurrence.
If searchElement is not found, nil is returned.
Example
local A = Array({1, 1, 1, 2, 2, 2, 3, 3})
A:BinaryFirst(2) -- 4
A:BinaryFirst(3) -- 7Syntax
Array.BinaryFirst(array, searchElement, start, stop)Parameters
array Required
- The table to be searched must be an array.
searchElement Required
- The value to find in the array.
start Optional
- Location in the array to begin searching.
stop Optional
- Location in the array to stop searching.
Return Value
- The first index of the item found in the array; or nil if the item was not found.
BinaryLast
The BinaryLast() method uses a binary search algorithm to locate instances of searchElement in table and returns the index of the last occurrence.
If searchElement is not found, nil is returned.
Example
local A = Array({1, 1, 1, 2, 2, 2, 3, 3})
A:BinaryLast(2) -- 6
A:BinaryLast(3) -- 8Syntax
Array.BinaryLast(array, searchElement, start, stop)Parameters
array Required
- The table to be searched must be an array.
searchElement Required
- The value to find in the array.
start Optional
- Location in the array to begin searching.
stop Optional
- Location in the array to stop searching.
Return Value
- The last index of the item found in the array; or nil if the item was not found.
BlockSwap
The BlockSwap() method exchanges one block (range) of items in an array with a second block of items.
Example
local A = Array({1, 2, 3, 4, 5, 6, 7, 8})
A:BlockSwap(1, 5, 4)
unpack(A) -- 5 6 7 8 1 2 3 4Syntax
Array.BlockSwap(array, indexA, indexB, count)Parameters
array Required
- The table to be searched must be an array.
indexA Required
- Index in the array where the first block begins.
indexB Required
- Index in the array where the second block begins.
count Required
- The length of each block is equal to count; blocks must be of equal size.
- The last index of each block ==
index[A|B] + count - 1
Return Value
- Returns the original, modified table.
Concat
The Concat() method is used to merge two or more arrays. This method does not change the existing arrays, but instead returns a new array.
Example
local A1 = Array({'a', 'b', 'c'})
local A2 = {'d', 'e', 'f'}
local A3 = A1:Concat(A2)
-- A3 is a new array { 'a', 'b', 'c', 'd', 'e', 'f' }Syntax
local newArray = Array.Concat(sourceArray, value1[, value2[, ...[, valueN]]])Parameters
sourceArray Required
- The initial table on which to add new values must be an array.
valueN Required
- Array(s) and/or value(s) to concatenate into a new array.
The Concat method creates a new array consisting of the elements in the array on which it is called, followed in order by, for each argument, the elements of that argument (if the argument is an array) or the argument itself (if the argument is not an array). It does not recurse into nested array arguments.
Return Value
- A new Table instance of sub-type 'Array'
Entries
The Entries() method returns a new Table Iterator object that contains the key/value pairs for each element in the table.
Example 1: Calling the Iterator's internal Next() function
local A = Array({'a', 'b', 'c'})
local Next = A:Entries()
Next() -- 1 'a'
Next() -- 2 'b'
Next() -- 3 'c'
Next() -- nil nilExample 2: Using
for...inloop on an array
local A = Array({'a', 'b', 'c'})
for k, v in A:Entries() do
print(k, v)
end
-- 1 'a'
-- 2 'b'
-- 3 'c'Example 3: Using
for...inloop on a dictionary
local A = Array({foo='bar', faa='baz', fee='boz'})
for k, v in A:Entries() do
print(k, v)
end
-- faa 'baz'
-- fee 'boz'
-- foo 'bar'Syntax
local iterator = Array.Entries(table)Parameters
table Required
- The table to iterate over can be array, dictionary, or mixed.
Return Value
- The iterator function.
Every
The Every() method tests whether all elements in a table pass the test implemented by the provided function.
Example
local isBigEnough = function (element, index, array, this) {
return element >= 10
}
local A1 = Array({12, 5, 8, 130, 44})
local A2 = Array({12, 54, 18, 130, 44})
A1:Every(isBigEnough) -- false
A2:Every(isBigEnough) -- trueSyntax
local isEveryTrue = Array.Every(table, function, context)Parameters
table Required
- The table to iterate over can be array, dictionary, or mixed.
function Required
- Function to test for each element, taking up to four arguments:
- currentValue
Required- The current element being processed in the table.
- index Optional
- The index of the current element being processed in the array.
- For dictionary and mixed tables, the key is returned as the index.
- table Optional
- The table Every was called upon.
- this Optional
- The context to use for the this variable.
- Defaults to the Array API Object.
- currentValue
context Optional
- Optional. Context for the this argument passed to function.
The Every method executes the provided function once for each element present in table until it finds one where function returns a falsy value. If such an element is found, the Every method immediately returns false. Otherwise, if function returns a truthy value for all elements, Every returns true.
function is invoked with four arguments: the value of the element, the index of the element, the Table object being traversed, and a This object.
Every does not mutate table on which it was called.
The range of elements processed by Every is set before the first invocation of function. Elements which are appended to table after the call to Every begins will not be visited by function. If existing elements of table are changed, their value as passed to function will be the value at the time Every visits them; elements that are deleted are not visited.
Every acts like the "for all" quantifier in mathematics. In particular, for an empty table, it returns true.
Return Value
- The result. true if the callback function returns truthy for every table value; otherwise, false.
Fill
The Fill() method fills all the elements of an array from a start index to an end index with a static value.
Dictionary and mixed tables have unordered indices, so they are always filled from end to end.
Example
local A = Array({1, 2, 3})
A:Fill(1)
unpack(A) -- 1 1 1Syntax
Array.Fill(table, value, start, stop)Parameters
table Required
- The table to iterate over can be array, dictionary, or mixed.
value Required
- The value used to fill all elements of table.
start Optional
- First index, defaults to 1.
- Dictionary and mixed tables always use the default.
stop Optional
- Last index, defaults to the length of table.
- Dictionary and mixed tables always use the default.
Return Value
- The original, modified table
Filter
The Filter() method creates a new array with all elements that pass the test implemented by the provided function.
Example 1: Filter a numeric array
local moreThanTen = function (n)
return n > 10
end
local A1 = {12, 5, 8, 90, 44}
local Filtered = A1:Filter(moreThanTen)
unpack(Filtered) -- 12 90 44Example 2: Filter a dictionary table
local moreThanTen = function (n)
return n > 10
end
local Ages = Array({sam = 12, mike = 5, bob = 8, al = 90, jim = 44})
local Filtered = Ages:Filter(moreThanTen)
Array.toString(Filtered) -- 'jim=44,al=90,sam=12'Example 3: Filter items based on search criteria (query)
local Fruit = Array({'apple', 'banana', 'grapes', 'mango', 'orange'})
local FilterItems = function (query)
return Fruit:Filter(function (el)
return string.find(string.lower(el), string.lower(query)) ~= nil
end)
end
local Filtered = FilterItems('ap')
unpack(Filtered) -- apple grapes
Filtered = FilterItems('an')
unpack(Filtered) -- banana mango orangeSyntax
local newArray = Array.Filter(table, callback[, context])Parameters
table Required
- The table to Filter can be array, dictionary, or mixed.
function Required
- Function is a predicate, to test each element of the table. Return true to keep the element, false otherwise, taking up to four arguments:
- currentValue
Required- The current element being processed in the table.
- index Optional
- The index of the current element being processed in the array.
- For dictionary and mixed tables, the key is returned as the index.
- table Optional
- The table Filter was called upon.
- this Optional
- The context to use for the this variable.
- Defaults to the Array API Object.
- currentValue
context Optional
- Optional. Context for the this argument passed to function.
Filter() does not mutate the table on which it is called.
Return Value
- A new array containing the elements that pass the test implemented by function.
Find
The Find() method returns the value of the first element in a table that satisfies the provided testing function.
Example
local moreThanTen = function (n)
return n > 10
end
local A = Array({5, 9, 2, 42, 1, 16})
A:Find(moreThanTen) -- 42Syntax
Array.Find(table, function, context)Parameters
table Required
- The table to search can be array, dictionary, or mixed.
function Required
- Function to execute on each value in the table, taking up to four arguments:
- currentValue
Required- The current element being processed in the table.
- index Optional
- The index of the current element being processed in the array.
- For dictionary and mixed tables, the key is returned as the index.
- table Optional
- The table Find was called upon.
- this Optional
- The context to use for the this variable.
- Defaults to the Array API Object.
- currentValue
context Optional
- Optional. Context for the this argument passed to function.
Return Value
- The first value in the table that passes the test; otherwise, nil.
FindIndex
The FindIndex() method returns the index of the first element in the array that satisfies the provided testing function or -1 if a match is not found.
Example
local moreThanTen = function (n)
return n > 10
end
local A = Array({5, 9, 2, 42, 1, 16})
A:FindIndex(moreThanTen) -- 4Syntax
Array.FindIndex(array, function, context)Parameters
array Required
- The table to be searched must be an array.
function Required
- Function to execute on each value in the table, taking up to four arguments:
- currentValue
Required- The current element being processed in the array.
- index Optional
- The index of the current element being processed in the array.
- table Optional
- The array FindIndex was called upon.
- this Optional
- The context to use for the this variable.
- Defaults to the Array API Object.
- currentValue
context Optional
- Optional. Context for the this argument passed to function.
Return Value
- The first index within the array containing a value that passes the test; otherwise, -1.
ForEach
The ForEach() method executes a provided function once for each table element.
Example
local A = Array({'a', 'b', 'c'})
A.ForEach(function (element)
print(element)
end)
-- 'a'
-- 'b'
-- 'c'Syntax
Array.ForEach(table, function, context)Parameters
table Required
- The table to enumerate can be array, dictionary, or mixed.
function Required
- Function to execute for each value in the table, taking up to four arguments:
- currentValue Optional
- The current element being processed in the table.
- index Optional
- The index of the current element being processed in the array.
- For dictionary and mixed tables, the key is returned as the index.
- table Optional
- The table ForEach was called upon.
- this Optional
- The context to use for the this variable.
- Defaults to the Array API Object.
- currentValue Optional
context Optional
- Optional. Context for the this argument passed to function.
Return Value
- nil.
From
The From() method creates a new Array instance from a number, string, or table.
Example 1: Array from string
local newArray = Array.From('test')
unpack(newArray) -- t e s tExample 2: Array from table
local oldArray = {'a', 'b', 1, 2}
local newArray = Array.From(oldArray)
newArray[1] = 'b'
unpack(newArray) -- 'b' 'b' 1 2
unpack(oldArray) -- 'a' 'b' 1 2Syntax
local newArray = Array.From(item)Parameters
item Required
- A number, string, or table used to generate a new array.
Return Value
- A new Table instance of sub-type Array.
Includes
The Includes() method determines whether a table includes a certain value, returning true or false as appropriate.
Example
local A = Array({1, 2, 3})
A:Includes(2) -- true
A:Includes(4) -- falseSyntax
Array.Includes(table, searchElement, start)Parameters
table Required
- The table to search can be array, dictionary, or mixed.
searchElement Required
- The value to search for.
start Optional
- The position in table at which to begin searching for searchElement.
- A negative value searches from the index of #table + fromIndex. Defaults to 1.
- fromIndex is ignored if table is a dictionary or mixed table.
Return Value
- A Boolean. true if table contains searchElement, false otherwise.
IndexOf
The IndexOf() method returns the first index at which a given value can be found in the array, or -1 if it is not present.
Example
local A = Array({2, 9, 9})
A.indexOf(2) -- 1
A.indexOf(7) -- -1Syntax
Array.IndexOf(array, searchElement, start)Parameters
array Required
- The table to be searched must be an array.
searchElement Required
- The value to locate in array.
start Optional
- The position in array at which to begin searching for searchElement.
- A negative value searches from the index of #array + fromIndex. Defaults to 1.
Return Value
- The first index of the value in array; -1 if not found.
InsertionSort
The InsertionSort() method sorts an array, in-place, in ascending order.
The insertion sort algorithm is extremely fast when sorting small arrays (from 2 to 10 items).
Array.Sort() should be used to sort arrays larger than 10 items.
Example
local A = Array({9, 7, 6, 15, 16, 5, 10, 11})
A:InsertionSort()
unpack(A) -- 5 6 7 9 10 11 15 16Syntax
Array.InsertionSort(array, start, stop)Parameters
array Required
- The table to be sorted must be an array.
start Optional
- Index of the first element in the range to be sorted. Defaults to 1.
stop Optional
- Index of the last element in the range to be sorted. Defaults to #array
Return Value
- The original, sorted array.
Join
The Join() method joins all values of a table into a string.
Example
local A = Array({'Wind', 'Rain', 'Fire'})
A:Join() -- 'Wind,Rain,Fire'
A:Join('-') -- 'Wind-Rain-Fire'Syntax
Array.Join(table, separator)Parameters
table Required
- The table to Join can be array, dictionary, or mixed.
separator Optional
- Specifies a string to separate each element of the array.
- separator is converted to a string if necessary. If omitted, the array elements are separated with a comma (',').
- If separator is an empty string, all elements are joined without any characters between them.
Return Value
- A string with all array values joined.
Keys
The Keys() method returns a new Table Iterator that contains the keys for each element in the table.
Example 1: Calling the Iterator's internal Next() function
local T = Array({a='foo', b='bar', c='baz'})
local Next = T:Keys()
Next() -- a
Next() -- c
Next() -- bExample 2: Using
for...inloop
local T = Array({a='foo', b='bar', c='baz'})
for k in T:Keys() do
print(k)
end
-- a
-- c
-- bSyntax
local iterator = Array.Keys(table)Parameters
table Required
- The table to iterate over can be array, dictionary, or mixed.
Return Value
- The iterator function.
LastIndexOf
The LastIndexOf() method returns the last index at which a given value can be found in the array, or -1 if it is not present.
Example
local A = Array({2, 9, 9})
A:indexOf(2) -- 1
A:indexOf(7) -- -1Syntax
Array.IndexOf(array, searchElement, start)Parameters
array Required
- The table to be searched must be an array.
searchElement Required
- The value to locate in array.
start Optional
- The position in array at which to begin searching for searchElement.
- A negative value searches from the index of #array + fromIndex. Defaults to 1.
Return Value
- The first index of the value in array; -1 if not found.
Length
The Length() method returns the number of elements in a table.
Example
local A = {'foo', 'bar', 'foobar'}
local T = {foo='foo', bar='bar', n=1}
A:Length() -- 3
T:Length() -- 3Syntax
Array.Length(table)Parameters
table Required
- The table to measure can be array, dictionary, or mixed.
Return Value
- A number representing the number of elements in an array. -1 is returned if array is not a valid table.
Map
The Map() method creates a new table with the results of calling a provided function on every element in a source table.
Example
local A = Array({1, 5, 10, 15})
local doubles = A:Map(function (n) return n * 2 end)
unpack(doubles) -- 2 10 20 30
unpack(A) -- 1 5 10 15
local B = Array({1, 4, 9})
local Roots = B:Map(math.sqrt)
unpack(Roots) -- 1 2 3
unpack(B) -- 1 4 9Syntax
local mappedArray = Array.Map(table, function, context)Parameters
table Required
- The table to enumerate can be array, dictionary, or mixed.
function Required
- Function to execute for each value in the table, taking up to four arguments:
- currentValue
Required- The current element being processed in the table.
- index Optional
- The index of the current element being processed in the array.
- For dictionary and mixed tables, the key is returned as the index.
- table Optional
- The table Map was called upon.
- this Optional
- The context to use for the this variable.
- Defaults to the Array API Object.
- currentValue
context Optional
- Optional. Context for the this argument passed to function.
Map does not mutate the table on which it is called (although function, if invoked, may do so).
Return Value
- A new table with each element being the result of the callback function.
Pop
The Pop() method removes the last element from an array and returns that element.
This method changes the length of the array.
Example
local A = Array({1, 2, 3})
local removed = A:Pop()
print(removed) -- 3
unpack(A) -- 1 2Syntax
local removedElement = Array.Pop(array)Parameters
array Required
- The table to be modified must be an array.
Return Value
- The removed element from the array; nil if the array is empty or if the provided array is not an array.
Push
The Push() method adds one or more elements to the end of an array and returns the new length of the array.
Example
local A = Array({1, 2, 3})
local newLength = A:Push(4)
print(newLength) -- 4
unpack(A) -- 1 2 3 4
newLength = A:Push(5, 6, 7)
print(newLength) -- 7
unpack(A) -- 1 2 3 4 5 6 7Syntax
local newLength = Array.Push(array, [element1[, ...[, elementN]]])Parameters
array Required
- The table to be modified must be an array.
elementN Required
- The value(s) to add to the end of array.
Return Value
- The new length of the array upon which the method was called.
Reduce
The Reduce() method applies a function against an accumulator and each element in the array (from left to right) to reduce it to a single value.
Example
local A1 = Array({0, 1, 2, 3})
local Reduced = A1:Reduce(function (sum, n)
return sum + n
end)
print(Reduced) -- 6
local A2 = Array({{0, 1}, {2, 3}, {4, 5}})
local Flattened = A2:Reduce(function (a, b)
return Array.Concat(a, b)
end, {})
-- flattens to {0, 1, 2, 3, 4, 5}
unpack(Flattened) -- 0 1 2 3 4 5Syntax
local reducedValue = Array.Reduce(array, function, initialValue)Parameters
array Required
- The table to be reduced must be an array.
function Required
- Function to execute on each element in the array, taking four arguments:
- accumulator
Required- The accumulator accumulates function's return values; it is the accumulated value previously returned in the last invocation of function, or initialValue, if supplied (see below).
- currentValue
Required- The current element being processed in the array.
- index Optional
- The index of the current element being processed in the array.
- Starting index is 1, if initialValue is provided, or index 2 otherwise.
- table Optional
- The table Map was called upon.
- accumulator
initialValue Optional
- Optional. Value to use as the first argument to the first call to function. If no initial value is supplied, the first element in the array will be used.
Calling Reduce on an array does not mutate the original array.
For a detailed explanation of Reduce, visit MDN Array.prototype.reduce: How Reduce Works, keeping in mind those examples are JavaScript which starts at index 0. Lua arrays start at index 1.
Return Value
- The value that results from the reduction.
- Calling Reduce on an empty array or non-array object both return nil.
ReduceRight
The ReduceRight() method applies a function against an accumulator and each element in the array (from right to left) to reduce it to a single value.
Example
local A = Array({0, 1, 2, 3, 4})
local Reduced = A:ReduceRight(function (prev, cur)
return prev..', '..cur
end)
print(Reduced) -- '4, 3, 2, 1, 0'Syntax
local reducedValue = Array.ReduceRight(array, function, initialValue)Parameters
array Required
- The table to be reduced must be an array.
function Required
- Function to execute on each element in the array, taking four arguments:
- accumulator
Required- The accumulator accumulates function's return values; it is the accumulated value previously returned in the last invocation of function, or initialValue, if supplied (see below).
- currentValue
Required- The current element being processed in the array.
- index Optional
- The index of the current element being processed in the array.
- Starting index is the length of array, if initialValue is provided, or #array - 1 otherwise.
- table Optional
- The table Map was called upon.
- accumulator
initialValue Optional
- Optional. Value to use as the first argument to the first call to function. If no initial value is supplied, the last element in the array will be used.
Calling ReduceRight on an array does not mutate the original array.
For a detailed explanation of ReduceRight, visit MDN Array.prototype.reduceRight, keeping in mind those examples are JavaScript which starts at index 0. Lua arrays start at index 1.
Return Value
- The value that results from the reduction.
- Calling ReduceRight on an empty array or non-array object both return nil.
- Calling ReduceRight on an array with 1 item immediately returns that item.
Reverse
The Reverse() method reverses part or all of an array (in place).
When index positions are provided, a sub-array within the Array is reversed. Otherwise, the entire array is reversed.
Example
local A1 = Array({'foo', 'bar', 'foobar'})
A1:Reverse()
unpack(A1) -- foobar bar foo
local A2 = {1, 2, 3, 'a', 'b', 'c'}
A2:Reverse(3, 5)
unpack(A2) -- 1 2 b a 3 cSyntax
Array.Reverse(array, start, stop)Parameters
array Required
- The table to be reversed must be an array.
start Optional
- The first index in the range of items to be reversed. Default is 1.
- If start is a negative number, the first index will be offset from the end of the array, and can be calculated as (array length) + (negative start)
stop Optional
- The last index in the range of items to be reversed. Default is the length of array.
- If stop is a negative number, the last index will be offset from the end of the array, and can be calculated as (array length) + (negative stop)
Reverse modifies the array on which it is called.
If the calculated value of stop is less than the calculated value of start, no elements are moved and the array remains unaffected.
Return Value
- Returns the original, reversed array.
Rotate
The Rotate() method moves a range of items in an array to the left or right by some number of spaces, with values on the edges wrapping around to the other end.
Example
local A1 = Array({0, 1, 2, 3, 4})
A1:Rotate(1, 5, 1)
unpack(A1) -- 1 2 3 4 0
local A2 = Array({0, 1, 2, 3, 4, 5, 6})
A2:Rotate(3, 5, 1)
unpack(A2) -- 0 1 3 4 2 5 6Syntax
Array.Rotate(array, start, stop, step)Parameters
array Required
- The table to be rotated must be an array.
start Required
- The first index in the range of items to be rotated.
- If start is a negative number, the first index will be offset from the end of the array, and can be calculated as (array length) + (negative start)
stop Required
- The last index in the range of items to be reversed.
- If stop is a negative number, the last index will be offset from the end of the array, and can be calculated as (array length) + (negative stop)
step Required
- The number of spaces to move elements to the right or left. Positive step moves items left, while negative step moves items right. A step of 0 returns array, unmodified.
Rotate modifies the array on which it is called.
When an item in the desired range is shifted left or right, another item is pushed off the end of the range as a result. That item is added to the opposite end of the range, allowing movement of items to wrap (rotate) through the table.
Return Value
- Returns the original, rotated array.
Shift
The Shift() method removes the first element from an array and returns that element.
This method changes the length of the array.
Example
local A = Array({1, 2, 3})
local removed = A:Shift()
unpack(A) -- 2 3
print(removed) -- 1Syntax
local removedElement = Array.Shift(array)Parameters
array Required
- The table to be modified must be an array.
Return Value
- The removed element from the array; nil if the array is empty or if the provided array is not an array.
Slice
The Slice() method creates a shallow copy of a portion of an array and returns it.
The original array is not modified.
Example
local A = Array({'foo', 'bar', 'foobar'})
local newArray = A:Slice(2, 3)
unpack(newArray) -- 'bar' 'foobar'
unpack(A) -- 'foo' 'bar' 'foobar'
newArray = A:Slice(-1, -1)
unpack(newArray) -- 'bar'Syntax
local newArray = Array.Slice(array, start, stop)Parameters
array Required
- The table to be modified must be an array.
start Optional
- The first index in the range of items to be returned. Default is 1.
- If start is a negative number, the first index will be offset from the end of the array, and can be calculated as (array length) + (negative start)
stop Optional
- The last index in the range of items to be returned. Default is the length of array.
- If stop is a negative number, the last index will be offset from the end of the array, and can be calculated as (array length) + (negative stop)
Return Value
- A new array containing the extracted elements.
Some
The Some() method tests whether some element in a table passes the test implemented by the provided function.
Example
local moreThanTen = function (n)
return n > 10
end
local A1 = Array({2, 5, 8, 1, 4})
local A2 = Array({2, 8, 1, 12, 4})
local someBiggerThanTen = A1:Some(moreThanTen)
print(someBiggerThanTen) -- false
someBiggerThanTen = A2:Some(moreThanTen)
print(someBiggerThanTen) -- trueSyntax
local atLeastOneTrue = Array.Some(table, function, context)Parameters
table Required
- The table to enumerate can be array, dictionary, or mixed.
function Required
- Function to execute for each value in the table, taking up to four arguments:
- currentValue
Required- The current element being processed in the table.
- index Optional
- The index of the current element being processed in the array.
- For dictionary and mixed tables, the key is returned as the index.
- table Optional
- The table Some was called upon.
- this Optional
- The context to use for the this variable.
- Defaults to the Array API Object.
- currentValue
context Optional
- Optional. Context for the this argument passed to function.
Return Value
- true if function returns a truthy value for any table value comparison; otherwise, false.
Sort
The Sort() method sorts the elements of an array in place and returns the array.
If Sort is called on a dictionary or mixed table, an iterator is returned and the original table is not modified.
Example 1: Ascending and descending sort on arrays
local A = Array({5, 9, 12, 2, 1, 55})
A:Sort()
table.concat(a, ', ') -- 1, 2, 5, 9, 12, 55
A = Array({5, 9, 12, 2, 1, 55}) -- reset array
A:Sort(1) -- descending sort
table.concat(a, ', ') -- 55, 12, 9, 5, 2, 1Example 2: Sort becomes an iterator when used on dictionary/mixed tables
local Scores = Array({tim = 45, tom = 90, ted = 20})
-- Ascending
for k, v in Scores:Sort() do
print(k..' has '..v..' points')
end
-- ted has 20 points
-- tim has 45 points
-- tom has 90 points
-- Descending
for k, v in Scores:Sort(1) do
print(k..' has '..v..' points')
end
-- tom has 90 points
-- tim has 45 points
-- ted has 20 pointsSyntax
Array.Sort(table, direction, function)Parameters
table Required
- The table to sort can be array, dictionary, or mixed.
direction Optional
- Optional. Sort descending by passing 1, ascending by passing -1. Default is -1 (ascending).
function Optional
- Function that defines the sort order, taking two arguments:
- valueA
Required- The first element to compare.
- valueB
Required- The second element to compare.
- valueA
- function must return true if valueA should come before valueB.
Return Value
- The original, sorted array if table is an array.
- Otherwise, an iterator is returned to enumerate table in sorted order.
Splice
The Splice() method changes the contents of an array by removing existing elements and/or adding new elements.
Example
local A = Array({'foo', 'bar', 'foobar'})
local Removed = A:Splice(2, 2, 'raboof', 'rab')
unpack(Removed) -- 'bar' 'foobar'
unpack(A) -- 'foo' 'raboof' 'rab'
-- reset a
A = Array({'foo', 'bar', 'foobar'})
Removed = A:Splice(-1, 2)
unpack(Removed) -- 'bar' 'foobar'
unpack(A) -- 'foo'Syntax
local removedElements = Array.Splice(array, start, deleteCount, [element1[, ...[, elementN]]])Parameters
array Required
- The table to be modified must be an array.
start Optional
- The first index in the range of items to be removed. Default is 1.
- If start is a negative number, the start index will be offset from the end of the array, and can be calculated as (array length) + (negative start)
- If the final calculated value of the start index is less than or equal to 0, start is set to the length of array.
deleteCount Optional
- An integer indicating the number of old array elements to remove.
- If deleteCount is 0, no elements are removed. In this case, you should specify at least one new element.
- If deleteCount is greater than the number of elements left in array starting at start, then all of the elements through the end of array will be deleted.
- If deleteCount is omitted, then all of the elements beginning at start through the end of array will be deleted.
elementN Optional The element(s) to add to array, beginning at start. If you don't specify any elements, Splice() will only remove elements from array.
Return Value
- An array containing the deleted elements. If only one element is removed, an array of one element is returned.
- If no elements are removed, an empty array is returned.
- If array is not actually an array, nil is returned.
Swap
The Swap() method exchanges the values at two locations in an array.
Example
local A1 = Array({'a', 'b', 'c'})
A1:Swap(1, 3)
unpack(A1) -- 'c' 'b' 'a'
local A2 = {'foo', 'bar', 'baz', 'foobar'}
A2:Swap(4, 2)
unpack(A2) -- foo foobar baz barSyntax
Array.Swap(array, indexA, indexB)Parameters
array Required
- The table to be modified must be an array.
indexA Required
- Index of the value to move into indexB of array.
indexB Required
- Index of the value to move into indexA of array.
Return Value
- The original, modified array
Unshift
The Unshift() method adds one or more elements to the beginning of an array and returns the new length of the array.
Example
local A = Array({1, 2, 3})
local newLength = A:Unshift(4, 5)
print(newLength) -- 5
unpack(A) -- 4 5 1 2 3Syntax
local newLength = Array.Unshift(array, [element1[, ...[, elementN]]])Parameters
array Required
- The table to be modified must be an array.
elementN Required
- The element(s) to add to the beginning of array.
Return Value
- The new length of array.
Values
The Values() method returns a new Table Iterator that contains the values for each element in the table.
Example 1: Calling the Iterator's internal Next() function
local A = Array({'w', 'y', 'k', 'o', 'p'})
local Next = A:Values()
Next() -- 'w'
Next() -- 'y'
Next() -- 'k'
Next() -- 'o'
Next() -- 'p'
Next() -- nilExample 2: Using
for...inloop
local T = Array({a='foo', b='bar', c='baz'})
for k in T:Values() do
print(k)
end
-- 'foo'
-- 'baz'
-- 'bar'Syntax
local iterator = Array.Values(table)Parameters
table Required
- The table to iterate over can be array, dictionary, or mixed.
Return Value
- The iterator function.
...more documentation is coming. The following utility methods are also available:
getTableType
isArray
isDictionary
isEmpty
isMixed
isTable
toString
If ArrayForLua makes you happy, consider Donate a coffee to the Dev