Module:Array/doc

From Brighter Shores Wiki
Revision as of 17:52, 22 March 2024 by Habblet (talk | contribs) (Created page with "{{Documentation}} {{Helper module |name = Array |fname1 = <nowiki>all( arr, [fn] )</nowiki> |ftype1 = <samp>arr: any[]</samp><br><samp>fn?: any</samp><br><samp>-> boolean</samp> |fuse1 = Behaviour depends on the value of <code>fn</code>: * <code>nil</code> - Checks that the array doesn't contain any '''false''' elements. * <code>fun(elem: any, i?: integer): boolean</code> - Returns '''true''' if <code>fn</code> returns '''true''' for every element. * <code>nu...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

This is the documentation page for Module:Array

This is a documentation subpage for Module:Array.
It contains usage information, categories, and other content that is not part of the original module page.
Module:Array requires libraryUtil.
Module:Array is required by Module:DependencyList.

This module is a helper module to be used by other modules; it may not designed to be invoked directly. See Brighter Shores:Lua/Helper modules for a full list and more information.

FunctionTypeUse
all( arr, [fn] )arr: any[]
fn?: any
-> boolean
Behaviour depends on the value of fn:
  • nil - Checks that the array doesn't contain any false elements.
  • fun(elem: any, i?: integer): boolean - Returns true if fn returns true for every element.
  • number | table | boolean - Checks that all elements in arr are equal to this value.
any( arr, [fn] )arr: any[]
fn?: any
-> boolean
Behaviour depends on the value of fn:
  • nil - Checks that the array contains at least one non false element.
  • fun(elem: any, i?: integer): boolean - Returns true if fn returns true for at least one element.
  • number | table | boolean - Checks that arr contains this value.
clean( arr )arr: any[]
-> any[]
Recursively removes all metatables.
clone( arr, [deep] )arr: any[]
deep?: boolean
-> any[]
Make a copy of the input table. Preserves metatables.
contains( arr, val )arr: any[]
val: any
-> boolean
Check if arr contains val.
containsAny( arr, t )arr: any[]
t: any[]
-> boolean
Check if arr contains any of the values in the table t.
containsAll( arr, t )arr: any[]
t: any[]
-> boolean
Check if arr contains all values in the table t.
convolve( x, y )x: number[]
y: number[]
-> number[]
Convolute two number arrays.
condenseSparse( arr )arr: any[]
-> any[]
Remove nil values from arr while preserving order.
count( arr, fn )arr: any[]
fn: any
-> integer
Behaviour depends on value of val:
  • nil - Counts the number of non false elements.
  • fun(elem: any): boolean - Count the number of times the function returned true.
  • boolean | number | table - Counts the number of times this value occurs in arr.
diff( arr, [order|1] )arr: number[]
order?: number
-> number[]
Differentiates arr. The length of the result is #arr - order long.
each( arr, fn )arr: any[]
fn: fun(elem: any, i?: integer)
Loops over the array part of arr and passes each element as the first argument to fn. This function returns nothing.
filter( arr, fn )arr: any[]
fn: fun(elem: any, i?: integer): boolean
-> any[]
Makes a copy of arr with only elements for which fn returned true.
find( arr, fn, [default] )arr: any[]
fn: any
default?: any
-> any?, integer?
Behaviour depends on the value of fn:
  • fun(elem: any, i?: integer): boolean - Find the first elements for which fn returns true.
  • boolean | number | table - Find the first occurance of this value.
Returns two values: the element itself and its index.
find_index( arr, fn, [default] )arr: any[]
fn: any
default?: any
-> integer?
Behaviour depends on the value of fn:
  • fun(elem: any, i?: integer): boolean - Find the index of the first elements for which fn returns true.
  • boolean | number | table - Find the index of the first occurance of this value.
get( arr, indexes )arr: any[]
indexes: integer|integer[]
-> any[]
Extracts a subset of arr.
int( arr, [start|1], [stop|#arr] )arr: number[]
start?: number
stop?: number
-> number[]
Integrates arr from index start to stop. Effectively does {startnarr[n]|n[start,stop]}.
intersect( arr1, arr2 )arr1: any[]
arr2: any[]
-> any[]
Returns an array with elements that are present in both tables.
intersects( arr1, arr2 )arr1: any[]
arr2: any[]
-> boolean
Checks if the two inputs have at least one element in common.
insert( arr, val, [index], [unpackVal] )
insert( arr, val, [unpackVal] )
arr: any[]
val: any
index?: integer
unpackVal?: boolean
-> any[]
Inserts values into arr. If val is an array and unpackVal is true then the individual elements of val are inserted. index is the location to start the insertion. Default is at the end of arr.
last( arr )arr: any[]
-> any
Returns the last element of arr.
len( arr )arr: any[]
-> integer
Returns the length of the array but it also works on proxy arrays like mw.loadData or mw.loadJsonData.
map( arr, fn )arr: any[]
fn: fun(elem: any, i?: integer): any
-> any[]
Returns a new table were each element of arr is modified by fn.
max_by( arr, fn )arr: any[]
fn: fun(elem: any): any
-> any, integer
Find the element for which fn returned the largest value. The returned value of fn needs to be comparable using the < operator. Returns three values: The element with the largest fn value, its fn result, and its index.
max( arr )arr: any[]
-> any, integer
Find the largest value in the array. The values need to be comparable using the < operator. Returns two values: the element and its index.
min( arr )arr: any[]
-> any, integer
Find the smallest value in the array. The values need to be comparable using the < operator. Returns two values: the element and its index.
new( [arr|{}] )arr?: any[]
-> any[]
Turn the input table into an Array. This makes it possible to use the colon : operator to access the Array methods. It also enables the use of math operators with the array.
local x = arr.new{ 1, 2, 3 }
local y = arr{ 4, 5, 6 } -- Alternative notation

mw.logObject( -x ) --> { -1, -2, -3 }
mw.logObject( x + 2 ) --> { 3, 4, 5 }
mw.logObject( x - 2 ) --> { -1, 0, 1 }
mw.logObject( x * 2 ) --> { 2, 4, 6 }
mw.logObject( x / 2 ) --> { 0.5, 1, 1.5 }
mw.logObject( x ^ 2 ) --> { 1, 4, 9 }

mw.logObject( x + y ) --> { 5, 7, 9 }
mw.logObject( x .. y ) --> { 1, 2, 3, 4, 5, 6 }
mw.logObject( (x .. y):reject{3, 4, 5} ) --> { 1, 2, 6 }
mw.logObject( x:sum() ) --> 6

mw.logObject( x:update( {1, 3}, y:get{2, 3} * 2 ) ) --> { 10, 2, 12 }
newIncrementor( [start|1], [step|1] )start?: number
step?: number
-> Incrementor
Returns a new incrementor function. Every time this incrementor function is called it returns a number step higher than the previous call. The current value can be obtained with inc.n or set inc.n = number where inc is an incrementor function. The step size can be changed with inc.step = number.
range( stop )
range( start, stop, [step|1] )
start: number
stop: number
step?: number
-> number[]
Returns a table containing a sequence of numbers from start to stop (both inclusive if ints, end-exclusive if floats) by step. range(4) produces {1, 2, 3, 4} (start defaults to 1). range(0, 4) produces {0, 1, 2, 3, 4}. When step is given, it specifies the increment (or decrement).
reduce( arr, fn, [accumulator|arr[1]] )arr: any[]
fn: fun(elem: any, acc: any, i?: integer): any
accumulator?: any
-> any
Condenses the array into a single value.

For each element fn is called with the current element, the current accumulator, and the current element index. The returned value of fn becomes the accumulator for the next element.

If no accumulator value is given at the start then the first element off arr becomes the accumulator and the iteration starts from the second element.

local t = { 1, 2, 3, 4 }
local sum = arr.reduce( t, function(elem, acc) return acc + elem end ) -- sum == 10
reject( arr, val )arr: any[]
val: any
-> any[]
Make a copy off arr with certain values removed.

Behaviour for different values of val:

  • boolean | number - Remove values equal to this.
  • table - Remove all values in this table.
  • fun(elem: any, i?: integer): boolean - Remove elements for which the functions returns true.
rep( val, n )val: any
n: number
-> any[]
Returns a table with n copies of val.
scan( arr, fn, [accumulator|arr[1]] )arr: any[]
fn: fun(elem: any, acc: any, i?: integer): any
accumulator?: any
-> any[]
Condenses the array into a single value while saving every accumulator value.

For each element fn is called with the current element, the current accumulator, and the current element index. The returned value of fn becomes the accumulator for the next element.

If no accumulator value is given at the start then the first element off arr becomes the accumulator and the iteration starts from the second element.

local t = { 1, 2, 3, 4 }
local x = arr.scan( t, function(elem, acc) return acc + elem end ) -- x = { 1, 3, 6, 10 }
set( arr, indexes, values )arr: any[]
indexes: integer|integer[]
values: any|any[]
-> any[]
Update a range of index with a range of values.

If if only one value is given but multiple indexes than that value is set for all those indexes.

If values is a table then it must of the same length as indexes.
slice( arr, [start|1], [stop|#arr] )
slice( arr, stop )
arr: any[]
start?: number
stop?: number
-> any[]
Returns a table containing all the elements of arr between the start and stop indices. The start and stop indices are inclusive. If start or stop are negative values then they are referenced to the end of the table.
split( arr, index )arr: any[]
index: number
-> any[], any[]
Split arr into two arrays. Retuns two tables. The first contains elements from [1, index], and the second from [index + 1, #arr].
sum( arr )arr: number[]
-> number
Returns the sum of all elements of arr.
take( arr, count, [start|1] )arr: any[]
count: number
start?: number
-> any[]
Extract a subtable from arr of count elements long starting from the start index.
take_every( arr, n, [start|1], [count|#arr] )arr: any[]
n: integer
start?: integer
count?: integer
-> any[]
Extract a subtable from arr.
local t = { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 }
local x = arr.take_every( t, 2 )       --> x = { 1, 3, 5, 7, 9 }
local x = arr.take_every( t, 2, 3 )    --> x = { 3, 5, 7, 9 }
local x = arr.take_every( t, 2, 3, 2 ) --> x = { 3, 5 }
unique( arr, [fn] )arr: any[]
fn?: fun(elem: any): any
-> any[]
Return a new table with all duplicates removed. fn is an optional function to generate an id for each element. The result will then contain elements that generated unique ids. The order of first occurance is preserved.
zip( ... )...any[]
-> any[][]
Combine elements with the same index from multiple arrays.
local x = {1, 2, 3}
local y = {4, 5, 6, 7}
local z = arr.zip( x, y ) --> z = { { 1, 4 }, { 2, 5 }, { 3, 6 }, { 7 } }

Example:

local arr = require( 'Module:Array' )

local x = arr{1, 2, 3, 4, 10}
local y = arr{'a', 'b', 'b', 1}

arr.any( x, function( item ) return item == 3 end ) --> true
arr.all( y, function( item ) return type( item ) == 'string' end ) --> false
arr.map( x, function( item ) return item * 2 end ) --> { 2, 4, 6, 8, 20 }
arr.filter( y, function( item ) return type( item ) == 'string' end ) --> { "a", "b", "b" }
arr.reject( y, function( item ) return type( item ) == 'string' end ) --> { 1 }
arr.find( x, function( item ) return item > 5 end ) --> 10,  5
arr.find_index( y, function( item ) return type( item ) ~= 'string' end ) --> 4
arr.max_by( x, function( item ) return item * 2 end ) --> 10, 20, 5
arr.reduce( x, function( item, acc ) return acc + item*item end, 5 ) --> 135
arr.range( 10, 1, -3 ) --> { 10, 7, 4, 1 }
arr.scan( x, function( item, acc ) return acc + item*item end, 5 ) --> { 6, 10, 19, 35, 135 }
arr.slice( x, 2, 4 ) --> { 2, 3, 4 }
arr.split( x, 2 ) --> { 1, 2 }, { 3, 4, 10 }
arr.sum( x ) --> 20
arr.take( x, 2 ) --> { 1, 2 }
arr.take_every( x, 2 ) --> { 1, 3, 10 }
arr.unique( y ) --> { "a", "b", 1 }
arr.zip( x, y, {20, 30} ) --> { { 1, "a", 20 }, { 2, "b", 30 }, { 3, "b" }, { 4, 1 }, { 10 } }
arr.intersect( x, y ) --> { 1 }
arr.intersects( x, y ) --> true
arr.contains({ 1, 2, 3}, 3) --> true
arr.diff( x ) --> { 1, 1, 1, 6 }
arr.int( x ) --> { 1, 3, 6, 10, 20 }
arr.insert( x, y, 3 ) --> { 1, 2, { "a", "b", "b", 1 }, 3, 4, 10 }

inc = arr.newIncrementor( 10, 5 )
print( inc() ) --> 10
print( inc() ) --> 15