Array - MSUTeam/MSU GitHub Wiki

• rand
• shuffle
• uniques
• removeByValue
• removeValues
• sortDescending
• sortAscending

File path: scripts/config/msu/array.nut

Functions related to interacting with and manipulating an array.

::MSU.Array.rand( _array, _start = null, _end = null );
// _array is an array
// _start is the start index of the range, inclusive
// _end is the end index of the range, exclusive

Returns a random element from _array within the range specified by the optional parameters _start and _end which both default to null.
For empty arrays, returns null if both _start and _end are null, otherwise throws an exception.
If _start is null, the range starts at 0. If _start is negative, the range starts at _array.len() + _start inclusive.
If _end is null, then the range ends at _array.len() exclusive.
If _end is negative, then the range ends at _array.len() + _end exclusive.

::MSU.Array.shuffle( _array );
// _array is an array

Efficiently shuffles the _array in place. Does not return the array as it is passed by reference.

::MSU.Array.uniques( _array );
// _array is an array

Returns a new array which contains only unique values from _array.

::MSU.Array.removeByValue( _array, _item );
// _array is an array
// _item can be any data type

Removes the first element in the array which is equal to _item and returns it. Returns null if no such element could be found. For example:

local idx = myArray.find(myItem);
if (idx != null) myArray.remove(idx);

// Instead of writing the above code, you can write the following

::MSU.Array.removeByValue(myArray, myItem);

::MSU.Array.removeValues( _array, _values )
// _array is an array
// _values is an array

Removes every value from _array, in place, that exists in _values. Returns _array. This is different from using array.filter because it modifies and returns the original array by reference instead of returning a new array.

::MSU.Array.sortDescending( _array, _member = null)
// _array is an array
// _member is a key if _array contains tables

Sorts the _array in descending order in place. Does not return the array as it is passed by reference.
If _member is not null then it assumes that _array contains tables and will sort them based on the value of _member. If the value of _member is a function, sorts based on the return value of _member(). It must therefore be a function with no arguments.

::MSU.Array.sortAscending( _array, _member = null )
// _array is an array
// _member is a key if _array contains tables

Sorts the _array in ascending order in place. Does not return the array as it is passed by reference.
If _member is not null then it assumes that _array contains tables and will sort them based on the value of _member. If the value of _member is a function, sorts based on the return value of _member(). It must therefore be a function with no arguments.