package com.hapticdata {
	
	import flash.utils.ByteArray;

	/**
	 * Adds extra methods to arrays for easier manipulation
	 * @class AdvArray 
	 * @author Kyle Phillips - <a href="http://www.haptic-data.com">http://www.haptic-data.com</a>
	 * @created Jun 29, 2008
	 */
	dynamic public class AdvArray extends Array {
		public function AdvArray(...args) {
			//this = this as Array;
			for each(var i:* in args)
			{
				super.push(i);
			}
			//super(...args);
		}
		
		 /**
		  * add an array to the end of the existing AdvArray
		  * @param a (Array) the array to append
		  * @return the new length of the array
		  */
		 public function append(a:Array):uint
		 {
		 	for(var i:uint=0;i<a.length;i++)
		 	{
		 		super.push(a[i]);
		 	}
		 	return super.length;
		 }
		 /**
		  * add an array at a given index of the existing AdvArray, defaults to the beginning of the array
		  * @param a (Array) the array to append
		  * @param index (uint) the index of the array to start placing the new array
		  * @return the new length of the array
		  */
		 public function appendAt(a:Array,index:uint=0):uint
		 {
		 	append(a);
		 	rotate(((a.length)+index)*-1);
		 	return super.length;
		 }
		/**
		 * allows you to search the array for a specific value, similar to MovieClip.contains()
		 * @param i (*) the value you are searching the array for
		 * @return returns Boolean
		 * @example
		 * if(myArray.contains("my string"))var myString:String = myArray.pluck(myArray.indexOf("my string"));
		 */
		public function contains(i:*):Boolean 
		{
			var index:int = this.indexOf(i);
			return (index != -1) ? true : false;
		}
		
		/**
		 * pull an item out of the array by its index and re-sort the array
		 * @param index (int) the index of the array to pluck
		 * @return the item that was removed from the array
		 */
		public function pluck(index:int):* {
			return super.splice(index,1);
		}
		 
		/**
		 * allows you to cycle an array one step forward, placing the first item at the end of the array
		 * @return returns the new AdvArray
		 */
		public function rotateForward():Array {
			var firstItem:* = super.shift();
			super.push(firstItem);
			return this;
		}
		/**
		 * allows you to cycle an array one step backwards, placing the last item at the beginning of the array
		 * @return returns the new AdvArray
		 */
		public function rotateBackwards():Array {
			var lastItem:* = super.pop();
			super.unshift(lastItem);
			return this;
		}
		/**
		 * allows you to specify a positive or negative value to cycle the array, 0 will do nothing
		 * @param inc (int) positive or negative value for direction and amount to rotate the array
		 * @return returns the new AdvArray
		 */
		public function rotate(inc:int=1):Array {
			if(inc>0) 
			{
				for(var j:int=0;j<inc;j++) rotateForward();
			}
			else if(inc<0)
			{
				for(var k:int=0;k>inc;k--)rotateBackwards();
			}
			return this;
		}
		/**
		 * makes a shallow copy of the current array
		 * Flex3 LiveDocs: In a shallow copy, if the original array has elements that are objects, only the 
		 * references to the objects are copied rather than the objects themselves. The copy points to the same objects as the original does. 
		 * Any changes made to the objects are reflected in both arrays.<http://livedocs.adobe.com/flex/3/html/help.html?content=10_Lists_of_data_6.html>
		 * @return a shallow copy of the current array
		 */
		public function shallowCopy():Array
		{
			return super.concat();
		}
		
		/**
		 * makes a deep copy of the current array
		 * Flex3 LiveDocs: In a deep copy, any objects found in the original array are also copied 
		 * so the the new array does not point to the same objects as does the original array. <http://livedocs.adobe.com/flex/3/html/help.html?content=10_Lists_of_data_6.html>
		 * @return a deep copy of the current array
		 */
		public function clone():Array
		{
    		var myBA:ByteArray = new ByteArray();
    		myBA.writeObject(super);
    		myBA.position = 0;
    		return(myBA.readObject());
		}

		 
	}
}