Array
Module | ejs |
Namespace | intrinsic |
Definition | dynamic class Array |
Specified | Ecma-262. |
Inheritance | Array ![]() |
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
Qualifiers | Property | Type | Description |
---|---|---|---|
No properties defined |
Array Methods
Qualifiers | Method |
---|---|
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
Append an item to the array.
- Parameters
obj: Object Object to add to the array
- Returns
- The array itself.
- Specified
- Ejs-11.
Create a new array.
- Parameters
values: Array Initialization values. The constructor allows three forms: - Array()
- Array(size: Number)
- Array(elt: Object, ...args)
Clear an array.
- Description
- Remove all elements of the array.
- Specified
- Ejs-11.
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.
Compact an array.
- Description
- Remove all null elements.
- Specified
- Ejs-11.
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.
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.
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.
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.
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.
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.
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.
- Returns
- Returns a new array of transformed elements.
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.
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.
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.
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.
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.
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.
Get the length of an array.
- Returns
- The number of items in the array.
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
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
Remove and return the last value in the array.
- Returns
- The last element in the array. Returns undefined if the array is empty.
Append items to the end of the array.
- Parameters
items: Array Items to add to the array.
- Returns
- The new length of the 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.
Reverse the order of the objects in the array.
- Description
- The elements are reversed in the original array.
- Returns
- A reference to the array.
Remove and return the first element in the array.
- Returns
- The previous first element in the 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.
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.
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.
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.
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.
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.
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.
Insert the items at the front of the array.
- Parameters
items: Array to insert
- Returns
- Returns the array reference.