Array

Moduleejs
Definitiondynamic class Array
InheritanceArray inherit Object
StabilityEvolving.

Arrays provide a growable, integer indexed, in-memory store for objects.

An array can be treated as a stack (FIFO or LIFO) or a list (ordered). Insertions can be done at the beginning or end of the stack or at an indexed location within a list.


Properties

QualifiersPropertyTypeDescription
public set length Set the length of an array. The array will be truncated if required. If the new length is greater then the old length, new elements will be created as required and set to undefined. If the new length is less than 0 the length is set to zero.

Array Methods

QualifiersMethod
public append(obj: Object): Array
 Append an item to the array.
Array(values: Array)
 Create a new array.
public clear(): Void
 Clear an array.
public override clone(deep: Boolean = true): Array
 Clone the array and all its elements.
public compact(): Array
 Compact an array.
public concat(args: Array): Array
 Concatenate the supplied elements with the array to create a new array.
public contains(element: Object): Boolean
 See if the array contains an element using strict equality "===".
public every(match: Function): Boolean
 Determine if all elements match.
public filter(match: Function): Array
 Find all matching elements.
public find(match: Function): Object
 Find the first matching element.
public findAll(match: Function): Array
 Find all matching elements.
public forEach(modifier: Function): Array
 Transform all elements.
iterator override get(): Iterator
 Iterator for this array to be used by "for (v in array)".
iterator override getValues(): Iterator
 Iterator for this array to be used by "for each (v in array)".
public indexOf(element: Object, startIndex: Number = 0): Number
 Search for an item using strict equality "===".
public insert(pos: Number, args: Array): Array
 Insert elements.
public join(sep: String = undefined): String
 Convert the array into a string.
public lastIndexOf(element: Object, startIndex: Number = 0): Number
 Find an item searching from the end of the array.
public map(mapper: Function): Array
 Call the mapper on each array element in increasing index order and return a new array with the values returned from the mapper.
public pop(): Object
 Remove and return the last value in the array.
public push(items: Array): Number
 Append items to the end of the array.
public reject(match: Function): Array
 Find non-matching elements.
public remove(start: Number, end: Number = -1): Void
 Remove elements.
public reverse(): Array
 Reverse the order of the objects in the array.
public shift(): Object
 Remove and return the first element in the array.
public slice(start: Number, end: Number = -1 , step: Number = 1): Array
 Create a new array subset by taking a slice from an array.
public some(match: Function): Boolean
 Determine if some elements match.
public sort(compare: Function = null , order: Number = 1): Array
 Sort the array.
public splice(start: Number, deleteCount: Number, values: Array): Array
 Insert, remove or replace array elements.
public override toString(): String
 Convert the array to a single string each member of the array has toString called on it and the resulting strings are concatenated.
public transform(mapper: Function): Void
 Transform all elements.
public unique(): Array
 Remove duplicate elements and make the array unique.
public unshift(items: Array): Array
 Insert the items at the front of the array.

Method Detail

public append(obj: Object): Array

Append an item to the array.

Parameters
obj: Object Object to add to the array.
Returns
The array itself.
Specified
ejscript-1.1

public Array(values: Array)

Create a new array.

Parameters
values: Array Initialization values. The constructor allows three forms:
  • Array()
  • Array(size: Number)
  • Array(elt: Object, ...args)

public clear(): Void

Clear an array.

Description
Remove all elements of the array.
Specified
ejscript-1.1

override public clone(deep: Boolean = true): Array

Clone the array and all its elements.

Parameters
deep: Boolean If true, do a deep copy where all object references are also copied, and so on, recursively. [default: true]
Specified
ejscript-1.1

public compact(): Array

Compact an array.

Description
Remove all null elements.
Specified
ejscript-1.1

public concat(args: Array): Array

Concatenate the supplied elements with the array to create a new array.

Description
If any arguments specify an array, their elements are concatenated. This is a one level deep copy.
Parameters
args: Array A variable length set of values of any data type.
Returns
A new array of the combined elements.

public contains(element: Object): Boolean

