11.7.3.1. The push( ) method

arrayName.push(item1, item2,...itemn);

where item1, item2,...itemn are a comma-separated list of items to be appended to the end of the array as new elements. Here are some examples:

// Create an array with two elements
var menuItems = ["home", "quit"];

// Add an element
// menuItems becomes ["home", "quit", "products"]
menuItems.push("products");   

// Add two more elements
// menuItems becomes ["home", "quit", "products", "services", "contact"]
menuItems.push("services", "contact");

When invoked with no arguments, push( ) appends an empty element:

menuItems.push( );  // Increase array length by one

// Same as
menuItems.length++;

The push( ) method returns the new length of the updated array:

var myList = [12, 23, 98];
trace(myList.push(28, 36));  // Appends 28 and 36 to myList, and displays: 5

Note that the items added to a list can be any expression. The expression is resolved before being added to the list:

var temperature = 22;
var sky = "sunny";
var weatherListing = new Array( );
weatherListing.push(temperature, sky);
trace (weatherListing); // Displays: "22,sunny", not "temperature,sky"

Pushing, Popping, and Stacks The push( ) method takes its name from a programming concept called a stack. A stack can be thought of as a vertical array, like a stack of dishes. If you frequent cafeterias or restaurants with buffets, you'll be familiar with the spring-loaded racks that hold plates for the diners. When clean dishes are added, they are literally pushed onto the top of the stack and the older dishes sink lower into the rack. When a customer pops a dish from the stack, he is removing the dish that was most recently pushed onto the stack. This is known as a last-in-first-out (LIFO) stack and is typically used for things like history lists. For example, if you hit the Back button in your browser, it will take you to the previous web page you visited. If you hit the Back button again, you'll be brought to the page before that, and so on. This is achieved by pushing the URL of each page you visit onto the stack and popping it off when the Back button is clicked. LIFO stacks can also be found in real life. The last person to check her luggage on an airplane usually receives her luggage first when the plane lands because the luggage is unloaded in the reverse order from which it was loaded. The early bird who checked his luggage first is doomed to wait the longest at the luggage conveyor belt after the plane lands. A first-in-first-out (FIFO) stack is more egalitarian -- it works on a first-come-first-served basis. A FIFO stack is like the line at your local bank. Instead of taking the last element in an array, a FIFO stack deals with the first element in an array next. It then deletes the first element in the array and all the other elements "move up," just as you move up in line when the person in front of you is deleted (i.e., she is either served and then leaves, or chooses to leave in disgust because she is tired of waiting). Therefore, the word push generally implies that you are using a LIFO stack, whereas the word append implies that you are using a FIFO stack. In either case, elements are added to the "end" of the stack; the difference lies in from which end of the array the element for the next operation is taken.

11.7.3.2. The unshift( ) method

arrayName.unshift(item1, item2,...itemn);

where item1, item2,...itemn are a comma-separated list of items to be added to the beginning of the array as new elements. Note that multiple items are added in the order that they were supplied. Here are some examples:

var flashVersions = new Array( );
flashVersions[0] = 5;
flashVersions.unshift(4);    // flashVersions is now [4, 5]
flashVersions.unshift(2,3);  // flashVersions is now [2, 3, 4, 5]

The unshift( ) method, like push( ), returns the new length of the array being enlarged.

11.7.3.3. The splice( ) method

arrayName.splice(startIndex, deleteCount, item1, item2,...itemn)

where startIndex is a number that specifies the index at which element removal and optional insertion should commence (remember that the first element's index is 0); deleteCount is an optional argument that dictates how many elements should be removed (including the element at startIndex). When deleteCount is omitted, every element after and including startIndex is removed. The optional parameters item1, item2,...itemn are a comma-separated list of items to be added to the array as elements starting at startIndex.

Another useful feature of splice( ) is that it returns an array of the elements it removes. Thus it can be used to extract a series of elements from an array:

myList = ["a", "b", "c", "d"];
trace(myList.splice(1, 2));  // Displays: "b, c"
                             // myList is now ["a", "d"]

11.7.3.4. The concat( ) method

origArray.concat(elementList)

The concat( ) method appends the elements contained in elementList, one by one, to the end of origArray and returns the result as a new array, leaving origArray untouched. Normally, we'll store the returned array in a variable. Here, simple numbers are used as the items to be added to the array:

var list1 = new Array(11, 12, 13);
var list2 = list1.concat(14, 15);  // list2 becomes [11, 12, 13, 14, 15]

In this example, we use concat( ) to combine two arrays:

var guests = ["Panda", "Dave"];
var registeredPlayers = ["Gray", "Doomtrooper", "TRK9"];
var allUsers = registeredPlayers.concat(guests);
// allUsers is now: ["Gray", "Doomtrooper", "TRK9", "Panda", "Dave"]

var allUsers = registeredPlayers.push(guests);

we'd have ended up with this nested array:

["Gray", "Shift", "TRK9", ["Panda", "Dave"]]

Furthermore, push( ) would have altered the registeredPlayers array, whereas concat( ) does not.

Note, however, that concat( ) does not break apart nested arrays (elements that are themselves arrays within the main array), as you can see from the following code:

var x = [1, 2, 3];
var y = [[5, 6], [7, 8]];
var z = x.concat(y);  // Result is [1, 2, 3, [5, 6], [7, 8]].
                      // Elements 0 and 1 of y were not "flattened."