Module:Array/doc

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.

Function	Type	Use
`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 ${\sum_{s t a r t}^{n} a r r [n] \| n \in [s t a r t, s t o p]}$ .
`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