See if the array contains an element using strict equality "===".

Description
This call searches from the start of the array for the specified element.
Parameters
element: Object The object to search for.
Returns
True if the element is found. Otherwise false.
Specified
ejscript-1.1

public every(match: Function): Boolean

Determine if all elements match.

Description
Iterate over every element in the array and determine if the matching function is true for all elements. This method is lazy and will cease iterating when an unsuccessful match is found. The checker is called with the following signature: function match(element: Object, elementIndex: Number, arr: Array): Boolean.
Parameters
match: Function Matching function.
Returns
True if the match function always returns true.

public filter(match: Function): Array

Find all matching elements.

Description
Iterate over all elements in the object and find all elements for which the matching function is true. The match is called with the following signature: function match(element: Object, elementIndex: Number, arr: Array): Boolean This method is identical to the.
Parameters
match: Function Matching function.
Returns
Returns a new array containing all matching elements.

public find(match: Function): Object

Find the first matching element.

Description
Iterate over elements in the object and select the first element for which the matching function is true. The matching function is called with the following signature: function match(element: Object, elementIndex: Number, arr: Array): Boolean.
Parameters
match: Function Matching function.
Returns
The matched item.
Specified
ejscript-1.1

public findAll(match: Function): Array

Find all matching elements.

Description
Iterate over all elements in the object and find all elements for which the matching function is true. The matching function is called with the following signature: function match(element: Object, elementIndex: Number, arr: Array): Boolean.
Parameters
match: Function Matching function.
Returns
Returns an array containing all matching elements.
Specified
ejscript-1.1

public forEach(modifier: Function): Array

Transform all elements.

Description
Iterate over the elements in the array and transform all elements by applying the transform function. The matching function is called with the following signature: function match(element: Object, elementIndex: Number, arr: Array): Boolean This method is identical to the.
Parameters
modifier: Function Transforming function.
Returns
Returns the original (transformed) array.

override iterator get(): Iterator

Iterator for this array to be used by "for (v in array)".


override iterator getValues(): Iterator

Iterator for this array to be used by "for each (v in array)".


public indexOf(element: Object, startIndex: Number = 0): Number

Search for an item using strict equality "===".

Description
This call searches from the start of the array for the specified element.
Parameters
element: Object The object to search for.
startIndex: Number Where in the array to start searching for the object (Defaults to zero). If the index is negative, it is taken as an offset from the end of the array. If the calculated index is less than zero the entire array is searched. If the index is greater than the length of the array, -1 is returned. [default: 0]
Returns
The items index into the array if found, otherwise -1.

public insert(pos: Number, args: Array): Array

Insert elements.

Description
Insert elements at the specified position. The insertion occurs before the element at the specified position. Negative indicies will measure from the end so that -1 will specify the last element. Indicies greater than the array length will append to the end. Indicies before the first position will insert at the start.
Parameters
pos: Number Where in the array to insert the objects.
args: Array Arguments are aggregated and passed to the method in an array.
Returns
The original array.
Specified
ejscript-1.1

public join(sep: String = undefined): String

Convert the array into a string.

Description
Joins the elements in the array into a single string by converting each element to a string and then concatenating the strings inserting a separator between each.
Parameters
sep: String Element separator. [default: undefined]
Returns
A string.

public lastIndexOf(element: Object, startIndex: Number = 0): Number

Find an item searching from the end of the array.

