/*
Webmonkey Array Enhancements

JavaScript 1.2, which only works in Netscape 
4.0, adds several fundamental methods to the 
array object. A few of these very useful 
methods are included here in a form that 
can be used by 3.0 browsers.

Source: Webmonkey Code Library
(http://www.hotwired.com/webmonkey/javascript/code_library/)

Author: Thau!
Author Email: thau@wired.com
*/

// copy
//
// Copies the contents of an array into a temp 
// array and returns the copy.
//
// It doesn't alter the original array, but be 
// careful if the array contains references to 
// objects instead of just strings or numbers. 
// References to objects will be copied as 
// references. This means that if you change 
// an object in the original array, it will 
// also be changed in the new array.
//
function Array_Copy()
{
  var loop;
  var temp_array = new Array();
  for (loop = 0; loop < this.length; loop++)
  {
    temp_array[loop] = this[loop];
  }
  return temp_array;
}

Array.prototype.copy = Array_Copy;

// pop
//
// Removes the last element of an array and 
// returns that element. 
//
function Array_Pop()
{
  var last_item = this[this.length-1];
  this.length--;
  return last_item;
}

Array.prototype.pop = Array_Pop;

// push
//
// Adds an element to the end of an array and 
// returns the new length of the array. This 
// method changes the length of the array. 
//
function Array_Push(the_item)
{
  this[this.length] = the_item;
  return this.length;
}

Array.prototype.push = Array_Push;

// push distinct
//
// Adds an element to the end of an array and 
// returns the new length of the array. This 
// method changes the length of the array. 
//
function Array_PushDistinct(the_item)
{
  if (!this.exists(the_item))
    this[this.length] = the_item;
  return this.length;
}

Array.prototype.pushDistinct = Array_PushDistinct;

function Array_Join(delim)
{
  var xstr = "";
  for (loop = 0; loop < this.length; loop++)
  {
    if (xstr == "")
      xstr = String(this[loop]);
    else
      xstr += delim + String(this[loop]);
  }
  return xstr;
}

Array.prototype.join = Array_Join;

// concat
//
// Joins two arrays and returns a new array. 
// It doesn't alter the original arrays, but be 
// careful if the arrays contain references to 
// objects instead of just strings or numbers. 
// References to objects will be copied as 
// references. This means that if you change 
// an object in the original arrays, it will 
// also be changed in the new array.
//
function Array_Concat(second_array)
{
  var first_array = this.copy();
  
  for (loop = 0; loop<second_array.length; loop++)
  {
    first_array[first_array.length] = second_array[loop];
  }
  return first_array;
}

Array.prototype.concat = Array_Concat;

// shift
//
// Removes the first element of an array and 
// returns that element.
//
function Array_Shift()
{
  var new_value = this[0];
  var orig_length = this.length;
  for (loop = 0; loop<this.length-1; loop++)
  {
    this[loop] = this[loop+1];
  }
  this.length--;
  return new_value;
}

//Array.prototype.shift = Array_Shift;

// unshift
//
// Adds an element to the beginning of an array and 
// returns the new length of the array.
//
function Array_Unshift(the_item)
{
  for (loop = this.length-1 ; loop >= 0; loop--)
  {
    this[loop+1] = this[loop];
  }
  this[0] = the_item;
  return this.length;
}

Array.prototype.unshift = Array_Unshift;

// permute
//
// Randomly reorders the elements of an 
// array and returns the new, reordered array. 
// The original array remains unchanged.
// 
function Array_Permute(the_array)
{

  var temp_array = this.copy();
  var new_array = new Array();
  var random_num = 0;
  for (loop = 0; loop < this.length; loop++)
  {
    random_num = Math.round(Math.random() * (temp_array.length-1));
    new_array[loop] = temp_array[random_num];
    temp_array[random_num] = temp_array[temp_array.length-1];
    temp_array.length--;
  }
  return new_array;
}

Array.prototype.permute = Array_Permute;

// AAL addons from here down

// find
//
// Returns the location of an item in an array or -1 if not found

function Array_Find(the_item)
{
  var pos=0;

  for (pos=0; pos<this.length; pos++)
    if (this[pos]==the_item)
      return pos;

  return -1;
}

Array.prototype.find = Array_Find;

// exists
//
// Returns true if an item exists in an array and false if not

function Array_Exists(the_item)
{
  if (this.find(the_item)>-1)
    return true;
  else
    return false;
}

Array.prototype.exists = Array_Exists;

// remove
//
// Removes the element at the passed index in the array and returns it
// Shifts the rest of the array to close the gap

function Array_Remove(idx)
{
  var new_value = this[idx];
  for (loop = idx; loop<this.length-1; loop++)
  {
    this[loop] = this[loop+1];
  }
  this.length--;
  return new_value;
}

Array.prototype.remove = Array_Remove;

// remove
//
// Removes the element from the array
// Shifts the rest of the array to close the gap
// 
// Returns index of item removed.  (-1 if no item was removed)

function Array_RemoveItem(the_item)
{
  var idx;

  idx = this.find(the_item);
  if (idx>-1) {
    this.remove(idx);
  }
  return idx;
}

Array.prototype.removeItem = Array_RemoveItem;