///!!!

/// For examples see Tests.gml

///!!!

// See type-conversion API at the bottom of this file

///@function Array(*item1, *item2, ...)

///@description Constructor funcion for Array objects

///@param {any} *item

function Array() constructor {

content = [];

size = 0;

// Change these if you want to avoid crashes

// (it may or may not cause unexpected consequences)

#macro ARRAY_SHOW_ERROR true

#macro ARRAY_SHOW_WARNING true

__throw = function(err) {

if ARRAY_SHOW_ERROR {

throw err;

}

else if ARRAY_SHOW_WARNING {

show_debug_message("Array error: "+string(err))

}

}

///@function append(value, value2, ..)

///@description Adds (a) value(s) to the end of the array

///@param {any} value

static append = function(value) {

for(var i = 0; i < argument_count; ++i) {

var val = argument[i]

content[size] = val;

++size;

}

return self;

}

///@function add(value, value2, ..)

///@description Mirrors append() method

///@param {any} value

static add = function(value) {

for(var i = 0; i < argument_count; ++i) {

var val = argument[i]

content[size] = val;

++size;

}

return self;

}

///@function concat(other)

///@description Adds every element of the second array to this array

///@param {Array/array} other

static concat = function(_other) {

if(!is_Array(_other)) {

if is_array(_other) {

_other = array_to_Array(_other)

}

else {

__throw("TypeError: trying to concat "+typeof(_other)+" with Array");

return self;

}

}

for(var i = 0; i < _other.size; i++) {

append(_other.get(i));

}

return self;

}

///@function copy()

///@description Returns a copy of the array object

static copy = function() {

ans = new Array();

forEach(function(el) {

ans.append(el);

});

return ans;

}

///@function clear()

///@description clears an array object

static clear = function() {

content = [];

size = 0;

return self;

}

///@function remove(pos)

///@description removes the value at given position

///@param {real} pos

static remove = function(pos) {

if(pos < 0)

pos += size;

if(size == 0) {

__throw("Error: trying to remove value from an empty Array");

return self;

}

else if(pos < 0 or pos > size - 1) {

__throw( "Error: index "+string(pos)+" is out of range [0, "+string(size-1)+"]");

return self;

}

var part1 = slice(0, pos);

var part2 = slice(pos+1);

part1.concat(part2);

content = part1.content;

size--;

return self;

}

///@function empty()

///@description Returns true if the array is empty and false otherwise

static empty = function() {

return size == 0;

}

///@function equal(other)

///@description Returns true if arrays are equal and false otherwise

static equal = function(_other) {

if(!is_Array(_other)) {

__throw( "TypeError: trying to compare "+typeof(_other)+" with Array");

return false;

}

if(size != _other.size)

return false;

for(var i = 0; i < size; i++) {

var c1 = get(i);

var c2 = _other.get(i);

if(typeof(c1) != typeof(c2))

return false;

if(is_array(c1) and is_array(c2)) {

if(!array_equals(c1, c2))

return false;

}

else if(is_Array(c1) and is_Array(c2)) {

if(!c1.equal(c2))

return false;

}

else if c1 != c2

return false;

}

return true;

}

///@function exists(value)

///@description Returns true if the value exists in the array and false otherwise

static exists = function(_val) {

val = _val;

ans = false;

forEach(function(x, pos) {

if(x == val) {

ans = true;

return 1; //Break out of forEach()

}

});

return ans;

}

///@function filter(func)

///@description Loops through the array and passes each value into a function.

/// Returns a new array with only values, that returned true.

/// Function func gets (x, *pos) as input

/// Note: Clean function. Does not affect the original array!

///@param {function} func

static filter = function(_func) {

func = _func;

ans = new Array();

forEach(function(x, pos) {

if(func(x, pos))

ans.append(x);

});

//content = ans.content;

//return self;

return ans;

}

///@function find(value)

///@description finds a value and returns its position. -1 if not found

///@param {any} value

static find = function(_val) {

val = _val;

ans = -1;

forEach(function(x, pos) {

if(x == val) {

ans = pos;

return 1; //Break out of forEach()

}

});

return ans;

}

///@function findAll(value)

///@description finds all places a value appears and returns an Array with all the positions. empty set if not found

///@param {any} value

static findAll = function(_val) {

val = _val;

ans = new Array();

forEach(function(x, pos) {

if(x == val)

ans.append(pos);

});

return ans;

}

///@function first()

///@description Returns the first value of the array

static first = function() {

return get(0);

}

///@function forEach(func)

///@description Loops through the array and runs the function with each element as an argument

/// Function func gets (x, *pos) as arguments

/// Note: Loop will stop immediately if the function returns anything but zero or undefined

///@param {function} func(x, *pos)

static forEach = function(func) {

for(var i = 0; i < size; i++) {

var res = func(get(i), i)

if(!is_undefined(res) and res != 0) {

break;

}

}

return self;

}

///@function get(pos)

///@description Returns value at given pos

///@param {real} pos

static get = function(pos) {

if(pos < 0)

pos += size; //i.e. Array.get(-1) = Array.last()

if(size == 0) {

__throw( "Error: trying to achieve value from empty Array");

return undefined;

}

else if(pos < 0 or pos > size-1) {

__throw( "Error: index "+string(pos)+" is out of range [0, "+string(size-1)+"]");

return undefined;

}

return content[pos];

}

///@function insert(pos, value)

///@description inserts a value into the array at given position

///@param {real} pos

///@param {any} value

static insert = function(pos, value) {

if(pos < 0)

pos += size;

if(pos < 0 or (pos > size-1 and size != 0)) {

show_debug_message("Warning: trying to insert a value outside of the array. Use Array.set() or Array.append() instead");

return set(pos, value);

}

var part1 = slice(0, pos);

var part2 = slice(pos);

part1.append(value);

part1.concat(part2);

content = part1.content;

size++;

return self;

}

///@function join(separator)

///@description returns a string, containing all of the array values separated by 'sep'

///@tip to join part of the array, use array.slice().join()

///@param {string} separator

///@param {bool} show_bounds

static join = function(sep, show_bounds) {

if is_undefined(sep)

sep = ", "

if is_undefined(show_bounds)

show_bounds = true

_sep = sep

if show_bounds

str = "["

else

str = ""

forEach(function(el, i) {

str += string(el)

if(i < size-1)

str += _sep

})

if show_bounds

str += "]"

return str

}

///@function lambda(func)

///@description Loops through the array and applies the function to each element

///@param {function} func(x, *pos)

static lambda = function(func) {

for(var i = 0; i < size; i++) {

set(i, func(get(i), i) );

}

return self;

}

///@function last()

///@description Returns the last value of the array

static last = function() {

return get(-1);

}

///@function _max()

///@description Returns a maximum of the array. Only works with numbers

static _max = function() {

ans = get(0);

forEach(function(x) {

if(!is_numeric(x)) {

__throw( "TypeError: Trying to calculate maximum of "+typeof(x)+"");

ans = undefined;

return 1 // Break out of forEach()

}

if(x > ans)

ans = x;

});

return ans;

}

///@function _min()

///@description Returns a minimum of the array. Only works with numbers

static _min = function() {

ans = content[0];

forEach(function(x) {

if(!is_numeric(x)) {

__throw( "TypeError: Trying to calculate minimum of "+typeof(x)+"");

ans = undefined;

return 1

}

if(x < ans)

ans = x;

});

return ans;

}

///@function number(value)

///@description Returns the amount of elements equal to given value in the array

///@note IMPORTANT! Don't try to use this with data structures, as results may be unpredictable

/// (Use forEach() with your own logic instead)

///@param {any} value

static number = function(_val) {

val = _val;

ans = 0;

forEach(function(x, pos) {

if(x == val)

ans++;

});

return ans;

}

///@function pop()

///@description removes a value from the end of the array and returns it

static pop = function() {

ans = last();

if(empty()) {

__throw( "Error: trying to pop value from empty Array");

return undefined;

}

remove(-1);

return ans;

}

///@function popBack()

///@description removes a value from the beginning of the array and returns it

static popBack = function() {

ans = first();

remove(0);

return ans;

}

///@function push(value, value2, ..)

///@description Mirrors append() method

///@param {any} value

static push = function(value) {

for(var i = 0; i < argument_count; ++i) {

var val = argument[i]

content[size] = val;

++size;

}

return self;

}

///@function pushBack(value)

///@description inserts a value to the beginning of the array

///@param {any} value

static pushBack = function(val) {

insert(0, val);

}

///@function getRandom()

///@description Returns a random element from the array

static getRandom = function() {

var idx = irandom(size-1)

if empty() {

var ans = undefined

}

else {

var ans = get(idx)

}

return ans

}

///@function resize(size)

///@description resizes the array. Sizing up leads to filling the empty spots with zeros

///@param {real} size

static resize = function(size) {

if(size < 0) {

__throw( "Error: array size cannot be negative");

return self;

}

while(size < size) {

append(0);

}

while(size > size) {

pop();

}

return self;

}

///@function reverse()

///@description reverses the array, affecting it

static reverse = function() {

ans = new Array();

forEach(function(element, pos) {

ans.set(size-pos-1, element);

});

content = ans.content;

return self;

}

///@function reversed()

///@description Returns reversed version of the array, without affecting the original

static reversed = function() {

ans = new Array();

forEach(function(element, pos) {

ans.set(size-pos-1, element);

});

return ans;

}

///@function set(pos, value)

///@description sets value in the array at given index

///@param {real} pos

///@param {any} item

static set = function(pos, value) {

if(pos < 0)

pos += size;

if(pos > size-1)

size = pos+1;

content[pos] = value;

return self;

}

///@function slice(begin, end)

///@description Returns a slice from the array with given boundaries. If begin > end - returns reversed version

///@param {real} begin

///@param {real} end

static slice = function(_begin, _end) {

if(is_undefined(_begin))

_begin = 0;

if(is_undefined(_end))

_end = size;

ans = new Array();

if(_begin > _end) {

for(var i = _end; i < _begin; i++) {

ans.pushBack(content[i]);

}

}

else {

for(var i = _begin; i < _end; i++) {

ans.append(content[i]);

}

}

return ans;

}

///@function sort(func, *startpos, *endpos)

///@description Bubble sorts through the array in given range, comparing values using provided function.

///Function gets (a, b) as input and must return True if A has more priority than B and False otherwise.

///@example myarray.sort(function(a, b) { return a > b }) will sort 'myarray' in descending order

///@param {function} func

///@param {real} *startpos Default - 0

///@param {real} *endpos Default - size

static sort = function(compare, _begin, _end) {

if(is_undefined(_begin))

_begin = 0;

if(is_undefined(_end))

_end = size;

if(!is_numeric(_begin) or round(_begin) != _begin or !is_numeric(_end) or round(_end) != _end) {

__throw( "TypeError: sort boundaries must be integers");

return self;

}

for(var i = _begin; i < _end; i++) { // Bubble sort LUL

for(var j = i; j > _begin; j--) {

if(j > 0 and compare(get(j), get(j-1))) {

swap(j, j-1);

}

}

}

return self;

}

#macro SORT_ASCENDING (function(a, b) { return a < b })

#macro SORT_DESCENDING (function(a, b) { return a > b })

///@function sorted(func, *startpos, *endpos)

///@description Mirrors .sort() function, but doesn't affect the original Array

static sorted = function(compare, _begin, _end) {

var ans = copy() // self.copy()

return ans.sort(compare, _begin, _end)

}

///@function shuffle()

///@description shuffles the array (randomly replaces every element)

static shuffle = function() {

// Knuth shuffle implementation

for(var i = size-1; i > 0; --i) {

var j = irandom_range(0, i)

swap(i, j)

}

return self

}

///@function shuffled()

///@description clean version of .shuffle()

static shuffled = function() {

var ans = copy();

return ans.shuffle();

}

///@function sum()

///@description Returns the sum of all the elements of the array. concats strings.

///NOTE: Works only with strings or numbars and only if all the elements are the same type.

static sum = function() {

if(is_string(get(0)))

ans = "";

else if(is_numeric(get(0)))

ans = 0;

else {

__throw( "TypeError: trying to sum up elements, that aren't strings or reals");

return undefined;

}

forEach(function(el) {

if(typeof(el) != typeof(ans))

__throw( "TypeError: Array elements aren't the same type: got "+typeof(el)+", "+typeof(ans)+" expected.");

ans += el;

});

return ans;

}

///@function swap(pos1, pos2)

///@description swaps 2 values at given positions

///@param {real} pos1

///@param {real} pos2

static swap = function(pos1, pos2) {

var temp = get(pos1);

set(pos1, get(pos2));

set(pos2, temp);

return self;

}

///@function unique()

///@description Returns a copy of this Array object, deleting all duplicates

static unique = function() {

ans = new Array();

forEach(function(x) {

if(!ans.exists(x))

ans.append(x);

});

return ans;

}

for(var i = 0; i < argument_count; i++)

append(argument[i])

static toString = function() {

return self.join()

}

}