Description
Search for an item using strict equality "===". This call searches from the end of the array for the given element.
Parameters
element: Object The object to search for.
startIndex: Number Where in the array to start searching for the object (Defaults to the array's length). If the index is negative, it is taken as an offset from the end of the array. If the calculated index is less than zero, -1 is returned. If the index is greater or equal to the length of the array, the whole array will be searched. [default: 0]
Returns
The items index into the array if found, otherwise -1.

public map(mapper: Function): Array

Call the mapper on each array element in increasing index order and return a new array with the values returned from the mapper.

Description
The mapper function is called with the following signature: function mapper(element: Object, elementIndex: Number, arr: Array): Object.
Parameters
mapper: Function Transforming function.

public pop(): Object

Remove and return the last value in the array.

Returns
The last element in the array. Returns undefined if the array is empty.

public push(items: Array): Number

Append items to the end of the array.

Parameters
items: Array Items to add to the array.
Returns
The new length of the array.

public reject(match: Function): Array

Find non-matching elements.

Description
Iterate over all elements in the array and select all elements for which the filter function returns false. The matching function is called with the following signature:

function match(element: Object, elementIndex: Number, arr: Array): Boolean.
Parameters
match: Function Matching function.
Returns
A new array of non-matching elements.
Specified
ejscript-1.1

public remove(start: Number, end: Number = -1): Void

Remove elements.

Description
Remove the elements from start to end inclusive. The elements are removed and not just set to undefined as the delete operator will do. Indicies are renumbered. NOTE: this routine delegates to splice.
Parameters
start: Number Numeric index of the first element to remove. Negative indices measure from the end of the array. -1 is the last element.
end: Number Numeric index of the last element to remove. [default: -1]
Specified
ejscript-1.1

public reverse(): Array

Reverse the order of the objects in the array.

Description
The elements are reversed in the original array.
Returns
A reference to the array.

public shift(): Object

Remove and return the first element in the array.

Returns
The previous first element in the array.

public slice(start: Number, end: Number = -1 , step: Number = 1): Array

Create a new array subset by taking a slice from an array.

Parameters
start: Number The array index at which to begin. Negative indicies will measure from the end so that -1 will specify the last element. If start is greater than or equal to end, the call returns an empty array.
end: Number The array index at which to end. This is one beyond the index of the last element to extract. If end is negative, it is measured from the end of the array, so use -1 to mean up to but not including the last element of the array. [default: -1 ]
step: Number Slice every step (nth) element. If the step value is negative, the copying begins at the start index down to the (and not including) the end index. [default: 1]
Returns
A new array that is a subset of the original array.

public some(match: Function): Boolean

Determine if some elements match.

Description
Iterate over all element in the array and determine if the matching function is true for at least one element. This method is lazy and will cease iterating when a successful match is found. The match function is called with the following signature: function match(element: Object, elementIndex: Number, arr: Array): Boolean.
Parameters
match: Function Matching function.
Returns
True if the match function ever is true.

public sort(compare: Function = null , order: Number = 1): Array

Sort the array.

Description
The array is sorted in lexical order. A compare function may be supplied.
Parameters
compare: Function Function to use to compare. A null comparator will use a text compare. [default: null ]
order: Number If order is >= 0, then an ascending lexical order is used. Otherwise descending. [default: 1]
Returns
The sorted array reference type Comparator = (function (*,,*)): AnyNumber | undefined).
Specified
ejs added the order argument.

public splice(start: Number, deleteCount: Number, values: Array): Array

Insert, remove or replace array elements.

Description
Splice modifies an array in place.
Parameters
start: Number The array index at which the insertion or deleteion will begin. Negative indicies will measure from the end so that -1 will specify the last element.
deleteCount: Number Number of elements to delete. If omitted, splice will delete all elements from the start argument to the end.
values: Array The array elements to add.
Returns
Array containing the removed elements.

override public toString(): String

Convert the array to a single string each member of the array has toString called on it and the resulting strings are concatenated.

Returns
A string.

public transform(mapper: Function): Void

Transform all elements.

Description
Iterate over all elements in the object and transform the elements by applying the transform function. This modifies the object elements in-situ. The transform function is called with the following signature: function mapper(element: Object, elementIndex: Number, arr: Array): Object.
Parameters
mapper: Function Transforming function.
Specified
ejscript-1.1

public unique(): Array

Remove duplicate elements and make the array unique.

Description
Duplicates are detected by using "==" (ie. content equality, not strict equality).
Returns
The original array with unique elements.
Specified
ejscript-1.1

public unshift(items: Array): Array

Insert the items at the front of the array.

Parameters
items: Array To insert.
Returns
Returns the array reference.