ECMA array

Introduction

This package is inspired by the ECMAScript's/JavaScript's Array object as well as professional frameworks like Lodash and Underscore. This little collection is by far not as complete as the professional solutions. Nevertheless, the most important methods are available and provide clear benefits compared to Matlab's primitive solutions like arrayfun.

Constructur

A new lib.ecma.array instance can be created in three ways

lib.ecma.array(value1, value2, ..., valueN)
lib.ecma.array([value1, value2, ..., valueN])
lib.ecma.array({value1, value2, ..., valueN})

The input arguments are optional.

• If no arguments are passed an empty lib.ecma.array is returned.
• If only one argument is passed and it is either a cell or an array then that argument is going to be spread. Thus the above three lines are identical.

return: lib.ecma.array

NOTE: Passing a single char array, e.g. 'foobar', will be spread. To prevent spreading wrap it in a cell.

lib.ecma.array('foobar') // length -> 6
lib.ecma.array({'foobar'}) // length -> 1

Properties

data

Contains the array values.

return: cell

length

Returns the length of the lib.ecma.array instance. Property is dependent and read-only.

return: double

example

arr = lib.ecma.array('foo', 'bar', 42);
arr.length // -> 3

Methods

save(obj, path)

Saves data into a mat-file located at 'path. The mat-file will contain a variable elm of type cell containing the array values.

return: lib.ecma.array

load(obj, path)

Loads data from a mat-file located at path. The mat-file must contain a variable elm of type cell containing the array values.

NOTE: this function alters the object.

return: lib.ecma.array

push(value1, value2, ..., valueN)

Add the new entry value at the end of the array.

• If no argument is passed, then the array is not affected.
• If only one argument is passed and it is either a cell or an array then that argument is going to be spread.

return: lib.ecma.array

NOTE: this function alters the object.

sort(callback, dim)

Sorts the array according to the return value of callback, a mapping function (obj, id, array) => {...}. dim is an optional parameter and tells along which dimension the array should be sorted if lib.ecma.array is a multi-dimensional array then.

return: lib.ecma.array

NOTE: this function alters the object.

reverse()

This function reverses simply the order of elements stored in the array.

return: lib.ecma.array

NOTE: this function alters the object.

indexOf(callback | element)

Returns the id of the first match of element. In case of a callback function, i.e. function_handle, of the type (obj, id, array) => {...} which returns a booloan (true or false) then indexOf returns the id of the first match. It is a match when the given callback function returns true.

return: double

Supported are shorthands for char arrays and double.

arr = lib.ecma.array(42,'foobar')

arr.find(42)
// -> 1

arr.find('foobar')
// -> 2

find(callback)

Returns the first match of element for callback function of the type (obj, id, array) => {...} which returns a booloan (true or false). It is a match when the given callback function returns true.

return: first match of any type

min(callback)

Returns the element for which callback, a mapping function (obj, id, array) => {...}, returns the minimal value. A second output is the index of the match.

return: (1) best match of any type, (2) index of element

example

arr = lib.ecma.array('foobar', 'foo', 'a couple of words')

[elm, id] = arr.min(@numel) // return element with the least characters.
// -> elm: 'foo'
// -> id: 2

every(callback)

Checks every element with the callback function of the type (obj, id, array) => logical. Returns true if all elements pass the check. Otherwise false is returned.

return: logical

some(callback)

Checks every element with the callback function of the type (obj, id, array) => logical. Returns true if at least one element passes the check. Otherwise false is returned if no element passes the check.

return: logical

slice(start, end)

Slices the array from start-index till the end-index and returns a new instance of lib.ecma.array which contains the sliced elements.

• The optional parameter end (default: array length) tells where to stop slicing
• The optional parameter start (default: 1) tells where to start.
• If no arguments are passed a copy of the array is returned

return: lib.ecma.array

pick(id1, id2, ..., idN)

Picks the elements of given ids (in given order) and return a new array containing these elements.

• If no arguments are passed an empty array is returned.

return: lib.ecma.array

filter(callback)

Checks every element with the callback function of the type (obj, id, array) => logical and returns a new instance of lib.ecma.array containing all elements which passes the callback check.

return: lib.ecma.array

exclude(callback)

Checks every element with the callback function of the type (obj, id, array) => logical and returns a new instance of lib.ecma.array containing all elements of the original array except those which passes the callback check.

return: lib.ecma.array

map(callback)

Converts every element with the callback function of the type (obj, id, array) => {...} and returns a new instance of lib.ecma.array with the same amount and order of elements containing the mapped elements.

return: lib.ecma.array

forEach(callback)

Loops over the whole array and calls for each element the callback function of the type (obj, id, array) => logical.

return: lib.ecma.array

forLoop(ids, callback)

Loops over the ids-array and calls for each element the callback function of the type (obj, id, array) => logical.

return: lib.ecma.array

join(delimiter)

Converts all elements to a string if possible and joins them with a delimiter.

return: char

reduce(reducer, initialValue)

The reduce() method executes a reducer function (that you provide) on each member of the array resulting in a single output value.

The reducer function takes two arguments:

• Accumulator
• Current Value

initialValue is optional and is the value to use as the first argument to the first call of the callback. If no initial value is supplied, the first element in the array will be used.

Calling reduce() on an empty array without an initial value is an error.

The reducer function's returned value is assigned to the accumulator, whose value is remembered across each iteration throughout the array and ultimately becomes the final, single resulting value.

accumulate(callback)

Like map but returns a native array. It is supposed to be used in cases where the values are needed directly in stead of an array wrapping them. Hence, accumulate is a shorthand for

mappedArray = Array.map(...);
values = [mappedArray.data{:}];

With accumulate it becomes

values = Array.accumulate(...);