Array Extensions

NinJa extends the base Array object found in JavaScript and adds a lot of the same functionality we've all grown to love about the List object in .NET. As always, there is full Intellisense for arrays. The old functions remain, but new functions have been added along with wrapper functions with .Net naming (like .Add instead of .push for adding items).

Adding and Removing Items

Adding and removing items is pretty easy. Use the following functions to manipulate an array:

• Add(object) - Adds an item to the end of the array.
• Remove(object) -Removes an item from the array.
• Clear() - Removes all items from the array.
• Insert(index, object) - Inserts an item at the given index.
• RemoveAt(index) - Removes the item at the given index.
• AddRange(array) - Adds the array of items to the end of the array.
• RemoveRange(array) - Removes all of the items in the given array from the array.
• Move(object, index) - Moves the object, if found, to the given index.
• Swap(object1, object2) - Swaps the positions of the two objects.
• ShiftLeft(index) - Effectively swaps the item with the one found before it.
• ShiftRight(index) - Effectively swaps the item with the one found after it.
• Copy() - Creates a copy of the array.

That's a lot of functions for just manipulate arrays. There is one other way to create an array:

• Array.From(object) - Takes an indexable object (contains .length and can use numeric indexing) and converts it into an array. A great example is using document.getElementsByTagName("tag"). This returns a specialized item that looks like an array, but items can be added and removed in real time by the dom and cause issues when traversing the array. Using Array.From(document.getElementsByTagName("tag")) will ensure that an array will be returned and be iterationally safe.

Speaking of iterations, there are two functions added that allows you to execute the same code on each item in an array:

• ForEach(function) - Calls the given function passing in an item in the array as the only parameter.
• ForEachReversed(function) - Calls the given function passing in an item in the array as the only parameter in reversed index order.

When using iteration functions, the this keyword will refer to the calling object, that is, the array itself. 

Iterating Arrays

Using the ForEach and ForEachReversed functions can be pretty handy, so here's a few things you need to know.

First, the function operates on a copy of the array. So if you modify the array in anyway, the iteration won't be affected as it's using the state of the array at the time the iteration function started.

Second, the first parameter passed to the function is the item at the current index. The second parameter is of the type IterationEventArgs. This is a special class containing information about the current iteration. There are advanced fields in this that can be used to traverse the array.

Iteration Control & IterationEventArgs

IterationEventArgs contains the following fields:

• CancelEvent -  If set to true, the iteration will break.
• Index - The current numerical index in the iteration.
• Object - The current item in the iteration. Same as the first parameter passed into the function.
• Sender - The array that's being iterated on.
• Navigate - This can be used to tell the iterator to go forward or backward in the index. A negative number will go back, a positive number will go forward.

Here's an example code where we remove all the strings in an array.

$Table("datagrid").Rows.ForEach(function(i, e){
    i.BackgroundColor(Colors.LightBlue);
    e.Navigate = 1;
});

This code snippet will give every other row in the table a light blue background color. It's yet another useless example that perfectly illustrates the power of navigating the ForEach and ForEachReversed iteration functions.

Searching Arrays

Three functions are provided for Arrays that allow you to search them for specific objects:

• Contains(object) - Returns whether the array contains the object.
• IndexOf(object) - Returns the index of the object in the array. If it's not found, -1 is returned.
• Find(function) - The array is iterated through much like ForEach with the function provided being called. Whenever the provided function returns true, the object in the current iteration is returned. If true is never returned, bull is returned.
• FindAll(function) - The array is iterated like with Find, except all objects in which the function returns true for are returned in an array. If no objects return true, an empty array is returned.