Array

Moduleejs
Namespaceintrinsic
Definitiondynamic class Array
SpecifiedEcma-262.
InheritanceArray inherit Object

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
No properties defined

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): 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, thisObj: Object): Void
 Transform all elements.
iterator override get(deep: Boolean): Iterator
 Get an iterator for this array to be used by "for (v in array)".
iterator override getValues(deep: Boolean): Iterator
 Get an iterator for this array to be used by "for each (v in array)".
public indexOf(element: Object, startIndex: Number): Number
 Search for an item using strict equality "===".
public insert(pos: Number, args: Array): Array
 Insert elements.
public join(sep: String): String
 Convert the array into a string.
public lastIndexOf(element: Object, fromIndex: Number): Number
 Find an item searching from the end of the arry.
public override get length(): Number
 Get the length of an array.
public set length(value: Number): Void
 Set the length of an 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): Void
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, step: Number): 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, order: Number): Array
 Sort the array using the supplied compare function.
public splice(start: Number, deleteCount: Number, values: Array): Array
 Insert, remove or replace array elements.
public override toString(locale: String): 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): Object
 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
Ejs-11.

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
Ejs-11.

override public clone(deep: Boolean): 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
Ejs-11.

public compact(): Array

Compact an array.

Description
Remove all null elements.
Specified
Ejs-11.

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.

Throws

OutOfBoundsError: If the starting index is greater than or equal to the size of the array or less then 0.

Specified
Ejs-11.

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
ECMA function doing the Same as findAll. 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
True when the match function returns true.
Specified
Ejs-11.

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
Ejs-11.

public forEach(modifier: Function, thisObj: Object): Void

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
thisObj: Object
Returns
Returns a new array of transformed elements.

override iterator get(deep: Boolean): Iterator

Get an iterator for this array to be used by "for (v in array)".

Parameters
deep: Boolean Follow the prototype chain. Only implemented in ECMA compliance mode.. [default: false]
Returns
An iterator object.

override iterator getValues(deep: Boolean): Iterator

Get an iterator for this array to be used by "for each (v in array)".

Parameters
deep: Boolean Follow the prototype chain. Only implemented in ECMA compliance mode.. [default: false]
Returns
An iterator object.

public indexOf(element: Object, startIndex: Number): 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 (zero based) to start searching for the object.
Returns
The items index into the array if found, otherwise -1.

Throws

OutOfBoundsError: If the starting index is greater than or equal to the size of the array or less then 0.


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.
Parameters
pos: Number Where in the array to insert the objects.
Returns
The original array.

Throws

OutOfBoundsError: If the starting index is greater than or equal to the size of the array or less then 0.

Specified
Ejs-11.

public join(sep: String): 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, fromIndex: Number): Number

Find an item searching from the end of the arry.

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.
Returns
The items index into the array if found, otherwise -1.

Throws

OutOfBoundsError: If the starting index is greater than or equal to the size of the array or less then 0.


override get public length(): Number

Get the length of an array.

Returns
The number of items in the array.

set public length(value: Number): Void

Set the length of an array.

Description
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 0.
Parameters
value: Number The new length

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
Ejs-11.

public remove(start: Number, end: Number): Void

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, step: Number): 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.
end: Number One beyond the index of the last element to extract. The array index at which to begin. If end is negative, it is measured from the end of the array.
step: Number Slice every step (nth) element. The step value may be negative.
Returns
A new array that is a subset of the original array.

Throws

OutOfBoundsError: If the start or end are equal to or greater than the length of the array, or, if the start is greater than the end, or, either start or end is negative.


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. This method is identical to the ECMA.
Parameters
match: Function Matching function
Returns
True if the match function ever is true.

public sort(compare: Function, order: Number): Array

Sort the array using the supplied compare function.

Parameters
compare: Function Function to use to compare. A null comparator will use a text compare
order: Number If order is >= 0, then an ascending order is used. Otherwise descending.
Returns
The sorted array reference type Comparator = (function (*,,*)): AnyNumber | undefined).
Specified
Emca-4, ejs-11 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.

Throws

OutOfBoundsError: If the start is equal to or greater than the length of the array.


override public toString(locale: String): String

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

Parameters
locale: String
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
Specified
Ejs-11.

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
Ejs-11.

public unshift(items: Array): Object

Insert the items at the front of the array.

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