List
Handles list-like operations.
Lists are ordered tables with numeric indices.
Functions
butLast
List.butLast(list: {Value}) → {Value}Returns a List containing all entires except the last.
Equivalent to slice(1, -1). See List.slice for more information.
List.butLast({ 1, 2, 3 })
-- { 1, 2 }
concat
List.concat(...: {Value}) → {Value}Returns a List of the same type concatenated to given arguments.
List.concat({ "a", "b", "c" }, { "d", "e", "f" })
-- { "a", "b", "c", "d", "e", "f" }
count
List.count(list: {Value},predicate: ((Value,number) → boolean)?) → number
Returns the number of entries that match the predicate.
If the predicate is not given, all entries will be considered a match.
List.count({ "a", "b", "c" })
-- 3
List.count({ "a", "b", "c" }, function(value)
return value == "b"
end)
-- 1
equals
List.equals(listA: {Value},listB: any) → booleanReturns true if both Lists have value equality.
local list1 = { "a", "b", "c" }
local list2 = { "a", "b", "c" }
List.equals(list1, list2)
-- true
every
List.every(list: {Value},predicate: (Value,number) → boolean) → booleanReturns true if predicate returns true for all entries in the list.
List.every({ "a", "b", "c" }, function(value, key)
return string.lower(value) == value
end)
-- true
filter
List.filter(list: {Value},predicate: (Value,number) → boolean) → {Value}Returns a new List of only entries for which the predicate function returns true.
List.filter({ 1, 2, 3, 4 }, function(value, key)
return value % 2 == 0
end)
-- { 2, 4 }
filterNot
List.filterNot(list: {Value},predicate: (Value,number) → boolean) → {Value}Returns a new List of only entries for which the predicate function returns false.
List.filterNot({ 1, 2, 3, 4 }, function(value, index)
return value % 2 == 0
end)
-- { 1, 3 }
find
List.find(list: {Value},predicate: (Value,number) → boolean,notSetValue: Value?) → Value?Returns the first value for which the predicate returns true.
List.find({ "a", "B", "c" }, function(value, key)
return value == string.upper(v)
end)
-- "B"
findIndex
List.findIndex(list: {Value},predicate: (Value,number) → boolean) → number?Returns the first index for which the predicate returns true.
List.findIndex({ "a", "B", "c" }, function(value, index)
return value == string.upper(v)
end)
-- 2
findPair
List.findPair(list: {Value},predicate: (Value,number) → boolean) → (number?,Value?)Returns the first [index, value] pair for which the predicate returns true.
List.findPair({ "a", "B", "c" }, function(value, index)
return value == string.upper(v)
end)
-- ( 2, "B" )
first
List.first(list: {Value},notSetValue: Value?) → ()Returns the first value in the list.
List.first({ "a", "b", "c" })
-- "a"
flatten
List.flatten(list: {ListOf<Value>},depth: number?) → {ListOf<Value>}Returns a flattened list in the same index-order as each Value would appear.
List.flatten({
"foo",
{
"bar",
"baz",
},
{
"bar",
"baz",
},
"quz",
})
-- { "foo", "bar", "baz", "bar", "baz", "quz" }
forEach
List.forEach(list: {Value},sideEffect: (Value,number) → boolean) → number
While the List is iterated, the sideEffect is executed for every entry.
If any call of the sideEffect returns false, the iteration will stop.
Returns the number of entries iterated (including the last iteration which returned false).
List.forEach({ 1, 10, -20, 30 }, function(value, index)
return value > 0
end)
-- 3
get
List.get(list: {Value},index: number,notSetValue: Value?) → Value?Returns the value at the given index, otherwise returns notSetValue if the given value is not found.
If index is negative, the index will start from the last value.
List.get({ "a", "b", "c" }, 3)
-- "c"
List.get({ "a", "b", "c" }, -1)
-- "c"
List.get({ "a", "b", "c" }, 100, "default")
-- "default"
has
List.has(list: {Value},index: number) → booleanReturns true if the index exists within the List.
List.has({ "a", "b", "c" }, 2)
-- true
includes
List.includes(list: {Value},query: Value) → booleanReturns true if the value is found within the List.
List.includes({ "a", "b", "c" }, "b")
-- true
indexOf
List.indexOf(list: {Value},searchValue: Value) → number?Returns the index of the value if found within the List, otherwise returns nil.
List.indexOf({ "a", "b", "c" }, "b")
-- 2
insert
List.insert(list: {Value},index: number,...: Value) → {Value}Inserts values given starting from the given index, pushing existing values towards the end.
The inserted value will be clamped to the beginning or end of the List if the given index is out of bounds.
List.insert({ "a", "b", "c" }, 2, "X", "Y", "Z")
-- { "a", "X", "Y", "Z", "b", "c" }
joinAsString
List.joinAsString(list: {Value},separator: string?) → stringJoins values together as a string, inserting a separator between each.
The default separator is ",".
List.joinAsString({ "a", "b", "c" }, ", ")
-- "a, b, c"
last
List.last(list: {Value},notSetValue: Value?) → Value?Returns the last value in the List.
Returns notSetValue if the List is empty.
List.last({ "a", "b", "c" })
-- "c"
List.last({ }, "default")
-- "default"
map
List.map(list: {Value},mapper: (Value,number) → (NewValue,number?)) → {NewValue}Returns a List with values passed through a mapper function.
Returning a second value in the mapper function will reassign the index.
If mapper returns nil, the entry will be filtered.
List.map({ 1, 2, 3 }, function(value, index)
return value * 10
end)
-- { 10, 20, 30 }
max
List.max(list: {Value},comparator: ((Value,Value) → boolean)?) → (Value,number?)Returns the maximum value in this List. If any values are comparatively equivalent, the first one found will be returned.
The comparator is used in the same way as table.sort. If it is not provided, the default comparator is >.
List.max({ 10, 200, 30 })
-- ( 200, 2 )
List.max({ child, teen, adult }, function(personA, personB)
return personA.age > personB.age
end)
-- ( adult, 3 )
merge
List.merge(...: {any}) → {any}Returns a merged result of all given Lists.
If Freeze.None is a value assigned to an index, it will delete that index from the resulting List.
List.merge({ 10, nil, 30 }, { nil, 20, nil })
-- { 10, 20, 30 }
List.merge({ "a", "b", "c" }, { "x" }, { nil, "y", Freeze.None })
-- { "x", "y" }
min
List.min(list: {Value},comparator: ((Value,Value) → boolean)?) → (Value,number?)Returns the minimum value in this List. If any values are comparatively equivalent, the first one found will be returned.
The comparator is used in the same way as table.sort. If it is not provided, the default comparator is >.
List.min({ 10, 200, 30 })
-- 10
List.min({ child, teen, adult }, function(personA, personB)
return personA.age > personB.age
end)
-- child
pop
List.pop(list: {Value},amount: number?) → {Value}Returns a List excluding the last index of this List.
This will repeat multiple times if given the optional amount argument and will always pop at least once.
List.pop({ 10, 20, 30 })
-- { 10, 20 }
List.pop({ 10, 20, 30 }, 2)
-- { 10 }
push
List.push(list: {Value},...: Value) → {Value}Returns a List with the provided values appended at the end of the List.
List.push({ 10, 20, 30 }, 40, 50, 60)
-- { 10, 20, 30, 40, 50, 60 }
reduce
List.reduce(list: {Value},reducer: (T,Value,number) → T,initialReduction: T) → T
Returns the final reduced result by iterating the List and calling the reducer for every entry
and passing along the reduced value.
List.reduce({ 10, 20, 30 }, function(reduction, value)
return reduction + value
end, 0)
-- 60
reduceRight
List.reduceRight(list: {Value},reducer: (T,Value,number) → T,initialReduction: T) → T
Returns the final reduced result by iterating the list in reverse (from the right side) and calling the reducer for every entry
and passing along the reduced value.
List.reduceRight({ "a", "b", "c" }, function(reduction, value)
return reduction .. value
end, "")
-- "cba"
remove
List.remove(list: {Value},...: number) → {Value}Returns a List which excludes this index. Values at indices above index are shifted down by 1 to fill the position.
index may be a negative number, which indexes back from the end of the list.
list.remove(-1) removes the last item in the list.
If the given given results in an index that is out of bounds, it will return the original list with no changes.
List.remove({ "a", "b", "c", "d" }, 3)
-- { "a", "b", "d" }
removeValue
List.removeValue(list: {Value},...: Value) → {Value}Returns a List having removed all entries with the given value.
If no values are present, it will return the original List with no changes.
List.removeValue({ "a", "b", "c" }, "a")
-- { "b", "c" }
rest
List.rest(list: {Value}) → {Value}Returns a List containing all entries except the first.
Equivalent to slice(2). See List.slice for more information.
List.rest({ "a", "b", "c" })
-- { "b", "c" }
reverse
List.reverse(list: {Value}) → {Value}Returns a List in reverse order.
List.reverse({ "a", "b", "c" })
-- { "c", "b", "a" }
set
List.set(list: {Value},index: number,value: Value) → {Value}
Returns a List which includes value at index.
If index already exists, it will be replaced.
Returns the original List if no changes were made.
List.set({"a", "b", "c"}, 1, "A")
-- { "A", "b", "c" }
shift
List.shift(list: {Value},amount: number?) → {Value}Returns a List excluding the first index in this List, shifting all other values to a lower index.
If amount is not provided, it will default to 1.
Passing an amount greater than the length of the given List will result in an empty List.
List.shift({ "a", "b", "c" })
-- { "b", "c" }
skip
List.skip(list: {Value},amount: number) → {Value}Returns a List which excludes the first amount of entries.
List.skip({ "a", "b", "c", "d" }, 2)
-- { "c", "d" }
slice
List.slice(list: {Value},from: number?,to: number?) → {Value}Returns a List that includes the range [from, to).
If from is negative, it is offset from the end of the list.
slice(-2) returns a list of the last two entries.
If it is not provided, the new list will begin at the first entry.
If to is negative, it is offset from the end of the list.
slice(1, -1) returns a list of everything but the last entry.
If it is not provided, the new list will continue through the end of the list.
List.slice({ "a", "b", "c" }, 2)
-- { "b", "c" }
List.slice({ "a", "b", "c" }, -1)
-- { "c" }
List.slice({ "a", "b", "c" }, 1, -1)
-- { "a", "b" }
some
List.some(list: {Value},predicate: (Value,number) → boolean) → booleanReturns true if predicate returns true for any entry in the List.
List.some({ 1, 2, 3 }, function(value, index)
return value % 2 == 0
end)
-- true
sort
List.sort(list: {Value},comparator: ((Value,Value) → boolean)?) → ()Returns a List which includes the same entries, sorted by using a comparator.
If a comparator is not provided, a default comparator uses < and >.
List.sort({ 4, 2, 1, 3 })
-- { 1, 2, 3, 4 }
take
List.take(list: {Value},amount: number) → {Value}Returns a List which includes the first amount of entires.
List.take({ "a", "b", "c", "d" }, 2)
-- { "a", "b" }
takeLast
List.takeLast(list: {Value},amount: number) → {Value}Returns a List which includes the last amount of entires.
List.takeLast({ "a", "b", "c" }, 2)
-- { "b", "c" }
unshift
List.unshift(list: {Value},...: Value) → {Value}Returns a List with the provided values prepended, shifting other values ahead to higher indices.
List.unshift({ "b", "c" }, "a")
-- { "a", "b", "c" }
update
List.update(list: {Value},index: number,updater: (Value?) → Value,notSetValue: Value?) → {Value}Returns a List with the entry at index updated to the result of updater.
If the entry does not exist, updater will be given notSetValue or nil.
List.update({ "a", "b", "c" }, 2, function(value)
return string.rep(value, 5)
end)
-- { "a", "bbbbb", "c" }
List.update({ "a", "b", "c" }, 4, function(value)
return string.rep(value, 5)
end, "d")
-- { "a", "b", "c", "ddddd" }
zip
List.zip(...: {Value}) → {{Value}}
Returns a List with all lists given "zipped" together.
The length of the List is the length of the shortest provided list.
List.zip({ "a", "b", "c" }, { "x", "y", "z" })
-- { { "a", "x" }, { "b", "y" }, { "c", "z" } }
List.zip({ alice, bertram, charlie }, { alexander, betty, candice, dennis })
-- { { alice, alexander }, { bertram, betty }, { charlie, candice } }
-- Note: dennis is omitted and not paired.
append
This was deprecated in v0.0.4
Use [List.push] instead.
List.append(list: {Value},...: Value) → {Value}create
This was deprecated in v0.0.4
Use [table.create] instead.
List.create(count: number,value: Value?) → {Value}findWhere
This was deprecated in v0.0.4
Use [List.find] instead.
List.findWhere(list: {Value},predicate: (Value,number) → boolean,from: never) → Value?findWhereLast
This was deprecated in v0.0.4
Use [List.reverse] and then [List.find] instead.
List.findWhereLast(list: {Value},predicate: (Value,number) → boolean,from: never?) → Value?join
This was deprecated in v0.0.4
Use [List.merge] instead.
List.join(...: {any}) → {any}removeIndex
This was deprecated in v0.0.4
Use [List.remove] instead.
List.removeIndex(list: {Value},index: number) → {Value}removeIndices
This was deprecated in v0.0.4
Use [List.remove] instead.
List.removeIndices(list: {Value},...: number) → {Value}removeValues
This was deprecated in v0.0.4
Use [List.removeValue] instead.
List.removeValues(list: {Value},...: Value) → {Value}