Array
| Module | ejs |
| Definition | dynamic class Array |
| Inheritance | Array  Object |
| Stability | Evolving. |
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 |
|---|---|---|---|
| get set | length | Number | Length of an array. |
Array Class Methods
| Qualifiers | Method |
|---|
Array Instance Methods
| Qualifiers | Method |
|---|---|
| Array(values: Array) | |
| Create a new array. | |
| append(obj: Object): Array | |
| Append an item to the array. | |
| clear(): Void | |
| Clear an array. | |
| override | clone(deep: Boolean = true): Array |
| Clone the array and all its elements. | |
| compact(): Array | |
| Compact an array. | |
| concat(args: Array): Array | |
| Concatenate the supplied elements with the array to create a new array. | |
| contains(element: Object): Boolean | |
| See if the array contains an element using strict equality "===". | |
| every(match: Function): Boolean | |
| Determine if all elements match. | |
| filter(match: Function): Array | |
| Find all matching elements. | |
| find(match: Function): Object | |
| Find the first matching element. | |
| findAll(match: Function): Array | |
| Find all matching elements. | |
| forEach(callback: Function, thisObj: Object = null): 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)". | |
| indexOf(element: Object, startIndex: Number = 0): Number | |
| Search for an item using strict equality "===". | |
| insert(pos: Number, args: Array): Array | |
| Insert elements. | |
| join(sep: String = ): String | |
| Convert the array into a string. | |
| lastIndexOf(element: Object, startIndex: Number = -1): Number | |
| Find an item searching from the end of the array. | |
| 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. | |
| pop(): Object | |
| Remove and return the last value in the array. | |
| push(items: Array): Number | |
| Append items to the end of the array. | |
| reduce(callback: Function, initial = null): Object | |
| Reduce array elements. | |
| reduceRight(callback: Function, initial = null): Object | |
| Reduce array elements. | |
| reject(match: Function): Array | |
| Find non-matching elements. | |
| remove(start: Number, end: Number = -1): Void | |
| Remove elements. | |
| removeElements(elts: Array): Array | |
| Remove specified elements from the array. | |
| reverse(): Array | |
| Reverse the order of the objects in the array. | |
| shift(): Object | |
| Remove and return the first element in the array. | |
| slice(start: Number, end: Number = -1, step: Number = 1): Array | |
| Create a new array subset by taking a slice from an array. | |
| some(match: Function): Boolean | |
| Determine if some elements match. | |
| sort(compare: Function = null, order: Number = 1): Array | |
| Sort the array. | |
| splice(start: Number, deleteCount: Number, values: Array): Array | |
| Insert, remove or replace array elements. | |
| 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. | |
| transform(mapper: Function): Array | |
| Transform all elements. | |
| unique(): Array | |
| Remove duplicate elements and make the array unique. | |
| unshift(items: Array): Array | |
| Insert the items at the front of the array. |
Method Detail
Array(values: Array)
- Description
- Create a new array.
- Parameters
values: Array Initialization values. The constructor allows three forms: - Array()
- Array(size: Number)
- Array(elt: Object, ...args)
- Description
- Append an item to the array.
- Parameters
obj: Object Object to add to the array.
- Returns
- The array itself.
- Specified
- ejscript-2.5
clear(): Void
- Description
- Clear an array. Remove all elements of the array.
- Specified
- ejs (
- Description
- 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]
- Returns
- A new array.
- Specified
- ejscript-2.5
compact(): Array
- Description
- Compact an array. Remove all null elements.
- Returns
- Modified original array.
- Specified
- ejscript-2.5
- Description
- Concatenate the supplied elements with the array to create a new array. 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.
- Description
- See if the array contains an element using strict equality "===". This call searches from the start of the array for the specified element. Note that some types are not interned like strings and so contains may return false if a different object with the same value is contained in the array. This can happen with Path types.
- Parameters
element: Object The object to search for.
- Returns
- True if the element is found. Otherwise false.
- Specified
- ejscript-2.5
- Description
- Determine if all elements match. 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. 8.
- Description
- Find all matching elements. 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.
- Description
- Find the first matching element. Iterate over elements in the object and select the first element for which the matching function returns 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-2.5
- Description
- Find all matching elements. 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-2.5
- Description
- Transform all elements. 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.
- Parameters
callback: Function Transforming function. thisObj: Object Object to use for the "this" value when invoking the callback. [default: null]
- Returns
- Returns the original (transformed) array.
override iterator get(): Iterator
- Description
- Iterator for this array to be used by "for (v in array)".
override iterator getValues(): Iterator
- Description
- Iterator for this array to be used by "for each (v in array)".
- Description
- Search for an item using strict equality "===". 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.
- Description
- Insert elements. 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-2.5
- Description
- Convert the array into a string. 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: ]
- Returns
- A string.
- Description
- Find an item searching from the end of the array. 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: -1]
- Returns
- The items index into the array if found, otherwise -1.
- Description
- Call the mapper on each array element in increasing index order and return a new array with the values returned from the mapper. The mapper function is called with the following signature: function mapper(element: Object, elementIndex: Number, arr: Array): Object.
- Parameters
mapper: Function Transforming function.
pop(): Object
- Description
- Remove and return the last value in the array.
- Returns
- The last element in the array. Returns undefined if the array is empty.
- Description
- Append items to the end of the array.
- Parameters
items: Array Items to add to the array.
- Returns
- The new length of the array.
- Description
- Reduce array elements. Apply a callback function against two values of the array and reduce to a single value. Traversal is from left to right. The first time the callback is called, previous will be set to the first value and current will be set to the second value. If an initial parameter is provided, then previous will be set to initial and current will be set to the first value. The callback is called with the following signature: function callback(previous, current, index: Number, array: Array): Object.
- Parameters
callback: Function Callback function. initial Initial value to use in the reduction. [default: null]
- Returns
- Returns a new array containing all matching elements.
- Description
- Reduce array elements. Apply a callback function against two values of the array and reduce to a single value. Traversal is from right to left. The first time the callback is called, previous will be set to the first value and current will be set to the second value. If an initial parameter is provided, then previous will be set to initial and current will be set to the first value. The callback is called with the following signature: function callback(previous, current, index: Number, array: Array): Object.
- Parameters
callback: Function Callback function. initial Initial value to use in the reduction. [default: null]
- Returns
- Returns a new array containing all matching elements.
- Description
- Find non-matching elements. 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-2.5
- Description
- Remove elements. 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-2.5
- Description
- Remove specified elements from the array. The elements are removed and not just set to undefined as the delete operator will do. Indicies are renumbered.
- Parameters
elts: Array List of elements to remove.
- Returns
- The original array.
- Specified
- ejscript-2.5
reverse(): Array
- Description
- Reverse the order of the objects in the array. The elements are reversed in the original array.
- Returns
- A reference to the array.
shift(): Object
- Description
- Remove and return the first element in the array.
- Returns
- The previous first element in the array. 0.
- Description
- 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. The step value may be negative. [default: 1]
- Returns
- A new array that is a subset of the original array.
- Description
- Determine if some elements match. 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.
- Description
- Sort the array. 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. The compare signature is: function comparator (array: Array, index1: Number, index2: Number): Number The comparison function should return 0 if the items are equal, -1 if the item at index1 is less and should return 1 otherwise. [default: null] order: Number If order is >= 0, then an ascending lexical order is used. Otherwise descending. [default: 1]
- Returns
- The sorted array reference.
- Specified
- ejs Added the order argument.
- Description
- Insert, remove or replace array elements. 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. X.
override toString(): String
- Description
- 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.
- Description
- Transform all elements. 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-2.5
unique(): Array
- Description
- Remove duplicate elements and make the array unique. Duplicates are detected by using "==" (ie. content equality, not strict equality).
- Returns
- The original array with unique elements.
- Specified
- ejscript-2.5
- Description
- Insert the items at the front of the array.
- Parameters
items: Array To insert.
- Returns
- Returns the array reference.