///@function Range(min, max, step)

///@function Range(min, max)

///@function Range(max)

///@description Returns a new Array object, containing numbers in certain range

function Range() : Array() constructor {

if argument_count > 1 {

var mi = argument[0];

var ma = argument[1];

}

else {

var mi = 0;

var ma = argument[0];

}

if argument_count > 2 {

var step = argument[2];

}

else {

var step = 1;

}

// Iterate!

if mi < ma // Normal

{

for(var i = mi; i <= ma; i += step) {

append(i);

}

}

else { // Reversed

for(var i = mi; i >= ma; i += step) {

append(i);

}

}

return self

}

///@function Iterator(arr)

///@description Constructs an iterator object to allow easier iteration through Array's

function Iterator(arr) constructor {

self.index = -1;

self.value = undefined;

self.array = arr

///@function next()

next = function() {

index++;

try {

value = array.get(index);

}

catch(e) {

value = undefined;

}

return value;

}

get = function() {

return value;

}

return self;

}

// Helper functions to convert between data types

///@function array_to_Array(array)

///@description Returns an instance of Array object with all the contents of an array

///@param {array} array

function array_to_Array(array) {

if(!is_array(array)) {

__throw( "TypeError: expected array, got "+typeof(array));

return undefined;

}

ans = new Array();

for(var i = 0; i < array_length(array); i++) {

ans.append(array[i]);

}

return ans;

}

///@function array_from_Array(Arr)

///@description Mirrors function Array_to_array()

///@param {Array} Arr

function array_from_Array(Arr) {

return Array_to_array(Arr)

}

///@function ds_list_to_Array(list)

///@description Returns an instance of Array object with all the contents of an array

///@param {real} list

function ds_list_to_Array(list) {

if(!ds_exists(list, ds_type_list)) {

__throw( "Error: ds_list with given index does not exist");

return undefined;

}

ans = new Array();

for(var i = 0; i < ds_list_size(list); i++) {

ans.append(list[| i]);

}

return ans;

}

///@function is_Array(Arr)

///@description Checks if a variable holds reference to an Array object

///@param {any} arr

function is_Array(Arr) {

return is_struct(Arr) and (instanceof(Arr) == "Array" or instanceof(Arr) == "Range");

}

///@function Array_to_array(Arr)

///@description Returns contents of an Array object in format of regular array

///@param {Array} Arr

function Array_to_array(Arr) {

if !is_Array(Arr) {

__throw("Error in function Array_to_array(): expected Array(), got "+typeof(Arr))

return undefined;

}

return Arr.content

}

///@function ds_list_from_Array(Arr)

///@description Returns contents of an Array object in format of ds_list

///@param {Array} Arr

function ds_list_from_Array(Arr) {

if !is_Array(Arr) {

__throw("Error in function ds_list_from_Array(): expected Array(), got "+typeof(Arr))

return undefined;

}

_list = ds_list_create()

Arr.forEach(function(item) {

ds_list_add(_list, item)

})

return _list

}

///@function Array_to_ds_list(Arr)

///@description Mirrors function ds_list_from_Array()

///@param {Array} Arr

function Array_to_ds_list(Arr) {

return ds_list_from_Array(Arr)

}

///@function ds_list_to_array(ds_list)

///@description IMPORTANT: Used for native gm arrays, not Array Class!!!

// use ds_list_to_Array() for Array Class support

///@param {real} ds_list

function ds_list_to_array(_list) {

var arr = []

// ah yes, performance

for(var i = ds_list_size(_list) - 1; i >= 0; --i) {

arr[i] = _list[| i]

}

return arr

}

///@function ds_list_from_array(gm_array)

///@description IMPORTANT: Used for native gm arrays, not Array Class!!!

// use ds_list_from_Array() for Array Class support

///@param {array} arr

function ds_list_from_array(arr) {

var _list = ds_list_create()

for(var i = array_length(arr) - 1; i >= 0; --i) {

_list[| i] = arr[i]

}

return _list

}

///@function array_to_ds_list(gm_array)

///@description IMPORTANT: Used for native gm arrays, not Array Class!!!

// use ds_list_from_Array() for Array Class support

///@param {array} arr

function array_to_ds_list(arr) {

return ds_list_from_array(arr)

}